使用消息指南

消息服务 API 是 Open Cloud 的 Lua MessagingService 的替代，可以让您通过服务器或客户端实例的体验通信。Lua API 只允许您在 Studio 中手动写入和更新脚本，但 Open Cloud API 允许您向 Live 服务器发送消息，从外部工具发布消息自动优化您的体验操作工作流程。

使用

您可以通过支持跨服务器通信使用 Messaging Service API 构建的几个有用工具，包括：

• 公告传送门 ： 网站传送门可以帮助您支持向所有服务器的用户发送公告，例如宣布即将发生的事件、更新和比赛的胜利者。 在传送门上，您可以编辑一条消息，然后单击一个按钮，将 API 调用发送给所有用户或选定用户。

• 管理系统 : 管理系统可以帮助保护您的体验安全和安全。当检测到用户有不当行为时，您可以发布消息来触发体验服务器警告或禁止特定用户。您还可以在管理系统中支持数据存储，以便在用户重新加入时阻止他们。

• 生活营销仪表板 : 生活营销仪表板是一个有用的工具来管理实时事件，例如一个万圣节派对。 在生活营销仪表板上，您可以预订一个事件、更新事件消息、触发事件准备好，并向选定的用户提供特殊物品，例如一个虚拟皇冠，无需更新任何体验代验证码。

限制

限制 | 描述 --- | --- 率 | Roblox 对通信请求限制 50 + 5 每分钟, 其中 n 是体验中的玩家数量。 例如, 20 个玩家的体验开始于 150 个消息请求每分钟, 其中 n

设置一个主题进行消息发送

在发布消息到您的体验的所有活跃服务器之前，您需要设置一个 主题 ，这是一个可以从多个服务器访问的自定义消息频道。在定义一个 主题 之后，您需要订阅用户到 主题 接收您的进入的消息。

目前，您只能在 Studio 中定义一个主题，并使用 Lua 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 钥匙。请确保您执行以下设置：

2. 将 消息服务 添加到 访问权限 。

3. 添加 发布 操作到您选择的体验。

4. 获取 宇宙ID ，用于发送您的消息的体验的识别器。

   1. 导航到创建者仪表板。

   2. 找到您想要发布消息的体验。

   3. 点击目标体验缩略图上的 ⋯ 按钮，显示选项列表，然后选择 复制宇宙ID 。

      

5. 在 x-api-key 头称示例中，将 API 钥匙添加到 POST 请求的 API 头中：

   发布消息的示例请求
   curl \
   --location \
   --request POST \
   'https://apis.roblox.com/messaging-service/v1/universes/{universeId}/topics/{topic}' \
   -H 'x-api-key: abc...' \
   -H 'Content-Type: application/json' \
   --data-raw '{"message":"message to publish"}'

   如果您的请求成功，它将返回一个空的响应身体。

6. 调用 API 发送消息。

将 Messaging Service API 添加到 OAuth 2.0 应用

您可以创建OAuth 2.0 应用程序，支持 Messaging Service API 来允许您的用户通过您的 OAuth 2.0 应用程序发布消息到实时服务器。

要使用 Messaging Service API 为您的应用程序和请求权限，请执行以下设置：

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

2. 当 实现授权流程 时，包括 universe-messaging-service:publish 在 scope 参数的授权 URL，该 URL 将用户重新定向到您的应用程序，例如以下示例：

   https://www.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 和秘密或 1> code 挑战</

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

   此端口返回一个类似于以下示例回应的列表：

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

4. 您的应用现在可以向任何用户授权的体验发送消息。在发送请求时，包括访问代币在授权头中，并在请求 URL 中包含 universeId 和主题。在下列格式中包含请求 HTTP 中的访问代码和主题：

   示例请求
   curl --location --request POST 'https://apis.roblox.com/messaging-service/v1/universes/{universeId}/topics/{topic}' \
   --header 'Authorization: Bearer <access_token>' \
   --header 'Content-Type: application/json' \
   --data-raw '{"message":"message to publish"}'