roblox-open-cloud

roblox-open-cloud

Open Cloud は、Roblox リソース向けの REST API です。ゲームサーバーを実行せずに、ライブゲームサーバーが使用するものと同じリソースを読み書きするコマンドラインツール、ウェブアプリ、CI/CD パイプライン、スケジュール済みジョブ、外部自動化を構築できます。

関連項目：

• roblox-datastores/SKILL.md：エンジン内の DataStore API。Open Cloud Data Stores は外部から利用する対応機能です。
• roblox-gamepasses/SKILL.md：ゲームパス、開発者製品、サブスクリプションにも Open Cloud の管理エンドポイントがあります。
• roblox-networking/SKILL.md：HttpService を使ったエクスペリエンス内の HTTP 通信と、送信リクエストに関するセキュリティモデルについて説明します。
• roblox-core/SKILL.md：サービス、HttpService、スクリプトコンテキストについて説明します。

認証

認証方式は次の 3 つです。上から順に推奨度が高くなります。

1. API キー（ほとんどの自動化で推奨）

すべての Open Cloud API は、API キー文字列を含む x-api-key ヘッダーを受け付けます。Creator Dashboard → API Keys ページでキーを作成してください。

• キーのアクセス範囲は、キーを所有するユーザーの権限によって決まります。そのユーザーがアクセスできるリソースにはすべてアクセスでき、個人のエクスペリエンスや、適切なロールを持つグループ所有のエクスペリエンスも含まれます。
• 特定のエクスペリエンスに制限できるスコープもありますが、すべてのスコープが対象ではありません。
• ベストプラクティス（公式ドキュメントより）：
  • 影響範囲を分離するため、アプリケーションごとに別々のキーを作成してください。
  • 必要な最小限の権限を選択し、可能な場合はスコープを特定のエクスペリエンスに制限してください。
  • IP 制限（CIDR 表記）を使用してください。ただし、Roblox のゲームサーバーから呼び出す場合は使用しないでください（Roblox サーバーの IP は不明で、予測できません）。
  • 短期間使用するキーには有効期限を設定してください。ローテーションの手順がない場合は、長期間の使用を避けてください。
  • キーをソース管理、スクリプト、公開チャンネルに絶対に保存しないでください。シークレットマネージャーを使用してください。Roblox のプレースではSecrets Storeを使用してください。
  • グループ所有のリソースには、対象グループへのアクセス権のみを持つ専用の別アカウントを作成し、そのアカウントでキーを生成してください。グループの自動化に個人アカウントのキーを使用しないでください。

2. OAuth 2.0（ほかのユーザーに代わってアプリが操作する場合）

自分以外の Roblox ユーザーに代わってアプリを操作する必要がある場合は、OAuth 2.0 を使用してください（例：クリエイターがログインするサードパーティ製ツール）。https://create.roblox.com/docs/cloud/auth/oauth2-overview を参照してください。より強力な安定性の保証があり、定期的に更新されます。

3. レガシー Cookie 認証（使用を避けてください）

レガシー API は Cookie ベースの認証を使用します。予告なく動作しなくなる可能性があり、安定性の保証も最小限です。**本番環境での使用は推奨されません。**不具合が許容される、単発の社内ツールに限って使用してください。

API キーのライフサイクル

API キーには次のステータスがあります（公式ドキュメントより）。

ステータス	理由	解決方法
Active	問題はありません。	該当なし
Disabled	Enable Key をオフにしました。	再度オンにしてください。
Expired	有効期限が過ぎました。	削除するか、新しい有効期限を設定してください。
Auto-Expired	60 日間、未使用または変更なし（有効期限を設定していない場合も含む）。	無効にしてから再度有効にするか、いずれかのプロパティを更新してください。
Revoked	グループキーの場合：キーを生成したアカウントがグループへのアクセス権を失いました。	キーを再生成してください。
Moderated	Roblox の管理者がセキュリティ上の理由でキーシークレットを変更しました。	再生成してください。
User Moderated	キーを生成したアカウントがモデレーション対象になっています。	モデレーションを解決してください。

60 日間の自動失効は、最もよくある想定外の問題です。設定したまま放置したキーは、通知なく機能しなくなります。定期的に使用するか、ローテーションやリマインダーの仕組みを構築してください。

Introspect エンドポイント

POST https://apis.roblox.com/api-keys/v1/introspect は、呼び出し元の IP からキーを使用できるかどうかと、キーまたはユーザーがモデレーション対象になっているかどうかを検証します。「キーが機能しない理由」をデバッグするのに便利です。

curl --location --request POST 'https://apis.roblox.com/api-keys/v1/introspect' \
--header 'Content-Type: application/json' \
--data '{"apiKey": "your-api-key"}'

キー名、認可されたユーザー、スコープ（userId／groupId／universeId／universeDatastore のリソース識別子を含みます。* はその種類のすべてのリソースを意味します）、enabled、expired、expirationTimeUtc を返します。

エンドポイント一覧

ベース URL：https://apis.roblox.com/cloud/v2/...（および、アセット用のレガシーパス apis.roblox.com/<feature>/v1/... がいくつかあります）。すべての v2 エンドポイントで x-api-key を使用できます。

データストアとメモリストア（最もよく使われる領域）

データストア（/cloud/v2/universes/{universe_id}/data-stores/...）：

• ListDataStores、SnapshotDataStores（毎日のスナップショットをトリガーします）。
• ListDataStoreEntries、CreateDataStoreEntry、GetDataStoreEntry、UpdateDataStoreEntry、IncrementDataStoreEntry、DeleteDataStoreEntry。
• ListDataStoreEntryRevisions（エントリごとのバージョン履歴）。
• /data-stores/{data_store_id}/scopes/{scope}/entries/... 以下のスコープ指定バリアント。
• レート制限（v2）： エンジン内 API と同じエクスペリエンスのデータストアリクエスト予算を共有します（読み取り／書き込み／一覧表示／削除の上限は同時ユーザー数に応じて変動します）。エラーコードと制限を参照し、外部からの呼び出しにはレート制限を設けてください（一定間隔またはリーキーバケット方式）。Open Cloud に別途無制限の枠があると想定しないでください。
• レガシー v1（/datastores/v1/、/ordered-data-stores/v1/）：2026 年 7 月 29 日以降、スロットリングガイドにある固定の非スケーリングテーブルが適用されるのは、これらのレガシーパスのみです。

メモリストア（/cloud/v2/universes/{universe_id}/memory-stores/...）：

• ソート済みマップ：ListMemoryStoreSortedMapItems、CreateMemoryStoreSortedMapItem、GetMemoryStoreSortedMapItem、UpdateMemoryStoreSortedMapItem、DeleteMemoryStoreSortedMapItem。
• キュー：CreateMemoryStoreQueueItem、ReadMemoryStoreQueueItems、DiscardMemoryStoreQueueItems。
• FlushMemoryStore（universe.memory-store:flush が必要です）。

順序付きデータストア（/cloud/v2/universes/{universe_id}/ordered-data-stores/...）：

• ListOrderedDataStoreEntries、CreateOrderedDataStoreEntry、GetOrderedDataStoreEntry、UpdateOrderedDataStoreEntry、IncrementOrderedDataStoreEntry、DeleteOrderedDataStoreEntry。
• 標準のデータストア v2 と同じ、エクスペリエンスで共有される予算モデルです（エラーコードのページを参照してください）。

ユニバースとプレース

• GetUniverse、UpdateUniverse。
• PublishUniverseMessage（ユニバース内のすべてのサーバーにメッセージを公開します。MessagingService の外部向けの対応機能です）。
• RestartUniverseServers（ユニバース内の稼働中のサーバーをすべて再起動します）。
• GetPlace、UpdatePlace（プレースのバージョンを公開します。CI/CD の基本機能です）。
• GetInstance、UpdateInstance。

アセット

• GetAsset、ListAssetVersions、GetAssetVersion（v1 パス：apis.roblox.com/assets/v1/assets/{assetId}）。
• アセット API によるアセット（画像、音声、モデル）のアップロード。コンテンツの一括インポートに便利です。

ユーザーとインベントリ

• GetUser、GenerateUserThumbnail。
• ListInventoryItems。

グループ

• GetGroup、ListGroupMemberships、UpdateGroupMembership、ListGroupRoles、GetGroupRole、ListGroupJoinRequests、AcceptGroupJoinRequest、DeclineGroupJoinRequest、GetGroupShout。

収益化（roblox-gamepasses との相互参照）

• ゲームパス：CreateGamePass、UpdateGamePass、GetGamePassConfig、ListGamePassConfigsByUniverse。
• デベロッパー製品：CreateDeveloperProduct、UpdateDeveloperProduct、GetDeveloperProductConfig、ListDeveloperProductConfigsByUniverse。
• サブスクリプション：サブスクリプション用エンドポイントで管理します。cancelled／purchased／refunded／renewed の Webhook イベントがあります。

モデレーションと禁止措置

• ListUserRestrictions、GetUserRestriction、UpdateUserRestriction（プレースおよびユニバースのスコープ）、ListUserRestrictionLogs。

Luau の実行

• CreateLuauExecutionSessionTask（エンジンの外部からユニバース／プレースに対して Luau を実行します。特権的な操作として扱ってください）。

通知と設定

• CreateUserNotification（エクスペリエンスの外部からユーザーに通知を送信します）。
• 設定（CreatorConfigs）：GetConfigRepositoryValues、ライブ設定のドラフト／公開／リビジョンのワークフロー。

クリエイターストア

• CreateCreatorStoreProduct、GetCreatorStoreProduct、UpdateCreatorStoreProduct、CreatorStoreAssetsSearch。

最新の一覧については、https://create.roblox.com/docs/en-us/cloud をご覧ください（新しいエンドポイントが定期的に追加されます）。

エクスペリエンス内から HttpService で Open Cloud を呼び出す

Open Cloud の一部のエンドポイントは、HttpService を介して稼働中のゲームサーバー内から呼び出せます。これにより、エクスペリエンスから離れることなく、外部のトリガーを使ってグループメンバーシップを更新したり、ユーザーをキックしたりできます。

要件：

• Experience Settings で Allow HTTP Requests を有効にします。
• API キーは Secrets Store を使って Secret として保存する必要があります。HttpService:GetSecret("APIKey") で取得してください。スクリプトにキーをハードコードしないでください。
• 許可されるヘッダーは x-api-key と content-type のみです。
• x-api-key の値は文字列ではなく、Secret データ型である必要があります。
• URL パスパラメーターで .. 文字列は使用できません（そのため、HttpService から .. を含むデータストア／エントリにはアクセスできません）。
• HTTPS のみ使用できます。1024 未満のポートは 80／443 を除いて使用できません。ポート 1194 はブロックされています。

レート制限（ゲームサーバーごと）：

• サーバーごとに、Open Cloud リクエストは毎分 2500 件までです。上限を超えると、リクエストメソッドが約 30 秒間停止し、pcall が "Number of Open Cloud requests exceeded limit." というエラーで失敗する場合があります。
• Open Cloud リクエストは、一般 HTTP リクエストの別枠の上限（毎分 500 件）にはカウントされません。
• 呼び出し元の場所にかかわらず、各エンドポイントにはキー所有者ごとの制限も適用されます。

例：エクスペリエンスからグループメンバーシップを更新します。

--!strict
local HttpService = game:GetService("HttpService")

local function updateGroupMembership(groupId: string, membershipId: string, roleId: string)
    local response
    local ok, err = pcall(function()
        response = HttpService:RequestAsync({
            Url = `https://apis.roblox.com/cloud/v2/groups/{groupId}/memberships/{membershipId}`,
            Method = "PATCH",
            Headers = {
                ["Content-Type"] = "application/json",
                ["x-api-key"] = HttpService:GetSecret("APIKey"), -- Secret, not string
            },
            Body = HttpService:JSONEncode({ role = `groups/{groupId}/roles/{roleId}` }),
        })
    end)
    if not ok then
        warn("HTTP request failed:", err)
        return false
    end
    if response.Success then
        print("Updated:", response.StatusCode, response.StatusMessage)
        return true
    end
    warn("Error:", response.StatusCode, response.StatusMessage)
    return false
end

ベストプラクティス： すべての処理を pcall で囲みます。安全な読み取りはデフォルトで再試行し、変更処理はエンドポイント固有の冪等性の仕様に従ってのみ再試行します。429 が返された場合は、上限付きの指数バックオフの前に retry-after、次に x-ratelimit-reset に従います。最後のレスポンス／エラーは常に保持し、最後の試行後にスリープしないでください。可能であればバルクエンドポイントにまとめます。HTTP/2 に依存してください（自動で使用されますが、ヘッダー名は小文字で送信してください）。Observability Dashboard（Creator Hub → Monitoring）では、HttpService の呼び出しのリクエスト数とレスポンス時間を確認できます。

Webhook

Open Cloud は、subscription イベント（cancelled、purchased、refunded、renewed など）を含む特定のイベントについて Webhook を送信します。アプリに Webhook エンドポイントを設定し、Cloud API を介して登録すると、Roblox がイベントのペイロードを POST します。これは、GetUserSubscriptionPaymentHistoryAsync をポーリングせずにサブスクリプションの分析情報を取得するためのリアルタイム手段です。https://create.roblox.com/docs/en-us/cloud/webhooks/webhook-notifications をご覧ください。

Transaction Refunded トリガーは、サブスクリプションイベントとは別のものです。developer products、パス、プライベートサーバー、有料アクセスが対象ですが、サブスクリプションは対象外です。ペイロードには、購入者、商品タイプと ID、Robux 額（購入者が支払った金額ではなく、商品の元の価格）、ユニバースとプレース、取引 ID またはレシート ID、返金時刻が含まれます。パスまたはアバターアイテムが返金された場合、Roblox によって自動的に取り消されます。developer product の特典はエクスペリエンスのコード内でのみ適用されるため、この通知を受け取ったら、プレイヤーデータから手動で削除してください。

2026 年 10 月の返金トリガーに関する注記は、2 回目の人によるレビュー（クリティカルティア）待ちの実験的なガイダンスです。これに依存する前に、テスト購入でペイロードを確認してください。

判断フロー：エンジン内かOpen Cloudか

必要なこと	使用するもの
サーバー稼働中に通常のプレイヤーデータを読み書きする	エンジン内の DataStoreService
外部からの一括移行、クリーンアップ、RTBFによる削除	Open Cloud Data Stores
リスクのある公開前に毎日スナップショットをスケジュールする	Open Cloud SnapshotDataStores
設定変更後にすべてのサーバーを再起動する	Open Cloud RestartUniverseServers
CIからプレイスを公開する	Open Cloud UpdatePlace
多数のアセットをプログラムでアップロードする	Open Cloud Assets
エクスペリエンス内からグループのロールを更新する	HttpService + Open Cloud UpdateGroupMembership
エクスペリエンス外のユーザーに通知を送信する	Open Cloud CreateUserNotification
リアルタイムのサブスクリプションイベント分析	Open Cloud Webhook
エクスペリエンス内で通常の収益化プロンプト／付与を行う	エンジン内の MarketplaceService
ゲームパス／開発者製品の設定を外部から管理する	Open Cloud game passes / developer products

セキュリティチェックリスト

• キーはシークレットマネージャーまたはSecrets Storeに保管し、ソース／スクリプトには絶対に保存しないでください。
• 権限スコープは最小限にし、可能な場合はエクスペリエンスに制限してください。
• Robloxサーバー以外から呼び出す場合は、IP制限を設定してください。
• 短期キーには有効期限を設定し、長期キーにはローテーション手順を用意してください。
• グループリソースには専用の自動化アカウントを使用してください（個人アカウントは使用しないでください）。
• HttpService からアクセスする必要があるデータストアキーには .. を含めないでください。
• すべての呼び出しをpcallで囲んでください。読み取りは安全に再試行し、変更操作の再試行には明示的な冪等性を必須にしてください。
• HttpService から x-api-key を文字列ではなく Secret として渡してください。
• introspectエンドポイントとObservability Dashboardでキーの使用状況を監査してください。
• 未使用のキーは無効化／削除してください（いずれにせよ60日後に自動的に期限切れになりますが、それだけを唯一のクリーンアップ方法として当てにしないでください）。
• CreateLuauExecutionSessionTask は特権機能として扱ってください。これはLuauをユニバースに対して実行します。

よくある間違い

• 本番環境でレガシーなCookie認証APIを使用する（予告なく動作しなくなることがあります）。
• APIキーをスクリプトまたはソース管理に保存する。
• グループの自動化に個人アカウントのキーを使用する（キーが漏えいすると、すべてのリソースが危険にさらされます）。
• バッチ処理を行わずに HttpService のOpen Cloud上限である2500リクエスト／分に達する。
• クライアント側のレートリミッターを使用せずにOpen Cloud v2 Data Storeの一括ジョブを実行する（エクスペリエンスで共有される予算により、稼働中のサーバーがスロットリングされます）。
• HttpService からデータストアキーの .. が使えると思い込む（使えません）。
• 60日後の自動期限切れを忘れ、自動化が気付かないうちに停止する。
• エンジン内APIですでに実現できることにOpen Cloudを使用する（不要な外部依存とレイテンシが発生します）。

進め方

1. タスクがエンジン内か外部かを確認します。外部の場合はOpen Cloudを使用します。
2. タスクに必要な最小限のスコープでAPIキーを作成します。グループ所有の場合は専用アカウントを使用します。
3. HttpService から呼び出す場合はキーをSecrets Storeに保存し、それ以外の場合はシークレットマネージャーに保存します。
4. introspectエンドポイントと単一のGETリクエストでテストします。
5. pcall、ヘッダーを考慮したレート制限、メソッド／エンドポイントを考慮した再試行を用いてワークフローを構築します。一括処理にはバッチエンドポイントを優先してください。
6. リアルタイムで受け取りたいイベント（サブスクリプション）にはWebhookを設定します。
7. Observability Dashboardで監視し、自動的に期限切れになる前にキーをローテーション／置き換えます。

参考資料

• https://create.roblox.com/docs/en-us/cloud
• https://create.roblox.com/docs/en-us/cloud/auth/api-keys
• https://create.roblox.com/docs/cloud/auth/oauth2-overview
• https://create.roblox.com/docs/en-us/cloud-services/http-service
• https://create.roblox.com/docs/en-us/cloud/reference/rate-limits
• https://create.roblox.com/docs/cloud-services/data-stores/error-codes-and-limits (Open Cloud v2 Data Storeの共有予算)
• https://create.roblox.com/docs/cloud/guides/data-stores/throttling (レガシーv1 Data Storeの制限)
• https://create.roblox.com/docs/en-us/cloud/webhooks/webhook-notifications
• https://create.roblox.com/docs/en-us/cloud-services/secrets

参考インデックス

• auth-and-keys.md：API キー、OAuth、スコープ、またはキーのローテーションを設定します。
• calling-from-in-experience.md：HttpService を通じて対応する Open Cloud エンドポイントを呼び出し、リトライを処理します。