傳訊使用指南

傳送服務 API 是開放雲端的引擎MessagingService的對應，可讓您在經體驗的服務器和客戶端之間通訊。引擎 API 只允許您在 Studio 手動寫入和更新腳本以發布訊息，但開放雲端 API 讓您從外部工具發送訊息到生產伺服器來自動化和改進您的操作工作流程。

使用

透過支持跨服務器通訊的消息傳送服務 API，您可以構建多種有用的工具，包括：

• 公告傳送門 : 網站傳送門可能有助於支持向您體驗中的所有服務器發送公告，例如公佈即將發生的事件、更新和比賽的勝者。在門戶上，您可以編輯一個訊息並點擊一個按鈕，呼叫 API 將訊息發送給所有使用者或選擇的使用者。

• 管理系統 ：一個管理系統可以幫助保護您的體驗安全和安全。當偵測到具有不當行為的使用者時，您可以發布一個訊息來啟動體驗伺服器警告或禁止特定使用者。您也可以在管理系統中使用數據儲存來將用戶帳戶添加到屏蔽他們重新加入的黑名單中。

• LiveOps 仪表板 : LiveOps 仪表板是管理實時事件，例如萬聖節派對的有用工具。在面板上，您可以預先編碼事件、更新事件訊息、在準備好時觸發事件，並獎勵選擇的用戶使用特殊物品，例如虛擬皇冠，而不更新任何體驗代碼。

限制

設定一個主題以進行通訊

在發布體驗的實時伺服器上的訊息之前，您必須設定一個 主題 ，這是一個可從多個伺服器存取的自訂訊息通道。定義主題後，您可以訂閱使用者對主題的註冊，以便接收到來自您的來訊。

目前，您只能在 Studio 中定義主題，並使用 Luau API MessagingService:SubscribeAsync() 來訂閱用戶。以下代碼示例訂閱任何使用者加入體驗時的主題：

Set up and Subscribe Users to a Topic
local MessagingService = game:GetService("MessagingService")
local Players = game:GetService("Players")

local function onPlayerAdded(player)
	-- 定義並訂閱主題
	local topic = "YourTopic"
	local connection = MessagingService:SubscribeAsync(topic, function(message)
		print(message.Data)
	end)

	player.AncestryChanged:Connect(function()
		-- 在玩家祖先變更時取消從主題上註冊
		connection:Disconnect()
	end)
end

Players.PlayerAdded:Connect(onPlayerAdded)

發布訊息到生產伺服器

在 設置主題 之後，發布訊息到你體驗的實時伺服器：

1. 在 創作者面板 創建 API 鑰匙，並將其複製到安全的地方。請確認您執行以下設定：

   1. 將 訊息傳送服務 添加到 存取權限 。
   2. 選擇一個體驗，並添加 宇宙訊息傳送服務：發布 操作。

2. 取得 宇宙 ID 以你的體驗：

   1. 導航到 創作者面板。

   2. 找到你想發布訊息的體驗。

   3. 將鼠標懸停在體驗縮略圖上，點擊 ⋯ 按鈕，然後選擇 複製宇宙 ID 。

      

3. 將 API 鑰匙和宇宙添加到 POST 請邀請中，如此示例：

   發佈訊息的例子請求
   curl -L -X POST 'https://apis.roblox.com/cloud/v2/universes/{universe}:publishMessage' \
   -H 'x-api-key: {api-key}' \
   -H 'Content-Type: application/json' \
   --data '{
    "topic": "your-topic",
    "message": "Hello, everyone!"
   }'

4. 發送 HTTP 請求以發布訊息。

   如果您的請求成功，它將返回 HTTP 200 並帶有空白的回應身體。

將訊息傳送服務 API 添加到 OAuth 2.0 應用程式

您可以創建 OAuth 2.0 應用程式，讓使用者發布訊息到自己的生產伺服器。

若要使用訊息傳送服務 API 為應用程式提供支援，並向使用者請求權限，請執行以下設定：

1. 當 註冊您的應用程式 時，在 權限 下，選擇 universe-messaging-service:publish 範圍。

2. 當 執行授權流程 時，包括 universe-messaging-service:publish 在授權 URL 的 scope 參數中，將用戶重新導回到您的應用程式，如下示例：

   https://authorize.roblox.com?client_id=816547628409595165403873012&redirect_uri=https://my-app.com/redirect&scope=openid+universe-messaging-service:publish&response_type=Code&prompts=login+consent&nonce=12345&state=6789

3. 請求使用者想要發布訊息的經驗的 universeId 獲得存取權限。您的應用程式可以將 要求傳送到 代幣資源端點 與使用權代碼、客戶端 ID 和秘密或 ，根據您的授權流程實現，作為要求參數來獲得一個列表的經驗，該用戶已授予許可：

   範例請求
   curl --location --request POST 'https://apis.roblox.com/oauth/v1/token/resources' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'token=<access_token>' \
   --data-urlencode 'client_id=<client_id>' \
   --data-urlencode 'client_secret=<client_secret>'

   此端點返回一個列表 universeIds 像下面的例子回應：

   範例回應
   {
     "resource_infos": [
       {
         "owner": {
           "id": "1516563360",
           "type": "User"
         },
         "resources": {
           "universe": {
             "ids": ["3828411582"]
           }
         }
       }
     ]
   }

4. 您的應用程式現在可以向任何經過使用者授權的體驗發送訊息。當傳送請邀請時，包括使用者代碼在授權標頭中，以及請求 URI 中的 universeId 和主題在下列格式中：

   範例請求
   curl --location --request POST 'https://apis.roblox.com/cloud/v2/universes/{universe}:publishMessage' \
   --header 'Authorization: Bearer <access_token>' \
   --header 'Content-Type: application/json' \
   --data-raw '{"topic": "some-topic","message":"message to publish"}'