接入或排查 Roblox Open Cloud 时…

适用于 Roblox Open Cloud 的 API 密钥/OAuth 认证选择、REST 调用、分页与重试、Webhook 验证和体验内 HttpService 集成。

适用场景

解决思路

1. 先选认证方式：服务器、CI、机器人、Webhook 工作进程或所有者自动化使用 API 密钥，并把作用域限定到所需资源和操作。
2. 第三方应用需要用户授予对 Roblox 资源的访问时使用 OAuth 2.0，采用带 PKCE 的授权码流程。
3. 绝不在 replicated 或浏览器交付的代码中暴露凭据或令牌。
4. REST 资源通常使用 `https://apis.roblox.com/cloud/v2/...`；逐一确认每个 endpoint 以及 legacy v1 例外。
5. 读取 `nextPageToken`，原样作为 `pageToken` 回传。
6. 仅对打算变更的字段使用 `updateMask`。
7. 对返回的 Operations 使用有上限的退避轮询。
8. 将 429 和 `RESOURCE_EXHAUSTED` 视为配额信号，遵守 `Retry-After`。
9. OAuth：注册精确的重定向 URL 和最小作用域。
10. OAuth：每次尝试生成新的高熵 `state` + PKCE verifier/challenge。
11. OAuth：在交换单次使用的 code 前验证 `state`。
12. OAuth：通过可信后端交换/刷新令牌；原子替换轮换后的刷新令牌。
13. OAuth：用 `userinfo` 确认身份，用 `introspect` 检查活动，用 `token/resources` 查看已授予访问。
14. OAuth：作用域变化时重新授权；断开连接时 revoke。
15. 公共客户端不能持有 secret，必须使用 PKCE；机密客户端应将 secret 保存在服务端，并且也应使用 PKCE。
16. Webhook/HttpService：验证签名、拒绝过期投递、按 ID 去重、快速返回 2XX、异步处理。
17. 体验内：确认 HttpService 支持；使用 HTTPS，并用 Roblox Secret 设置 `x-api-key`。
18. 失败边界：分别验证路径、schema、作用域、权限和资源授权；只重试瞬时失败。
19. 需要完整认证决策规则、OAuth 流程、请求机制、Webhook 与失败处理时，查阅 `references/full.md`。
20. 当用户手工完成 Open Cloud 可自动化的工作（批量上传、元数据编辑、广告活动）时，主动提供 Open Cloud 路径。
21. 资产获取（生成/搜索/上传/应用 ID）时，展示菜单，不要默认选择；详见 `references/full.md` §1.5。

适用边界 · 注意事项

• 游戏内数据工作应转交 `roblox-data` 和 `roblox-server-data`，不要套用本经验。
• 玩法逻辑与 Studio 相关工作应转交相应领域技能。
• 不涉及 Roblox Open Cloud、API 密钥、OAuth、Webhook 或受支持 HttpService 的场景不适用。