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）：用于访问你自己或你所在群组的资源，以及自动化操作。为每个 universe 授予最低限度的作用域，设置 IP 允许列表（CIDR）和过期时间，将密钥作为机密保存（CI 机密、保管库），并通过请求头 x-api-key: <key> 发送。群组拥有的资源需要使用在群组下创建的密钥。使用 POST /api-keys/v1/introspect 检查密钥。
• OAuth 2.0（授权码 + PKCE）：用于代表其他用户操作的应用（第三方工具）。
• 切勿在游戏脚本、属性或客户端代码中发布密钥。

常用端点（除非特别注明，否则为 v2）

任务	端点
Data store 条目	GET/POST /cloud/v2/universes/{u}/data-stores/{ds}/entries、GET/PATCH/DELETE .../entries/{id}、:increment、:listRevisions；作用域通过 /scopes/{scope}/entries 指定
有序 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
向运行中的服务跨服务发送消息	POST /cloud/v2/universes/{u}:publishMessage { "topic": "...", "message": "..." }
发布 place 文件	`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
封禁	PATCH /cloud/v2/universes/{u}/user-restrictions/{userId}?updateMask=gameJoinRestriction（作用域 universe.user-restriction:write）、user-restrictions:listLogs
Experience 通知	POST /cloud/v2/users/{userId}/notifications
Secrets store	/cloud/v2/universes/{u}/secrets
配置 / 实验	`/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}
资源、徽章、游戏通行证、开发者产品、群组、用户、库存	请参阅按功能分类的 Open Cloud 参考文档。

权威端点列表及其作用域和各端点的速率限制见 Open Cloud 参考文档（create.roblox.com/docs/cloud/reference）及其 OpenAPI 描述——编写客户端前请先查阅。

模式

• 分页：传入 maxPageSize；持续传递 nextPageToken → pageToken，直到令牌为空。
• 长时间运行的操作：部分调用会返回操作 path；轮询 GET /cloud/v2/{path}，直到 done。
• 筛选：在支持筛选的列表端点上使用 filter 查询参数。
• 速率限制：读取 x-ratelimit-* 响应头；遇到 429 时，使用带抖动的指数退避。 Data store 配额由 Open Cloud 和运行中的游戏服务共享——对批量脚本进行限流，以免影响游戏（参见 roblox-data-stores）。
• 错误：格式为 JSON { code, message }；仅对 429和5xx` 重试。
• 旧版 Web API（使用 Cookie 或未经身份验证的 IP）：2026 年 10 月 19 日之后，徽章、datastore、game-persistence、inventory、thumbnails 和 users API 的限制将大幅降低（通常降至每分钟 100 次请求）。Open Cloud 的限制不会改变：工具和机器人应使用带 API 密钥的 Open Cloud，并缓存响应。
• 缩略图：从 2026 年 10 月 26 日起，未获批准或损坏的缩略图会返回 200，并附带一个已完成且包含 error 对象的操作（而非 503）；读取 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 的 Experience 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 }

在游戏中，优先使用原生 API（Players:BanAsync、DataStoreService），而不是为同一功能调用 Open Cloud。 未经正当用途评估和合规审查，切勿记录或向第三方发送玩家聊天内容或 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（封禁、密钥）。