Roblox Open Cloud 用于从游戏外部访问 Roblox 资源。适用场景包括 Open Cloud、OAuth、Webhooks、HttpService 以及传送(teleport)交接流程。如果处理的是游戏内数据,文档建议参考 roblox-data 和 roblox-server-data。
【认证方式选择】 首先需要确定认证方式。API 密钥适用于服务端、CI、机器人、Webhook 工作器或所有者自动化场景,应将其作用域限定到所需的资源与操作。OAuth 2.0 适用于第三方应用需要用户授权访问 Roblox 资源的场景,使用带 PKCE 的授权码流程。文档强调,切勿在可复制或交付到浏览器的代码中暴露凭据或令牌。
【REST 调用机制】 资源通常使用 https://apis.roblox.com/cloud/v2/... 路径,需要逐个确认每个端点以及遗留的 v1 例外。分页时读取 nextPageToken,并将其原样作为 pageToken 返回。updateMask 只用于打算变更的字段。对返回的 Operations 使用有界退避进行轮询。将 429 和 RESOURCE_EXHAUSTED 视为配额信号,并遵守 Retry-After。
【OAuth 要点】 注册精确的重定向 URL 和最小作用域。每次尝试使用全新的高熵 state 以及 PKCE verifier/challenge。在交换一次性 code 之前验证 state。通过受信任的后端进行交换与刷新,并以原子方式替换轮换后的 refresh token。可使用 userinfo 验证身份、introspect 检查活动状态,以及 token/resources 查看已授予的访问权限。作用域变更时重新授权,断开连接时撤销授权。公共客户端无法持有密钥,必须使用 PKCE;机密客户端将密钥保存在服务端,同时也应使用 PKCE。
【Webhooks 与 HttpService】 需要验证签名、拒绝过期投递、对 ID 去重、快速返回 2XX,并异步处理。在体验内使用时,需要确认 HttpService 支持情况;使用 HTTPS 以及 Roblox Secret 作为 x-api-key。
【失败边界】 应分别验证路径、schema、作用域、权限和资源授予。仅对暂时性失败进行重试。
【注意】 该技能强调“意识而非脚本”。当用户手动完成本可由 Open Cloud 自动化的工作(批量上传、元数据编辑、活动运营)时,应提示 Open Cloud 方案。资产获取(生成/搜索/上传/应用 ID)时应呈现菜单选项,而非默认选择。