roblox-open-cloud

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Roblox Open Cloud and HttpService

Roblox Open Cloud 与 HttpService

Base URL:
https://apis.roblox.com
. Prefer Open Cloud endpoints (API key or OAuth 2.0, stable). Legacy cookie-authenticated
*.roblox.com
web APIs can break without notice — don't build on them.
Base URL:
https://apis.roblox.com
。优先使用 Open Cloud endpoint(API key 或 OAuth 2.0,稳定)。 传统的、基于 cookie 认证的
*.roblox.com
Web API 可能在无预警的情况下失效——不要基于它们进行开发。

Authentication

身份验证

  • API keys (Creator Dashboard → Open Cloud → API Keys): for your own/your group's resources and automation. Grant the minimum scopes per universe, set an IP allowlist (CIDR) and expiration, store as a secret (CI secret, vault), send as header
    x-api-key: <key>
    . Group-owned resources need a key created under the group. Introspect a key with
    POST /api-keys/v1/introspect
    .
  • OAuth 2.0 (authorization code + PKCE): apps acting on behalf of other users (third-party tools).
  • Never ship keys in game scripts, attributes, or client code.
  • API keys(Creator Dashboard → Open Cloud → API Keys):用于访问你自己或群组的资源以及 自动化。按 universe 授予最小 scope,设置 IP allowlist(CIDR)和 expiration, 将其作为 secret(CI secret、vault)存储,并通过 header
    x-api-key: <key>
    发送。群组拥有的资源需要使用在群组下创建的 key。可通过
    POST /api-keys/v1/introspect
    查询 key 信息。
  • OAuth 2.0(authorization code + PKCE):适用于代表其他用户执行操作的应用(第三方工具)。
  • 绝不要在游戏脚本、attribute 或客户端代码中附带 key。

Common endpoints (v2 unless noted)

常见 endpoint(除非另有说明,否则为 v2)

TaskEndpoint
Data store entries
GET/POST /cloud/v2/universes/{u}/data-stores/{ds}/entries
,
GET/PATCH/DELETE .../entries/{id}
,
:increment
,
:listRevisions
; scopes via
/scopes/{scope}/entries
Ordered data stores
/cloud/v2/universes/{u}/ordered-data-stores/{ods}/scopes/{scope}/entries[...]
Memory stores
/cloud/v2/universes/{u}/memory-store/sorted-maps/{map}/items
, `/queues/{q}/items[:read
Cross-server message into live servers
POST /cloud/v2/universes/{u}:publishMessage
{ "topic": "...", "message": "..." }
Publish a place file`POST /universes/v1/{u}/places/{p}/versions?versionType=Published
Restart servers (after an update)
POST /cloud/v2/universes/{u}:restartServers
Run Luau in a cloud server
POST /cloud/v2/universes/{u}/places/{p}[/versions/{v}]/luau-execution-session-tasks
Bans
PATCH /cloud/v2/universes/{u}/user-restrictions/{userId}?updateMask=gameJoinRestriction
(scope
universe.user-restriction:write
),
user-restrictions:listLogs
Experience notifications
POST /cloud/v2/users/{userId}/notifications
Secrets store
/cloud/v2/universes/{u}/secrets
Configs / experiments`/creator-configs-public-api/v1/configs/universes/{u}/repositories/{repo}[/draft
Universe/place settings
GET/PATCH /cloud/v2/universes/{u}
,
/cloud/v2/universes/{u}/places/{p}
Assets, badges, game passes, developer products, groups, users, inventorySee the Open Cloud reference by feature.
The authoritative list with scopes and per-endpoint rate limits is the Open Cloud reference (
create.roblox.com/docs/cloud/reference
) and its OpenAPI description — check it before writing a client.
任务Endpoint
Data store 条目
GET/POST /cloud/v2/universes/{u}/data-stores/{ds}/entries
、
GET/PATCH/DELETE .../entries/{id}
、
:increment
、
:listRevisions
;通过
/scopes/{scope}/entries
指定 scope
有序 Data store
/cloud/v2/universes/{u}/ordered-data-stores/{ods}/scopes/{scope}/entries[...]
Memory store
/cloud/v2/universes/{u}/memory-store/sorted-maps/{map}/items
、`/queues/{q}/items[:read
向 live server 发送跨服消息
POST /cloud/v2/universes/{u}:publishMessage
{ "topic": "...", "message": "..." }
发布 place 文件`POST /universes/v1/{u}/places/{p}/versions?versionType=Published
重启 server(更新后)
POST /cloud/v2/universes/{u}:restartServers
在云 server 中运行 Luau
POST /cloud/v2/universes/{u}/places/{p}[/versions/{v}]/luau-execution-session-tasks
封禁
PATCH /cloud/v2/universes/{u}/user-restrictions/{userId}?updateMask=gameJoinRestriction
(scope
universe.user-restriction:write
)、
user-restrictions:listLogs
Experience 通知
POST /cloud/v2/users/{userId}/notifications
Secrets store
/cloud/v2/universes/{u}/secrets
Configs / experiments`/creator-configs-public-api/v1/configs/universes/{u}/repositories/{repo}[/draft
Universe/place 设置
GET/PATCH /cloud/v2/universes/{u}
、
/cloud/v2/universes/{u}/places/{p}
Assets、badges、game passes、developer products、groups、users、inventory按功能参阅 Open Cloud reference。
包含 scope 和各 endpoint rate limit 的权威列表是 Open Cloud reference (
create.roblox.com/docs/cloud/reference
)及其 OpenAPI description——编写 client 前请先查阅。

Patterns

模式

  • Pagination: pass
    maxPageSize
    ; follow
    nextPageToken
    →
    pageToken
    until empty.
  • Long-running operations: some calls return an operation
    path
    ; poll
    GET /cloud/v2/{path}
    until
    done
    .
  • Filtering:
    filter
    query parameter on list endpoints that support it.
  • Rate limits: read the
    x-ratelimit-*
    response headers; on
    429
    , back off exponentially with jitter. Data store budgets are shared between Open Cloud and live game servers — throttle bulk scripts so they don't starve the game (see
    roblox-data-stores
    ).
  • Errors: JSON
    { code, message }
    ; retry only
    429
    and
    5xx
    .
bash
undefined
  • Pagination:传入
    maxPageSize
    ;持续将
    nextPageToken
    作为
    pageToken
    传递,直至其值为空。
  • Long-running operations:部分调用会返回 operation
    path
    ;轮询
    GET /cloud/v2/{path}
    ,直到
    done
    。
  • Filtering:在支持该参数的 list endpoint 上使用
    filter
    query parameter。
  • Rate limits:读取
    x-ratelimit-*
    response header;遇到
    429
    时,执行带抖动的指数退避。 Data store 配额由 Open Cloud 和游戏 live server 共享——请限制批量脚本的吞吐,避免其耗尽游戏可用资源(参见
    roblox-data-stores
    )。
  • Errors:JSON
    { code, message }
    ;仅对
    429
    和
    5xx
    进行重试。
bash
undefined

Read one player's data store entry

Read one player's data store entry

Announce to all live servers (the game subscribes to the "Announcements" topic)

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"}"}'
undefined
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"}"}'
undefined

HttpService inside games

游戏内的 HttpService

  • Enable Allow HTTP Requests (Experience Settings → Security). Server-side only.
  • Limits: 500 requests/min per server for external URLs; Open Cloud calls have a separate 2,500/min per server budget. Always
    pcall
    ; handle non-2xx (
    response.Success
    ).
  • Store keys in the experience Secrets store (Creator Hub) and read with
    HttpService:GetSecret(name)
    , which returns an opaque
    Secret
    usable in headers (and
    AddPrefix
    /
    AddSuffix
    ), not a readable string.
  • Only a subset of Open Cloud endpoints can be called from games (assets, bans, configs, data/memory stores, messaging, notifications, and more — check the in-game HTTP docs list). Calls to other
    roblox.com
    domains are blocked.
luau
--!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 }
In-game, prefer native APIs (
Players:BanAsync
,
DataStoreService
) over calling Open Cloud for the same thing. Never log or send player chat/PII to third parties without a legitimate purpose and compliance review.
  • 启用 Allow HTTP Requests(Experience Settings → Security)。仅限服务器端。
  • 限制:每台 server 每分钟对外部 URL 发起 500 次请求;Open Cloud 调用另有每台 server 每分钟 2,500 次的独立配额。始终使用
    pcall
    ;处理非 2xx 响应(
    response.Success
    )。
  • 将 key 存储在 experience 的 Secrets store(Creator Hub)中,并通过
    HttpService:GetSecret(name)
    读取。该方法返回一个不透明的
    Secret
    ,可用于 header(以及
    AddPrefix
    /
    AddSuffix
    ),而不是可读字符串。
  • 只有一部分 Open Cloud endpoint 可从游戏内调用(assets、bans、configs、data/memory stores、messaging、notifications 等——请查看游戏内 HTTP 文档列表)。对其他
    roblox.com
    域的调用会被阻止。
luau
--!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 }
在游戏内,对于相同功能,优先使用原生 API(
Players:BanAsync
、
DataStoreService
),而不是调用 Open Cloud。 未经正当目的和合规审查,绝不要记录或向第三方发送玩家聊天/PII。

Webhooks (Roblox → your server)

Webhooks(Roblox → 你的服务器)

Configure in Creator Dashboard → Webhooks. Triggers: subscription purchased/renewed/cancelled/refunded/ resubscribed, right-to-erasure requests, commerce order paid/refunded, transaction refunded. Verification details and a Node/Python verifier: references/webhooks.md.
在 Creator Dashboard → Webhooks 中配置。触发器:订阅已购买/续订/取消/退款/重新订阅、 删除权(right-to-erasure)请求、commerce order 已支付/已退款、transaction 已退款。 验证细节和 Node/Python verifier:references/webhooks.md。

Related skills

相关 skill

roblox-data-stores
(budgets, schema),
roblox-tooling
(CI publishing),
roblox-testing
(Luau execution tests),
roblox-analytics-liveops
(configs, experiments),
roblox-security
(bans, secrets).
roblox-data-stores
(预算、schema)、
roblox-tooling
(CI 发布)、
roblox-testing
(Luau 执行测试)、
roblox-analytics-liveops
(configs、experiments)、
roblox-security
(封禁、secrets)。