roblox-open-cloud

Roblox Open Cloud と HttpService

ベース URL：https://apis.roblox.com。Open Cloud エンドポイント（API キーまたは OAuth 2.0、安定性あり）を優先してください。 Cookie 認証を使う従来の *.roblox.com Web API は予告なく動作しなくなる可能性があるため、これらを基盤にしないでください。

認証

• API キー（Creator Dashboard → Open Cloud → API Keys）：自分またはグループが所有するリソースや自動化に使用します。ユニバースごとに必要最小限のスコープを付与し、IP 許可リスト（CIDR）と有効期限を設定して、シークレット（CI シークレット、ボールト）として保存し、ヘッダー x-api-key: <key> で送信します。グループ所有のリソースには、グループのもとで作成したキーが必要です。POST /api-keys/v1/introspect でキーをイントロスペクトできます。
• OAuth 2.0（認可コード + PKCE）：他のユーザーに代わって動作するアプリ（サードパーティ製ツール）向けです。
• ゲームスクリプト、属性、クライアントコードにキーを含めないでください。

一般的なエンドポイント（特記がない限り v2）

タスク	エンドポイント
データストアのエントリ	GET/POST /cloud/v2/universes/{u}/data-stores/{ds}/entries, GET/PATCH/DELETE .../entries/{id}, :increment, :listRevisions。スコープは /scopes/{scope}/entries 経由
順序付きデータストア	/cloud/v2/universes/{u}/ordered-data-stores/{ods}/scopes/{scope}/entries[...]
メモリストア	/cloud/v2/universes/{u}/memory-store/sorted-maps/{map}/items, `/queues/{q}/items[:read
稼働中サーバーへのサーバー間メッセージ	POST /cloud/v2/universes/{u}:publishMessage { "topic": "...", "message": "..." }
プレイスファイルの公開	`POST /universes/v1/{u}/places/{p}/versions?versionType=Published
サーバーの再起動（更新後）	POST /cloud/v2/universes/{u}:restartServers
クラウドサーバーで Luau を実行	POST /cloud/v2/universes/{u}/places/{p}[/versions/{v}]/luau-execution-session-tasks
BAN	PATCH /cloud/v2/universes/{u}/user-restrictions/{userId}?updateMask=gameJoinRestriction（スコープ universe.user-restriction:write）、user-restrictions:listLogs
エクスペリエンス通知	POST /cloud/v2/users/{userId}/notifications
シークレットストア	/cloud/v2/universes/{u}/secrets
設定／実験	`/creator-configs-public-api/v1/configs/universes/{u}/repositories/{repo}[/draft
ユニバース／プレイスの設定	GET/PATCH /cloud/v2/universes/{u}, /cloud/v2/universes/{u}/places/{p}
アセット、バッジ、ゲームパス、開発者製品、グループ、ユーザー、インベントリ	機能別の Open Cloud リファレンスを参照してください。

スコープとエンドポイントごとのレート制限を含む正式な一覧は、Open Cloud リファレンス （create.roblox.com/docs/cloud/reference）とその OpenAPI 定義にあります。クライアントを作成する前に確認してください。

パターン

• ページネーション：maxPageSize を指定し、nextPageToken を次の pageToken として渡して、空になるまで続けます。
• 長時間実行オペレーション：一部の呼び出しはオペレーションの path を返します。done になるまで GET /cloud/v2/{path} をポーリングします。
• フィルタリング：対応する一覧エンドポイントでは、クエリパラメーター filter を使用します。
• レート制限：レスポンスヘッダー x-ratelimit-* を確認し、429 の場合はジッターを加えて指数バックオフします。 データストアの使用枠は Open Cloud と稼働中のゲームサーバーで共有されます。ゲームの使用枠を枯渇させないよう、一括処理スクリプトをスロットリングしてください（roblox-data-stores を参照）。
• エラー：JSON { code, message }。再試行するのは 429 と 5xx のみです。
• 従来の Web API（Cookie 認証または IP 認証なし）：2026 年 10 月 19 日以降、バッジ、データストア、ゲーム永続化、インベントリ、サムネイル、ユーザーの各 API の制限が大幅に引き下げられます（多くの場合、毎分 100 リクエスト）。Open Cloud の制限は変更されません。ツールやボットには API キーを使って Open Cloud を利用し、レスポンスをキャッシュしてください。
• サムネイル：2026 年 10 月 26 日以降、未承認または破損したサムネイルは 503 ではなく、error オブジェクトを含む完了済みのオペレーションとともに 200 を返します。response.imageUri を読み取る前に error を確認してください。

# Read one player's data store entry
curl -s "https://apis.roblox.com/cloud/v2/universes/$UNIVERSE_ID/data-stores/PlayerData/entries/User_$USER_ID" \
  -H "x-api-key: $ROBLOX_API_KEY"

# Announce to all live servers (the game subscribes to the "Announcements" topic)
curl -s -X POST "https://apis.roblox.com/cloud/v2/universes/$UNIVERSE_ID:publishMessage" \
  -H "x-api-key: $ROBLOX_API_KEY" -H "Content-Type: application/json" \
  -d '{"topic":"Announcements","message":"{\"text\":\"Update in 5 minutes\"}"}'

ゲーム内の HttpService

• Allow HTTP Requests を有効にします（Experience Settings → Security）。サーバー側でのみ使用できます。
• 制限：外部 URL へのリクエストはサーバーあたり毎分 500 件です。Open Cloud の呼び出しには、サーバーあたり毎分 2,500 件の別枠が設けられています。必ず pcall を使用し、2xx 以外の応答（response.Success）を処理してください。
• キーは Creator Hub のエクスペリエンス Secrets store に保存し、HttpService:GetSecret(name) で読み取ります。このメソッドは、ヘッダー内で使用できる不透明な Secret を返します（AddPrefix／AddSuffix も使用できます）。読み取り可能な文字列ではありません。
• ゲームから呼び出せる Open Cloud エンドポイントは一部のみです（アセット、禁止措置、設定、データストア／メモリストア、メッセージング、通知など。ゲーム内 HTTP ドキュメントの一覧を確認してください）。その他の roblox.com ドメインへの呼び出しはブロックされます。

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

local function postToWebhook(url: string, payload: { [string]: any }): boolean
	local ok, response = pcall(function()
		return HttpService:RequestAsync({
			Url = url,
			Method = "POST",
			Headers = { ["Content-Type"] = "application/json" },
			Body = HttpService:JSONEncode(payload),
		})
	end)
	if not ok then
		warn("HTTP request failed to send:", response)
		return false
	end
	if not response.Success then
		warn(`HTTP {response.StatusCode}: {response.StatusMessage}`)
	end
	return response.Success
end

local function banViaOpenCloud(universeId: number, userId: number, reason: string): boolean
	local ok, response = pcall(function()
		return HttpService:RequestAsync({
			Url = `https://apis.roblox.com/cloud/v2/universes/{universeId}/user-restrictions/{userId}?updateMask=gameJoinRestriction`,
			Method = "PATCH",
			Headers = {
				["Content-Type"] = "application/json",
				["x-api-key"] = HttpService:GetSecret("OpenCloudKey"),
			},
			Body = HttpService:JSONEncode({
				gameJoinRestriction = { active = true, displayReason = reason, privateReason = reason },
			}),
		})
	end)
	return ok and response.Success
end

return { postToWebhook = postToWebhook, banViaOpenCloud = banViaOpenCloud }

ゲーム内では、同じ目的で Open Cloud を呼び出すよりも、ネイティブ API（Players:BanAsync、DataStoreService）を優先してください。 正当な目的があり、コンプライアンス審査を受けていない限り、プレイヤーのチャットや個人を特定できる情報（PII）をサードパーティーに記録または送信しないでください。

Webhook（Roblox → サーバー）

Creator Hub → Account Settings → Webhooks で設定します（最大 5 件。グループゲームの場合はグループ所有者のみ設定できます）。 トリガー：サブスクリプションの購入／更新／キャンセル／返金／再登録、消去権のリクエスト、コマース注文の支払い／返金、取引の返金（開発者製品、パス、プライベートサーバー、有料アクセスに対する Robux の返金／チャージバック。開発者製品の特典はご自身で取り消してください）。 検証の詳細と Node／Python の検証ツール：references/webhooks.md。

関連スキル

roblox-data-stores（予算、スキーマ）、roblox-tooling（CI による公開）、roblox-testing（Luau 実行テスト）、roblox-analytics-liveops（設定、実験）、roblox-security（禁止措置、シークレット）。