roblox-cloud

roblox-cloud

适用场景

当任务主要涉及 Roblox Open Cloud 或正常游戏玩法脚本以外的基于 HTTP 的集成工作时，使用此技能：

• 构建调用 Roblox Web API 的 CI、机器人、Web 后端、脚本或内部工具。
• 为非用户自动化选择 API 密钥，并检查端点所需的作用域。
• 构造请求 URL、请求正文、筛选条件、标头、分页、更新掩码或长时间运行操作的轮询。
• 处理 Open Cloud 错误、配额限制、重试和速率限制标头。
• 判断某个端点是否可在体验中通过 HttpService 使用。
• 在 Discord、Slack 或自定义 HTTPS 端点接收 Roblox Webhook。
• 读取 openapi.json、cloud.docs.json 或特定服务的 JSON 文件，以生成客户端或检查端点元数据。

当任务主要涉及以下内容时，不要使用此技能：

• OAuth 应用注册、授权流程、令牌交换、刷新处理或委托用户同意。
• DataStore 或 MemoryStore 架构设计、保存架构或跨服务器数据策略。
• 游戏玩法远程通信、复制或通用 Roblox 引擎脚本编写。

决策规则

• 如果核心问题是如何通过 HTTP 调用 Roblox 或与其集成，请使用此技能。
• 如果调用方是服务器、CI 任务、机器人、Webhook 工作进程，或不需要最终用户同意的体验内自动化，请优先使用 API 密钥。
• 如果集成需要用户授予访问权限、OAuth 注册、刷新令牌或按用户委托授权，请转交给 roblox-oauth。
• 如果问题转为持久化架构、争用、缓存或存储系统设计，而非请求机制，请转交给 roblox-data。
• 如果涉及游戏玩法联网、远程通信或信任边界问题，请转交给 roblox-networking。
• 如果任务仅是查询引擎 API，而不是云集成，请使用 roblox-api。
• 如果需要精确的路径模板、架构、作用域、速率限制或 HttpService 可用性元数据，请使用机器可读文件。
• 如果请求同时包含云集成和范围外的架构问题，只回答 Open Cloud 部分，并明确排除其余内容。

说明

1. 对调用方和集成界面进行分类：
   • 外部后端、CLI、CI 或自动化工作进程。
   • Webhook 接收端。
   • 体验内的 HttpService。
2. 在边界处选择身份验证方式：
   • 非用户自动化默认使用 API 密钥。
   • 如果任务需要用户特定的委派访问权限，请停止并改用 roblox-oauth。
3. 编写代码前确认端点：
   • 基础 URL 和路径模板。
   • 路径参数和查询参数。
   • 必需的请求正文架构。
   • 必需的作用域。
   • 速率限制。
   • 如果调用源自体验内，是否支持 HttpService。
4. 按照文档中的模式构造请求：
   • 按原样插入路径参数。
   • 翻页时保持查询参数不变。
   • JSON 请求正文添加 Content-Type: application/json。
   • 对使用 API 密钥身份验证的请求发送 x-api-key。
   • 仅对计划修补的字段使用 updateMask。
5. 明确处理 Open Cloud 响应机制：
   • 翻页时读取 nextPageToken。
   • 对长时间运行的调用使用退避策略轮询 Operation 资源。
   • 正确解析 Open Cloud JSON 类型，尤其是时间戳、时长、字节、字段掩码和小数。
6. 将故障处理纳入集成设计：
   • INVALID_ARGUMENT：检查 ID、筛选条件、标头和正文格式。
   • PERMISSION_DENIED 或 INSUFFICIENT_SCOPE：检查作用域和资源访问权限。
   • RESOURCE_EXHAUSTED 或 HTTP 429：存在 retry-after 时遵循该值，否则使用指数退避。
   • UNAVAILABLE 及类似的暂时性故障：使用退避策略重试，避免紧密循环。
7. 对 webhook 进行安全、幂等的接收设计：
   • 要求使用公开的 HTTPS POST 端点。
   • 在 5 秒内返回 2XX。
   • 配置密钥时验证 roblox-signature。
   • 按 NotificationId 去重。
   • 将投递视为可重试且可能重复。
8. 对 HttpService 应用额外的平台限制：
   • 只能调用受支持的 Open Cloud 端点。
   • 只允许使用 x-api-key 和 content-type 标头。
   • x-api-key 必须来自 Secret。
   • 仅允许 HTTPS。
   • 路径参数不能包含 ..。
9. 答案应限定在相关范围内：
   • 聚焦云请求、身份验证选择、webhook、HttpService、速率限制和工具产物。
   • 不要延伸到 OAuth 实现细节、游戏内网络或游戏内数据架构。

使用参考资料

• 需要了解 Open Cloud 与旧版或游戏内调用的总体模型时，先打开 references/open-cloud-overview.md。
• 任务符合已知工作流且需要选择最佳指南入口时，打开 references/cloud-guides.md。
• 需要了解请求构造、翻页、字段掩码、错误、作用域和重试行为时，打开 references/api-patterns-errors-types-scopes-and-rate-limits.md。
• 需要了解触发器支持、载荷格式、签名验证和投递预期时，打开 references/webhooks-documentation.md。
• 请求源自 Roblox 体验且需要验证端点支持情况时，打开 references/http-service.md。
• 需要根据统一的 OpenAPI 描述进行检查或生成时，打开 references/openapi-documentation.md。
• 需要直接从本地 JSON 产物中查找操作 ID、架构、作用域或引擎可用性元数据时，打开 references/cloud-reference-json-files.md。

检查清单

• 已确定集成方式属于外部自动化、Webhook 接收器，还是体验内 HttpService。
• 仅对非 OAuth 自动化使用 API 密钥；如有需要，则将 OAuth 相关工作交由其他流程处理。
• 实施前已确认端点路径、请求体架构、作用域和速率限制。
• 已了解所选端点的分页、筛选和 updateMask 行为。
• 对长时间运行的操作进行轮询，而非假定其会同步完成。
• 错误处理涵盖无效输入、权限失败和配额耗尽。
• 重试逻辑使用 retry-after 或指数退避。
• 将 Webhook 视为幂等、经过签名且有时间限制的请求。
• 检查 HttpService 调用的端点支持情况和标头限制。
• 回答不涉及 OAuth 实现、数据架构、游戏网络和通用引擎脚本。

常见错误

• 在这里实现 OAuth 流程，而不是切换到 roblox-oauth。
• 假定所有 Open Cloud 端点都可通过 HttpService 调用。
• 从 HttpService 发送不受支持的标头，或将 API 密钥以纯文本而非 Secret 形式存储。
• 忘记 API 密钥作用域和创作者权限都很重要。
• 分页时更改筛选参数，导致出现 400 错误。
• 忽略 Operation 轮询，并假定异步端点会立即完成。
• 遇到 429 或 503 时紧密循环重试，而不是采用退避策略。
• 将 Webhook 投递视为恰好一次，跳过重复事件去重。
• 让 Webhook 处理程序在返回 2XX 响应前执行耗时操作。
• 将云集成问题扩展到存档架构、游戏玩法或远程安全设计。

示例

使用 API 密钥进行外部自动化

• 使用 API 密钥执行 CI 作业，以发布一个 place、更新一个 universe，或列出库存物品。
• 确认端点作用域，构建请求 URL，并检查速率限制标头，以安全地批量处理请求。

体验内 Open Cloud 调用

• 编写 HttpService:RequestAsync 前，确认该端点支持在引擎中使用。
• 将 API 密钥存放在 Secrets 中，仅发送 x-api-key 和 content-type，并在遇到 429 时采用退避策略。

Webhook 接收器

• 配置一个公开的 HTTPS 端点。
• 验证 roblox-signature，拒绝过期时间戳，按 NotificationId 去重，快速返回 2XX，并异步处理事件。