消息传递使用指南

消息服务 API 是开放云的等价于引擎的 MessagingService，它允许您在游戏的服务器和客户端之间进行通信。引擎 API 仅允许您在 Studio 中手动编写和更新脚本以发布消息，但开放云 API 允许您通过外部工具向实时服务器发送消息，以自动化和改善您的操作工作流程。

使用方法

通过支持与消息服务 API 的跨服务器通信，您可以构建多个有用的工具，包括：

• 公告门户：一个网络门户可以帮助支持向您游戏中的所有用户发送公告，例如宣布即将举行的活动、更新以及竞赛的获胜者。在门户上，您可以编辑消息并单击一个按钮调用 API，将消息发送给所有用户或选定用户。

• ** moderation 系统**：一个 moderation 系统可以帮助保持您的游戏安全。当检测到用户有不当行为时，您可以发布一条消息以触发游戏服务器警告或禁用特定用户。您还可以在 moderation 系统中使用 数据存储 将用户账户添加到黑名单，以防止他们重新加入。

• 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. 在 Creator Dashboard 上 创建 API 密钥 并将其安全地复制到某个地方。确保您执行以下设置：

   1. 将 messaging-service 添加到 访问权限。
   2. 选择一个游戏，并添加 universe-messaging-service:publish 操作。

2. 获取您游戏的 Universe ID：

   1. 导航到 Creator Dashboard。

   2. 找到您希望发布消息的游戏。

   3. 将鼠标悬停在游戏的缩略图上，单击 ⋯ 按钮，并选择 复制 Universe ID。

      

3. 将 API 密钥和 universe 添加到 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 支持的 开放云端点 之一。您可以使用它从一个游戏跨多个游戏发布消息。