消息傳遞使用指南

消息服務 API 是開放雲的等價於引擎的 MessagingService，它允許您在遊戲的伺服器和客戶端之間進行通信。引擎 API 只允許您在 Studio 中手動編寫和更新腳本以發布消息，但開放雲 API 讓您可以從外部工具向線上伺服器發送消息，以自動化和改善您的操作工作流程。

使用方法

您可以通過支持跨伺服器通信來構建幾個有用的工具，這些工具包括：

• 公告門戶：一個網絡門戶可以幫助支持向您遊戲中的所有用戶發送公告，例如宣布即將舉行的活動、更新或比賽的獲勝者。在門戶中，您可以編輯消息並單擊一個按鈕，調用 API 將消息發送給所有用戶或特定用戶。

• 管理系統：管理系統可以幫助保持您的遊戲安全。當檢測到有不當行為的用戶時，您可以發布消息以觸發遊戲伺服器警告或禁止特定用戶。您還可以在管理系統中使用 數據存儲 將用戶帳戶添加到阻止清單中，防止他們重新加入。

• LiveOps 儀表板：LiveOps 儀表板是管理現場活動的有用工具，例如萬聖節派對。在儀表板上，您可以預編碼活動、更新活動消息、在準備好時觸發活動，並向選定的用戶發放如虛擬皇冠等特殊物品，而不需更新任何遊戲代碼。

限制

消息服務 API 遵循與引擎 MessagingService 相同的限制。兩個 API 之間的速率限制是共享的，來自兩個 API 的使用都計入相同的限制。

為消息設置主題

在您可以向遊戲的線上伺服器發布消息之前，您必須設置一個 主題，這是一個可從多個伺服器訪問的自定義消息通道。在定義完主題後，您需要訂閱用戶以接收即將到來的消息。

目前，您只能在 Studio 中定義主題並使用 Luau API MessagingService:SubscribeAsync() 訂閱用戶。以下代碼示例在用戶加入遊戲時將其訂閱到主題：

設置並訂閱用戶到主題
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. 將 messaging-service 添加到 訪問權限。
   2. 選擇一個遊戲，並添加 universe-messaging-service:publish 操作。

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. 在 實施授權流程 時，在將用戶重定向回您應用程序的授權 URL 的 scope 參數中包括 universe-messaging-service:publish，如以下例所示：

   https://apis.roblox.com/oauth/v1/authorize?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。您的應用程序可以向 令牌資源端點 發送 POST 請求，帶上訪問令牌、客戶端 ID 和密鑰或 code challenge，根據您 的授權流程的實現，作為請求參數以獲取用戶授權的遊戲的 universeIds 列表：

   示例請求
   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"}'

與 HTTPService 使用

此 API 是 HttpService 支持的 開放雲端點 之一。您可以使用它在遊戲內部跨不同遊戲發布消息。