Back to Details

roblox-cloud

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

roblox-cloud

roblox-cloud

When to Use

使用场景

Use this skill when the task is mainly about Roblox Open Cloud or HTTP-based integration work outside normal gameplay scripting:
  • Building CI, bots, web backends, scripts, or internal tools that call Roblox web APIs.
  • Choosing API keys for non-user automation and checking the required scopes for an endpoint.
  • Constructing request URLs, bodies, filters, headers, pagination, update masks, or long-running operation polling.
  • Handling Open Cloud errors, quota limits, retries, and rate-limit headers.
  • Deciding whether an endpoint is usable from HttpService inside an experience.
  • Receiving Roblox webhooks on Discord, Slack, or a custom HTTPS endpoint.
  • Reading openapi.json, cloud.docs.json, or service-specific JSON files to generate clients or inspect endpoint metadata.
Do not use this skill when the task is mainly about:
  • OAuth app registration, authorization flows, token exchange, refresh handling, or delegated user consent.
  • DataStore or MemoryStore schema design, save architecture, or cross-server data strategy.
  • Gameplay remotes, replication, or general Roblox engine scripting.
当任务主要涉及Roblox Open Cloud或常规游戏脚本之外的基于HTTP的集成工作时，使用此技能：
  • 构建调用Roblox Web API的CI、机器人、Web后端、脚本或内部工具。
  • 为非用户自动化选择API密钥，并检查端点所需的权限范围（scopes）。
  • 构建请求URL、请求体、过滤器、请求头、分页、更新掩码（update masks）或轮询长时间运行的操作。
  • 处理Open Cloud错误、配额限制、重试和速率限制请求头。
  • 判断某个端点是否可在体验内通过HttpService调用。
  • 在Discord、Slack或自定义HTTPS端点接收Roblox webhook。
  • 读取openapi.json、cloud.docs.json或服务特定的JSON文件以生成客户端或检查端点元数据。
以下场景请勿使用此技能：
  • OAuth应用注册、授权流程、令牌交换、刷新处理或委托用户同意。
  • DataStore或MemoryStore的schema设计、存储架构或跨服务器数据策略。
  • 游戏玩法远程调用（gameplay remotes）、复制或常规Roblox引擎脚本。

Decision Rules

决策规则

  • Use this skill if the core question is how to call or integrate with Roblox from HTTP.
  • Prefer API keys when the caller is a server, CI job, bot, webhook worker, or in-experience automation that does not need end-user consent.
  • Hand off to roblox-oauth when the integration needs user-granted access, OAuth registration, refresh tokens, or per-user delegated authorization.
  • Hand off to roblox-data when the question becomes about persistent schema, contention, caching, or store-system design instead of request mechanics.
  • Hand off to roblox-networking for gameplay networking, remotes, or trust-boundary questions.
  • Hand off to roblox-api if the task is only an engine API lookup rather than a cloud integration.
  • Use the machine-readable artifacts when you need exact path templates, schemas, scopes, rate limits, or HttpService usability metadata.
  • If a request mixes cloud integration with out-of-scope architecture, answer only the Open Cloud portion and explicitly exclude the rest.
  • 如果核心问题是如何通过HTTP调用Roblox或与之集成，则使用此技能。
  • 当调用方是服务器、CI任务、机器人、webhook工作器或不需要终端用户同意的体验内自动化时，优先使用API密钥。
  • 当集成需要用户授予的访问权限、OAuth注册、刷新令牌或每用户委托授权时，转交给roblox-oauth处理。
  • 当问题变为关于持久化schema、竞争、缓存或存储系统设计而非请求机制时，转交给roblox-data处理。
  • 当涉及游戏玩法网络、远程调用或信任边界问题时，转交给roblox-networking处理。
  • 当任务仅为引擎API查询而非云集成时，转交给roblox-api处理。
  • 当需要精确的路径模板、schema、权限范围、速率限制或HttpService可用性元数据时，使用机器可读工件。
  • 如果请求混合了云集成与超出范围的架构内容，仅回答Open Cloud相关部分，并明确排除其余内容。

Instructions

操作指南

  1. Classify the caller and integration surface:
    • External backend, CLI, CI, or automation worker.
    • Webhook receiver.
    • In-experience HttpService.
  2. Choose authentication at the boundary:
    • Default to API keys for non-user automation.
    • If the task needs user-specific delegated access, stop and switch to roblox-oauth.
  3. Confirm the endpoint before coding:
    • Base URL and path template.
    • Path and query parameters.
    • Required request body schema.
    • Required scopes.
    • Rate limits.
    • Whether HttpService is supported if the call originates in-experience.
  4. Build requests using the documented patterns:
    • Insert path parameters exactly.
    • Keep pagination queries stable across pages.
    • Add Content-Type: application/json for JSON bodies.
    • Send x-api-key for API-key-authenticated requests.
    • Use updateMask only for fields you intend to patch.
  5. Handle Open Cloud response mechanics explicitly:
    • Read nextPageToken for pagination.
    • Poll Operation resources with backoff for long-running calls.
    • Parse Open Cloud JSON types correctly, especially timestamps, durations, bytes, field masks, and decimals.
  6. Handle failure paths as part of the integration:
    • INVALID_ARGUMENT: verify IDs, filters, headers, and body shape.
    • PERMISSION_DENIED or INSUFFICIENT_SCOPE: verify scopes and resource access.
    • RESOURCE_EXHAUSTED or HTTP 429: honor retry-after when present, otherwise use exponential backoff.
    • UNAVAILABLE and similar transient failures: retry with backoff, not tight loops.
  7. For webhooks, design for secure, idempotent receipt:
    • Require a public HTTPS POST endpoint.
    • Return 2XX within 5 seconds.
    • Verify roblox-signature when a secret is configured.
    • Deduplicate by NotificationId.
    • Treat deliveries as retryable and potentially duplicated.
  8. For HttpService, apply the extra platform constraints:
    • Only supported Open Cloud endpoints are callable.
    • Only x-api-key and content-type headers are allowed.
    • x-api-key must come from a Secret.
    • HTTPS only.
    • Path parameters cannot contain ..
  9. Keep the answer inside scope:
    • Focus on cloud requests, auth choice, webhooks, HttpService, rate limits, and tooling artifacts.
    • Do not drift into OAuth implementation details, gameplay networking, or in-experience data architecture.
  1. 分类调用方和集成场景：
    • 外部后端、CLI、CI或自动化工作器。
    • Webhook接收器。
    • 体验内HttpService。
  2. 在边界处选择认证方式：
    • 非用户自动化默认使用API密钥。
    • 如果任务需要特定用户的委托访问权限，停止当前流程并切换到roblox-oauth。
  3. 编码前确认端点信息：
    • 基础URL和路径模板。
    • 路径和查询参数。
    • 必填请求体schema。
    • 必填权限范围。
    • 速率限制。
    • 如果调用来自体验内，确认是否支持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实现细节、游戏玩法网络或体验内数据架构。

Using References

使用参考资料

  • Open references/open-cloud-overview.md first when you need the high-level model for Open Cloud versus legacy or in-experience calls.
  • Open references/cloud-guides.md when the task matches a known workflow and you need the best guide starting point.
  • Open references/api-patterns-errors-types-scopes-and-rate-limits.md for request construction, pagination, field masks, errors, scopes, and retry behavior.
  • Open references/webhooks-documentation.md for trigger support, payload shape, signature verification, and delivery expectations.
  • Open references/http-service.md when requests originate from a Roblox experience and endpoint support must be validated.
  • Open references/openapi-documentation.md when you need to inspect or generate against the unified OpenAPI description.
  • Open references/cloud-reference-json-files.md when you need to mine local JSON artifacts directly for operation IDs, schemas, scopes, or engine-usability metadata.
  • 当需要了解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、schema、权限范围或引擎可用性元数据时，查看references/cloud-reference-json-files.md。

Checklist

检查清单

  • The integration surface is identified as external automation, webhook receiver, or in-experience HttpService.
  • API key usage is chosen only for non-OAuth automation, and OAuth work is handed off when required.
  • Endpoint path, body schema, scopes, and rate limits are confirmed before implementation.
  • Pagination, filtering, and updateMask behavior are understood for the chosen endpoint.
  • Long-running operations are polled instead of assumed synchronous.
  • Error handling covers invalid input, permission failures, and quota exhaustion.
  • Retry logic uses retry-after or exponential backoff.
  • Webhooks are treated as idempotent, signed, and time-bounded.
  • HttpService calls are checked for endpoint support and header limitations.
  • The response stays out of OAuth implementation, data architecture, gameplay networking, and general engine scripting.
  • 已识别集成场景为外部自动化、webhook接收器或体验内HttpService。
  • API密钥仅用于非OAuth自动化，当需要OAuth工作时已转交处理。
  • 实现前已确认端点路径、请求体schema、权限范围和速率限制。
  • 已理解所选端点的分页、过滤和updateMask行为。
  • 长时间运行的操作采用轮询而非假设同步完成。
  • 错误处理涵盖无效输入、权限失败和配额耗尽情况。
  • 重试逻辑使用retry-after或指数退避策略。
  • Webhook被视为幂等、已签名且有时间限制。
  • 已检查HttpService调用的端点支持情况和请求头限制。
  • 响应未涉及OAuth实现、数据架构、游戏玩法网络和常规引擎脚本内容。

Common Mistakes

常见错误

  • Implementing OAuth flows here instead of switching to roblox-oauth.
  • Assuming every Open Cloud endpoint is callable from HttpService.
  • Sending unsupported headers from HttpService or storing the API key as plain text instead of a Secret.
  • Forgetting that API-key scopes and creator permissions both matter.
  • Changing filter parameters while paginating and then hitting 400 errors.
  • Ignoring Operation polling and assuming async endpoints finish immediately.
  • Retrying 429s or 503s in a tight loop instead of backing off.
  • Treating webhook delivery as exactly once and skipping deduplication.
  • Letting webhook handlers do slow work before returning a 2XX response.
  • Expanding a cloud-integration question into save-schema, gameplay, or remote-security design.
  • 在此处实现OAuth流程而非切换到roblox-oauth。
  • 假设所有Open Cloud端点都可通过HttpService调用。
  • 从HttpService发送不支持的请求头，或将API密钥以明文形式存储而非存入Secret。
  • 忘记API密钥权限范围和创建者权限都很重要。
  • 分页时更改过滤器参数导致400错误。
  • 忽略Operation轮询，假设异步端点立即完成。
  • 以紧密循环方式重试429或503错误而非退避。
  • 将webhook交付视为恰好一次，跳过去重步骤。
  • webhook处理程序在返回2XX响应前执行耗时工作。
  • 将云集成问题扩展到存储schema、游戏玩法或远程安全设计。

Examples

示例

External automation with an API key

使用API密钥的外部自动化

  • Use an API key for a CI job that publishes a place, updates a universe, or lists inventory items.
  • Confirm the endpoint scope, build the request URL, and inspect rate-limit headers for safe batching.
  • 为发布场地、更新宇宙或列出库存物品的CI任务使用API密钥。
  • 确认端点权限范围，构建请求URL，并检查速率限制请求头以实现安全批量处理。

In-experience Open Cloud call

体验内Open Cloud调用

  • Before writing HttpService:RequestAsync, confirm the endpoint is supported for engine use.
  • Put the API key in Secrets, send only x-api-key and content-type, and handle 429s with backoff.
  • 在编写HttpService:RequestAsync之前，确认端点支持引擎调用。
  • 将API密钥存入Secrets，仅发送x-api-key和content-type，并通过退避策略处理429错误。

Webhook receiver

Webhook接收器

  • Configure a public HTTPS endpoint.
  • Verify roblox-signature, reject stale timestamps, deduplicate by NotificationId, return 2XX quickly, and process the event asynchronously.
  • 配置公共HTTPS端点。
  • 验证roblox-signature，拒绝过期时间戳，通过NotificationId去重，快速返回2XX，并异步处理事件。