roblox-open-cloud

roblox-open-cloud

Open Cloud 是 Roblox 资源的 REST API 接口。它让你能够构建命令行工具、Web 应用、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、脚本上下文。

身份验证

三种身份验证模型，按优先级排列：

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. legacy cookie auth（避免使用）

旧版 API 使用基于 Cookie 的身份验证，可能会在没有通知的情况下失效，且稳定性保障有限。**不建议用于生产环境。**仅用于可以接受故障的一次性内部工具。

API 密钥生命周期

API 密钥有以下状态（摘自官方文档）：

状态	原因	解决方法
Active	无问题。	不适用
Disabled	你关闭了 Enable Key。	重新开启。
Expired	已过期。	移除过期时间或设置新的过期时间。
Auto-Expired	连续 60 天未使用或修改（即使未设置过期时间）。	先禁用再重新启用，或更新任意属性。
Revoked	群组密钥：生成密钥的账号失去了群组访问权限。	重新生成密钥。
Moderated	Roblox 管理员出于安全原因更改了密钥机密。	重新生成密钥。
User Moderated	生成密钥的账号受到审核处理。	解决审核问题。

60 天后自动过期是最常见的意外情况：设置后忘记使用的密钥会悄无声息地停止工作。请定期使用密钥，或建立轮换／提醒流程。

Introspect endpoint

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）：**与体验中的 Data Store 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。
• 与标准 Data Stores v2 使用相同的体验共享预算模型（请参阅错误代码页面）。

Universe 和地点

• GetUniverse、UpdateUniverse。
• PublishUniverseMessage（向某个 universe 的所有服务端发布消息；这是 MessagingService 的外部对应项）。
• RestartUniverseServers（重启某个 universe 的所有运行中服务端）。
• 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。
• 订阅：通过订阅端点管理；Webhook 事件包括 cancelled/purchased/refunded/renewed。

内容审核和封禁

• ListUserRestrictions、GetUserRestriction、UpdateUserRestriction（按地点和 universe 限定范围）、ListUserRestrictionLogs。

Luau 执行

• CreateLuauExecutionSessionTask（在引擎外对某个 universe/place 运行 Luau；请将其视为特权操作）。

通知和配置

• CreateUserNotification（在体验外向用户发送通知）。
• 配置（CreatorConfigs）：GetConfigRepositoryValues，以及用于实时配置的草稿/发布/修订流程。

创作者商店

• CreateCreatorStoreProduct、GetCreatorStoreProduct、UpdateCreatorStoreProduct、CreatorStoreAssetsSearch。

请参阅 https://create.roblox.com/docs/en-us/cloud，查看完整且最新的列表（定期添加新端点）。

在体验内通过 HttpService 调用 Open Cloud

部分 Open Cloud 端点可通过 HttpService 从运行中的游戏服务端内部调用。借助此方式，你可以在不离开体验的情况下，通过外部触发器执行更新群组成员资格或踢出用户等操作。

要求：

• 在体验设置中启用 允许 HTTP 请求。
• API 密钥必须通过 Secrets Store 存储为 Secret。使用 HttpService:GetSecret("APIKey") 获取。切勿在脚本中硬编码密钥。
• 仅允许使用 x-api-key 和 content-type 标头。
• x-api-key 的值必须是 Secret 数据类型，而不能是字符串。
• URL 路径参数中不允许使用字符串 ..（因此无法通过 HttpService 访问包含 .. 的数据存储/条目）。
• 仅支持 HTTPS；除 80/443 外，禁止使用低于 1024 的端口；端口 1194 已封锁。

速率限制（每个游戏服务端）：

• 每个服务端每分钟最多 2500 个 Open Cloud 请求。超出限制会导致请求方法停顿约 30 秒，且 pcall 可能失败并返回 "Number of Open Cloud requests exceeded limit."。
• Open Cloud 请求不会计入单独的每分钟 500 次常规 HTTP 请求限制。
• 每个端点还设有按密钥所有者计算的限制，无论调用来自何处都会执行。

示例：从体验中更新群组成员资格。

--!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 会针对某些事件发送 webhook，包括订阅事件（cancelled、purchased、refunded、renewed）。在应用中设置 webhook 端点，通过 Cloud API 注册该端点，随后 Roblox 会向其 POST 事件负载。对于订阅分析，这是无需轮询 GetUserSubscriptionPaymentHistoryAsync 的实时途径。请参阅 https://create.roblox.com/docs/en-us/cloud/webhooks/webhook-notifications。

Transaction Refunded 触发器与订阅事件彼此独立。它涵盖开发者产品、通行证、私人服务器和付费访问，但不包括订阅。其负载包含买家、产品类型和 ID、Robux 金额（产品原价，而非买家支付的金额）、universe 和 place、交易或收据 ID，以及退款时间。退款的通行证或虚拟形象物品会由 Roblox 自动撤销；退款的开发者产品所提供的权益仅存在于你的体验代码中，因此收到此通知时，请自行从玩家数据中移除这些权益。

2026 年 10 月的退款触发器说明属于实验性指南，尚待第二位人工审核者审核（关键级别）。请先通过测试购买验证负载，再依赖此功能。

决策树：引擎内还是 Open Cloud

需求	使用
实时服务运行期间读写普通玩家数据	引擎内 DataStoreService
外部批量迁移、清理、RTBF 删除	Open Cloud 数据存储
高风险发布前安排每日快照	Open Cloud SnapshotDataStores
配置更改后重启所有服务	Open Cloud RestartUniverseServers
从 CI 发布一个场景	Open Cloud UpdatePlace
以编程方式上传大量资源	Open Cloud 资源
从体验内更新群组角色	HttpService + Open Cloud UpdateGroupMembership
在体验外向用户发送通知	Open Cloud CreateUserNotification
实时订阅事件分析	Open Cloud Webhook
在体验内发起普通变现提示／发放	引擎内 MarketplaceService
在外部管理游戏通行证／开发者产品配置	Open Cloud 游戏通行证／开发者产品

安全检查清单

• 将密钥存储在机密管理器或 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 数据存储批量任务时没有客户端速率限制器（共享体验预算 → 实时服务受到限流）。
• 期望 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 数据存储共享预算）
• https://create.roblox.com/docs/cloud/guides/data-stores/throttling（旧版 v1 数据存储限制）
• 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 端点并处理重试。