訊息傳遞使用指南

*此內容是使用 AI（Beta 測試版）翻譯，可能含有錯誤。若要以英文檢視此頁面，請按一下這裡。

訊息服務 API 是開放雲端相當於引擎 MessagingService 的功能，讓您能夠在您的體驗的伺服器和客戶端之間進行通信。引擎 API 只允許您在 Studio 中手動撰寫和更新腳本以發佈訊息，但開放雲端 API 允許您從外部工具向實時伺服器傳送訊息，以自動化和改善您的操作工作流程。

使用方法

通過支援使用訊息服務 API 進行跨伺服器通信，您可以構建幾個有用的工具，包括：

  • 公告門戶：一個網頁門戶可以幫助將公告傳送給您體驗中的所有伺服器的用戶，例如宣佈即將舉行的活動、更新和比賽的獲勝者。在該門戶上，您可以編輯訊息並點擊按鈕以呼叫 API 向所有用戶或選定的用戶發送訊息。

  • 管理系統：一個管理系統可以幫助保持您的體驗安全。當檢測到用戶的行為不當時，您可以發佈訊息以觸發體驗伺服器警告或禁止該用戶。您還可以在管理系統中使用數據存儲來將用戶帳戶添加到阻止清單，以防止其重新加入。

  • 實時運營儀表板：實時運營儀表板是管理即時事件的有用工具，例如萬聖節派對。在儀表板上，您可以預先編碼事件、更新事件訊息、在準備好時觸發事件，以及為選定的用戶獎勵特殊物品，例如虛擬王冠，而無需更新體驗的任何代碼。

限制

限制描述
速率Roblox 對訊息請求進行限制，限制為 50 + (5 * number_of_players_in_experience)。例如，擁有 20 名玩家的體驗在每分鐘 150 條訊息請求時開始進行限制。
主題大小80 個字符
訊息大小1,024 個字符 (1 KB)

為訊息設置主題

在您能夠向您體驗的實時伺服器發佈訊息之前，您必須設置一個 主題，這是一個可從多個伺服器訪問的自定義訊息通道。在定義主題後，您需要訂閱用戶到該主題，以便接收您的來訊。

目前，您只能在 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 請求以發佈訊息。

將訊息服務 API 添加到 OAuth 2.0 應用

您可以創建OAuth 2.0 應用，允許您的用戶向他們自己的實時伺服器發佈訊息。

要在您的應用中使用訊息服務 API 並向用戶請求權限，執行以下設置：

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

  2. 當實現授權流程時，在將用戶重定向回您應用的授權 URL 的 scope 參數中包含 universe-messaging-service:publish，如下示例所示：

    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 的訪問。您的應用可以向令牌資源端點發送 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"}'

此頁面