消息传递使用指南

消息传递服务 API 是开放云的相当于引擎 MessagingService 的服务，可以让您在体验的服务器和客户端之间进行通信。引擎 API 仅允许您在 Studio 手动编写并更新脚本发布消息，但开放云 API 允许您从外部工具发送消息到实时服务器自动化和优化操作工作流程。

使用

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

公告门户 : 一个网站门户可以帮助支持向您体验中的服务器上的所有用户发送公告，例如宣布即将到来的活动、更新和比赛的获胜者。在门户上，您可以编辑消息并单击调用 API 发送消息给所有用户或选定用户的按钮。
审核系统 : 审核系统可以帮助保护您的体验安全和安全。当检测到具有不当行为的用户时，您可以发布消息以触发体验服务器警告或禁止特定用户。你还可以在审核系统中使用数据存储来将用户帐户添加到屏蔽他们重新加入的列表中。
LiveOps 仪表板 : LiveOps 仪表板是管理实时事件，例如万圣节派对的有用工具。在仪表板上，您可以预编一个事件，更新事件消息，在准备好时触发事件，并奖励选定的用户使用特殊物品，例如虚拟皇冠，而不更新任何体验代验证码。

目前，API只能通过 HTTP 目标活体验服务器。

限制

限制	描述
速率	Roblox 在 50 + (5 * number_of_players_in_experience) 限制消息请求。例如，拥有 20 名玩家的体验开始在每分钟 150 个消息请求限制。
主题大小	80 个字符
消息大小	1,024 个字符 (1 KB)

设置消息主题

在发布消息到体验的实时服务器之前，您必须设置一个主题，这是一个可从多个服务器访问的自定义消息通道。定义了一个主题后，您可以订阅用户到主题以便接收收到的消息。

目前，您只能在 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)

发布消息到实时服务器

在设置一个主题后，发布消息到你的体验实时服务器：

在创建者仪表板上创建 API 密钥并将其复制到安全的地方。请确保您执行以下设置：
1. 将消息服务添加到访问权限。
2. 选择一个体验，并添加宇宙消息服务：发布操作。
获取宇宙 ID 为您的体验：
1. 导航到创建者仪表板。
2. 找到你想发布消息的体验。
3. 将鼠标悬停在体验缩略图上，单击 ⋯ 按钮，然后选择复制宇宙 ID 。

将 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!"
}'

发送 HTTP 请求发布消信息。

如果您的请求成功，它将返回 HTTP 200 并带有空的响应身体。

将消息传递服务 API 添加到 OAuth 2.0 应用程序

您可以创建 OAuth 2.0 应用程序，允许用户发布消息到自己的实时服务器。

通过 OAuth 2.0 支持第三方应用是一个可能在未来版本中进行更改的测试功能。

要使用消息传递服务 API 为您的应用程序提供支持并向用户请求权限，请执行以下设置：

当注册您的应用时，在权限下，选择宇宙消息服务：发布范围。

当实现授权流程时，包括 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

请求访问用户想要发布消息的体验的 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"]
        }
      }
    }
  ]
}

您的应用现在可以向任何经验发送消息，该用户已授予权限。发送请求时，将访问代币包含在授权头中，并将 universeId 和主题包含在请求 URI 中的格式如下：

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

使用

限制

设置消息主题

发布消息到实时服务器

将消息传递服务 API 添加到 OAuth 2.0 应用程序

在此页面