roblox-cloud

roblox-cloud

使用する場面

タスクの主な内容が、通常のゲームプレイ用スクリプト以外で Roblox Open Cloud または HTTP ベースの連携を扱う場合に、このスキルを使用します。

• Roblox の Web API を呼び出す CI、ボット、Web バックエンド、スクリプト、社内ツールを構築する。
• ユーザー以外による自動化に使用する API キーを選び、エンドポイントに必要なスコープを確認する。
• リクエスト URL、本文、フィルター、ヘッダー、ページネーション、更新マスク、長時間実行オペレーションのポーリングを構成する。
• Open Cloud のエラー、クォータ制限、再試行、レート制限ヘッダーに対応する。
• エクスペリエンス内の HttpService からエンドポイントを利用できるか判断する。
• Roblox の Webhook を Discord、Slack、またはカスタム HTTPS エンドポイントで受信する。
• openapi.json、cloud.docs.json、またはサービス固有の JSON ファイルを読み込み、クライアントを生成したりエンドポイントのメタデータを調査したりする。

タスクの主な内容が次のいずれかの場合は、このスキルを使用しないでください。

• OAuth アプリの登録、認可フロー、トークン交換、更新処理、または委任されたユーザーの同意。
• DataStore または MemoryStore のスキーマ設計、保存アーキテクチャ、またはサーバー間のデータ戦略。
• ゲームプレイのリモート通信、レプリケーション、または一般的な Roblox エンジンのスクリプティング。

判断ルール

• Roblox を HTTP 経由で呼び出したり連携したりする方法が中心的な質問であれば、このスキルを使用します。
• 呼び出し元がサーバー、CI ジョブ、ボット、Webhook ワーカー、またはエンドユーザーの同意を必要としないエクスペリエンス内の自動化である場合は、API キーを優先します。
• 連携にユーザーが許可したアクセス、OAuth 登録、更新トークン、またはユーザーごとの委任認可が必要な場合は、roblox-oauth に引き継ぎます。
• 質問がリクエストの仕組みではなく、永続データのスキーマ、競合、キャッシュ、またはストアシステムの設計に関する内容になった場合は、roblox-data に引き継ぎます。
• ゲームプレイのネットワーク通信、リモート通信、または信頼境界に関する質問は、roblox-networking に引き継ぎます。
• タスクがクラウド連携ではなく、エンジン API の参照のみである場合は、roblox-api に引き継ぎます。
• 正確なパスのテンプレート、スキーマ、スコープ、レート制限、または HttpService の利用可否に関するメタデータが必要な場合は、機械可読な成果物を使用します。
• リクエストにクラウド連携と対象外のアーキテクチャの両方が含まれる場合は、Open Cloud の部分のみを回答し、それ以外は対象外であることを明示します。

手順

1. 呼び出し元と統合先を分類します。
   • 外部バックエンド、CLI、CI、または自動化ワーカー。
   • Webhook 受信先。
   • エクスペリエンス内の HttpService。
2. 境界で使用する認証方式を選択します。
   • ユーザー以外による自動化では、API キーをデフォルトとします。
   • ユーザー固有の委任アクセスが必要な場合は、作業を中断して roblox-oauth に切り替えます。
3. コーディングを始める前に、エンドポイントを確認します。
   • ベース URL とパスのテンプレート。
   • パスパラメーターとクエリパラメーター。
   • 必須のリクエスト本文スキーマ。
   • 必須スコープ。
   • レート制限。
   • 呼び出し元がエクスペリエンス内の場合に HttpService がサポートされているかどうか。
4. ドキュメントに記載されたパターンに従ってリクエストを作成します。
   • パスパラメーターを正確に挿入します。
   • ページ間でページネーションのクエリを一貫させます。
   • JSON 本文には Content-Type: application/json を追加します。
   • API キー認証を使用するリクエストでは x-api-key を送信します。
   • 更新するフィールドにのみ updateMask を使用します。
5. Open Cloud のレスポンス処理を明示的に行います。
   • ページネーションでは nextPageToken を読み取ります。
   • 長時間実行される呼び出しでは、バックオフを使って Operation リソースをポーリングします。
   • Open Cloud の JSON 型を正しく解析します。特に、タイムスタンプ、期間、バイト、フィールドマスク、小数に注意します。
6. 統合の一環としてエラー処理を行います。
   • INVALID_ARGUMENT：ID、フィルター、ヘッダー、本文の形式を確認します。
   • PERMISSION_DENIED または INSUFFICIENT_SCOPE：スコープとリソースへのアクセス権を確認します。
   • RESOURCE_EXHAUSTED または HTTP 429：retry-after がある場合はそれに従い、ない場合は指数バックオフを使用します。
   • UNAVAILABLE などの一時的なエラー：短い間隔でループせず、バックオフを使って再試行します。
7. Webhook では、安全で冪等な受信を設計します。
   • パブリック HTTPS POST エンドポイントを必須とします。
   • 5 秒以内に 2XX を返します。
   • シークレットが設定されている場合は roblox-signature を検証します。
   • NotificationId を使って重複を排除します。
   • 配信は再試行される可能性があり、重複する場合もあるものとして扱います。
8. HttpService では、プラットフォーム固有の追加制約を適用します。
   • 呼び出せるのは、サポート対象の Open Cloud エンドポイントのみです。
   • 使用できるヘッダーは x-api-key と content-type のみです。
   • x-api-key の値には Secret を使用する必要があります。
   • HTTPS のみを使用します。
   • パスパラメーターに .. を含めることはできません。
9. 回答の範囲を守ります。
   • クラウドリクエスト、認証方式の選択、Webhook、HttpService、レート制限、ツールの成果物に焦点を当てます。
   • OAuth の実装詳細、ゲームプレイのネットワーキング、エクスペリエンス内のデータアーキテクチャには話を広げないでください。

リファレンスの使用方法

• Open Cloud とレガシーの呼び出し、エクスペリエンス内の呼び出しとの大まかな違いが必要な場合は、まず references/open-cloud-overview.md を開きます。
• 既知のワークフローに該当し、最適なガイドの出発点が必要な場合は、references/cloud-guides.md を開きます。
• リクエストの作成、ページネーション、フィールドマスク、エラー、スコープ、再試行の動作については、references/api-patterns-errors-types-scopes-and-rate-limits.md を開きます。
• トリガーのサポート、ペイロードの形式、署名の検証、配信の想定については、references/webhooks-documentation.md を開きます。
• Roblox エクスペリエンスからリクエストを送信し、エンドポイントのサポート状況を確認する必要がある場合は、references/http-service.md を開きます。
• 統合 OpenAPI 定義を調査する、またはそれに基づいて生成する必要がある場合は、references/openapi-documentation.md を開きます。
• 操作 ID、スキーマ、スコープ、エンジンでの利用可否に関するメタデータをローカルの JSON 成果物から直接取得する必要がある場合は、references/cloud-reference-json-files.md を開きます。

チェックリスト

• 統合の接続先が、外部自動化、Webhook 受信先、またはゲーム内の HttpService のいずれか特定されています。
• API キーの使用は OAuth を必要としない自動化に限り、OAuth が必要な場合は担当者に引き継いでいます。
• 実装前に、エンドポイントのパス、本文のスキーマ、スコープ、レート制限を確認しています。
• 選択したエンドポイントのページネーション、フィルタリング、updateMask の動作を把握しています。
• 長時間実行される操作は、同期的に完了すると思い込まず、ポーリングしています。
• エラー処理では、無効な入力、権限エラー、クォータ超過に対応しています。
• 再試行ロジックでは、retry-after または指数バックオフを使用しています。
• Webhook は冪等で、署名付きかつ有効期間が限られたものとして扱っています。
• HttpService の呼び出しでは、エンドポイントが対応していることと、ヘッダーの制限を確認しています。
• 回答では、OAuth の実装、データアーキテクチャ、ゲームプレイのネットワーク処理、一般的なエンジンスクリプトには踏み込んでいません。

よくある間違い

• roblox-oauth に切り替えず、ここで OAuth フローを実装する。
• すべての Open Cloud エンドポイントを HttpService から呼び出せると思い込む。
• HttpService から未対応のヘッダーを送信したり、API キーを Secret ではなくプレーンテキストで保存したりする。
• API キーのスコープとクリエイターの権限の両方が重要であることを忘れる。
• ページネーション中にフィルターパラメーターを変更し、400 エラーが発生する。
• Operation のポーリングを無視し、非同期エンドポイントがすぐに完了すると想定する。
• バックオフせず、429 や 503 に対して立て続けに再試行する。
• Webhook が必ず 1 回だけ配信されるものとして扱い、重複排除を省略する。
• 2XX 応答を返す前に Webhook ハンドラーで時間のかかる処理を実行する。
• クラウド連携に関する質問を、セーブデータのスキーマ、ゲームプレイ、リモートセキュリティの設計にまで広げる。

例

API キーを使った外部自動化

• CI ジョブでプレースを公開したり、ユニバースを更新したり、インベントリーアイテムを一覧表示したりする場合は、API キーを使用します。
• エンドポイントのスコープを確認し、リクエスト URL を作成して、安全にバッチ処理できるようレート制限のヘッダーを調べます。

ゲーム内からの Open Cloud 呼び出し

• HttpService:RequestAsync を記述する前に、エンドポイントがエンジンからの使用に対応していることを確認します。
• API キーを Secrets に格納し、x-api-key と content-type のみを送信して、429 にはバックオフで対処します。

Webhook 受信先

• パブリックな HTTPS エンドポイントを設定します。
• roblox-signature を検証し、古いタイムスタンプを拒否し、NotificationId で重複を排除して、速やかに 2XX を返し、イベントを非同期に処理します。