メッセージング使用ガイド

Messaging Service APIは、ゲームのサーバーとクライアント間で通信するためのEngine MessagingServiceのOpen Cloud版です。Engine APIでは、メッセージを公開するためのスクリプトを手動でスタジオで記述および更新することしかできませんが、Open Cloud APIでは、外部ツールからライブサーバーにメッセージを送信して、業務ワークフローを自動化および改善できます。

使用法

Messaging Service APIを使用して、サーバー間通信をサポートすることで構築できる便利なツールはいくつかあります。

• アナウンスメントポータル: ウェブポータルは、ゲーム内のすべてのユーザーにアナウンスを送信するのに役立ちます。たとえば、今後のイベント、アップデート、コンペティションの優勝者を発表することができます。ポータルではメッセージを編集し、APIを呼び出してすべてのユーザーまたは選択したユーザーにメッセージを送信するボタンをクリックできます。

• モデレーションシステム: モデレーションシステムは、ゲームを安全に保つのに役立ちます。不適切な行動をするユーザーを検出した場合、特定のユーザーに警告または禁止するためのメッセージを公開できます。また、モデレーションシステムでuser accountsを使用して再参加を防ぐブロックリストにユーザーアカウントを追加することもできます。

• LiveOpsダッシュボード: LiveOpsダッシュボードは、ハロウィンパーティーのようなライブイベントを管理するための便利なツールです。ダッシュボードでは、イベントを事前にコーディングしたり、イベントメッセージを更新したり、準備が整ったときにイベントをトリガーしたり、ゲームのコードを更新せずに特定のユーザーにバーチャルクラウンのような特別アイテムを報酬として付与したりできます。

制限

Messaging Service APIは、Engine MessagingServiceと同じ制限に従います。レート制限は両方のAPIで共有されており、両APIからの使用は同じ制限にカウントされます。

メッセージングのためのトピックをセットアップする

ゲームのライブサーバーにメッセージを公開する前に、カスタマイズされたメッセージチャネルであるトピックをセットアップする必要があります。このトピックは複数のサーバーからアクセス可能です。トピックを定義した後、ユーザーをそのトピックに登録して、受信メッセージを受け取る必要があります。

現在、トピックをスタジオでのみ定義でき、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キーを作成するためにCreator Dashboardに移動し、どこか安全な場所にコピーします。次の設定を行ってください。

   1. Access Permissionsにmessaging-serviceを追加します。
   2. ゲームを選び、universe-messaging-service:publish操作を追加します。

2. ゲームのUniverse IDを取得します：

   1. Creator Dashboardに移動します。

   2. メッセージを公開したいゲームを見つけます。

   3. ゲームのサムネイルにカーソルを合わせ、**⋯**ボタンをクリックし、Copy Universe 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": "皆さん、こんにちは！"
   }'

4. メッセージを公開するためにHTTPリクエストを送信します。

   リクエストが成功すると、HTTP 200と空のレスポンスボディが返されます。

Messaging Service APIをOAuth 2.0アプリに追加する

ユーザーが自分のライブサーバーにメッセージを公開できるOAuth 2.0アプリケーションを作成できます。

Messaging Service APIをアプリケーションで使用し、ユーザーから権限をリクエストするには、次の設定を行います。

1. アプリケーションを登録する際、Permissionsの下で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へのアクセスをリクエストします。アプリケーションは、アクセスToken、クライアントID、シークレットまたはcode challengeを使用して、トークンリソースエンドポイントにPOSTリクエストを送信します。そのリクエストパラメータとして、ユーザーが権限を付与したゲームの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. アプリケーションは、ユーザーが権限を付与したゲームにメッセージを送信できるようになります。リクエストを送信する際には、Authorizationヘッダーにアクセストークンを含め、リクエスト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":"公開するメッセージ"}'

HTTPServiceと共に使用する

このAPIは、HttpServiceでサポートされているOpen Cloudエンドポイントの1つです。このAPIを使用して、ゲーム内の異なるゲーム間でメッセージを公開できます。