roblox-open-cloud
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseRoblox Open Cloud and HttpService
Roblox Open Cloud 与 HttpService
Base URL: . Prefer Open Cloud endpoints (API key or OAuth 2.0, stable).
Legacy cookie-authenticated web APIs can break without notice — don't build on them.
https://apis.roblox.com*.roblox.comBase URL:。优先使用 Open Cloud endpoint(API key 或 OAuth 2.0,稳定)。
传统的、基于 cookie 认证的 Web API 可能在无预警的情况下失效——不要基于它们进行开发。
https://apis.roblox.com*.roblox.comAuthentication
身份验证
- 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 . Group-owned resources need a key created under the group. Introspect a key with
x-api-key: <key>.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 发送。群组拥有的资源需要使用在群组下创建的 key。可通过
x-api-key: <key>查询 key 信息。POST /api-keys/v1/introspect - OAuth 2.0(authorization code + PKCE):适用于代表其他用户执行操作的应用(第三方工具)。
- 绝不要在游戏脚本、attribute 或客户端代码中附带 key。
Common endpoints (v2 unless noted)
常见 endpoint(除非另有说明,否则为 v2)
| Task | Endpoint |
|---|---|
| Data store entries | |
| Ordered data stores | |
| Memory stores | |
| Cross-server message into live servers | |
| Publish a place file | `POST /universes/v1/{u}/places/{p}/versions?versionType=Published |
| Restart servers (after an update) | |
| Run Luau in a cloud server | |
| Bans | |
| Experience notifications | |
| Secrets store | |
| Configs / experiments | `/creator-configs-public-api/v1/configs/universes/{u}/repositories/{repo}[/draft |
| Universe/place settings | |
| Assets, badges, game passes, developer products, groups, users, inventory | See the Open Cloud reference by feature. |
The authoritative list with scopes and per-endpoint rate limits is the Open Cloud reference
() and its OpenAPI description — check it before writing a client.
create.roblox.com/docs/cloud/reference| 任务 | Endpoint |
|---|---|
| Data store 条目 | |
| 有序 Data store | |
| Memory store | |
| 向 live server 发送跨服消息 | |
| 发布 place 文件 | `POST /universes/v1/{u}/places/{p}/versions?versionType=Published |
| 重启 server(更新后) | |
| 在云 server 中运行 Luau | |
| 封禁 | |
| Experience 通知 | |
| Secrets store | |
| Configs / experiments | `/creator-configs-public-api/v1/configs/universes/{u}/repositories/{repo}[/draft |
| Universe/place 设置 | |
| Assets、badges、game passes、developer products、groups、users、inventory | 按功能参阅 Open Cloud reference。 |
包含 scope 和各 endpoint rate limit 的权威列表是 Open Cloud reference
()及其 OpenAPI description——编写 client 前请先查阅。
create.roblox.com/docs/cloud/referencePatterns
模式
- Pagination: pass ; follow
maxPageSize→nextPageTokenuntil empty.pageToken - Long-running operations: some calls return an operation ; poll
pathuntilGET /cloud/v2/{path}.done - Filtering: query parameter on list endpoints that support it.
filter - Rate limits: read the response headers; on
x-ratelimit-*, 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 (see429).roblox-data-stores - Errors: JSON ; retry only
{ code, message }and429.5xx
bash
undefined- Pagination:传入 ;持续将
maxPageSize作为nextPageToken传递,直至其值为空。pageToken - Long-running operations:部分调用会返回 operation ;轮询
path,直到GET /cloud/v2/{path}。done - Filtering:在支持该参数的 list endpoint 上使用 query parameter。
filter - Rate limits:读取 response header;遇到
x-ratelimit-*时,执行带抖动的指数退避。 Data store 配额由 Open Cloud 和游戏 live server 共享——请限制批量脚本的吞吐,避免其耗尽游戏可用资源(参见429)。roblox-data-stores - Errors:JSON ;仅对
{ code, message }和429进行重试。5xx
bash
undefinedRead one player's data store entry
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"
-H "x-api-key: $ROBLOX_API_KEY"
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"
-H "x-api-key: $ROBLOX_API_KEY"
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"}"}'
-H "x-api-key: $ROBLOX_API_KEY" -H "Content-Type: application/json"
-d '{"topic":"Announcements","message":"{"text":"Update in 5 minutes"}"}'
undefinedcurl -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"}"}'
-H "x-api-key: $ROBLOX_API_KEY" -H "Content-Type: application/json"
-d '{"topic":"Announcements","message":"{"text":"Update in 5 minutes"}"}'
undefinedHttpService 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 ; handle non-2xx (
pcall).response.Success - Store keys in the experience Secrets store (Creator Hub) and read with , which returns an opaque
HttpService:GetSecret(name)usable in headers (andSecret/AddPrefix), not a readable string.AddSuffix - 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
domains are blocked.
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 }In-game, prefer native APIs (, ) 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.
Players:BanAsyncDataStoreService- 启用 Allow HTTP Requests(Experience Settings → Security)。仅限服务器端。
- 限制:每台 server 每分钟对外部 URL 发起 500 次请求;Open Cloud 调用另有每台 server 每分钟 2,500 次的独立配额。始终使用 ;处理非 2xx 响应(
pcall)。response.Success - 将 key 存储在 experience 的 Secrets store(Creator Hub)中,并通过 读取。该方法返回一个不透明的
HttpService:GetSecret(name),可用于 header(以及Secret/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(、),而不是调用 Open Cloud。
未经正当目的和合规审查,绝不要记录或向第三方发送玩家聊天/PII。
Players:BanAsyncDataStoreServiceWebhooks (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-storesroblox-toolingroblox-testingroblox-analytics-liveopsroblox-securityroblox-data-storesroblox-toolingroblox-testingroblox-analytics-liveopsroblox-security