模式 | 文档 - Roblox 创作者中心

本页面涵盖开放云 API 的常见模式，特别是关于发出请求和处理响应。

路径

要向开放云 API 发出请求，您必须先形成一个 URL。这个 URL 是基础 URL（https://apis.roblox.com/cloud/v2）、Open Cloud API 路径（例如，/universes/{universe_id}/places/{place_id}/user-restrictions）和任何查询参数（例如，?maxPageSize=25）的组合。完整的请求 URL 可能会看起来像这样：


https://apis.roblox.com/cloud/v2/users/4687549151/inventory-items?maxPageSize=100

许多路径，包括上面的示例，具有路径参数，由 API 参考中的斜角括号命名。路径参数是你在提交请求之前插入的变量，几乎总是ID：用户ID、组ID、地点ID等。ID通常是数字的，但并不总是如此；例如，数据存储和内存存储ID支持更广的字符设置。

一些资源具有多个路径模式，可在 API 参考中的资源路径标题下看到。例如，列出用户限制的 URL 可以是以关注中/正在关注任一选项：

https://apis.roblox.com/cloud/cloud/v2/universes/{universe_id}/user-restrictions
https://apis.roblox.com/cloud/cloud/v2/universes/{universe_id}/places/{place_id}/user-restrictions

你可能可以推断出两者之间的差异：一些用户限制适用于整个宇宙（体验），而其他人适用于宇宙内的特定地点。除了路径的小增加和额外的路径参数外，调用是相同的。

许多 API 返回路径作为其响应的一部分，您可以使用它来提出进一步的请求。如果 API 需要几秒钟才能满足请求，它通常会返回操作而不是资源或响应本身。

内容长度和类输入

许多 API 调用，尤其是那些创建或更新资源的调用，需要一个 JSON 请求体。如果您的请求有身体，请确保包含 Content-Length 和 Content-Type 头标。大多数 HTTP 客户端会自动添加这些头。

页面分割

如果您在请求中指定 maxPageSize，那么一些方法会返回分页结果—实际上是部分响应：


GET /cloud/v2/users/{user_id}/inventory-items?maxPageSize=25

{
  "inventoryItems": [
    ...
  ],
  "nextPageToken": "aaaBBB"
}


GET /cloud/v2/universes/{universe_id}/data-stores?maxPageSize=25

{
  "dataStores": [
    ...
  ],
  "nextPageToken": "datastore1"
}

如果响应包含 nextPageToken 的值，请在后续请求的 pageToken 参数中使用该值来检索下一页。当 nextPageToken 是空的或全部被省略时，你已经到达了结果的最后：


GET /cloud/v2/users/{user_id}/inventory-items?maxPageSize=25&pageToken=aaaBBB

{
  "inventoryItems": [
    ...
  ],
  "nextPageToken": ""
}


GET /cloud/v2/universes/{universe_id}/data-stores?maxPageSize=25&pageToken=datastore1

{
  "dataStores": [
    ...
  ]
}

除了 pageToken 之外，您必须使用相同的查询来确保页面正常显示。更改任何过滤器参数会导致 400 错误。

长时间运行操作

一些方法返回一个 Operation 对象，该对象代表一个长时间运行的请求，以后返回异步响应。对象包含以下字段：

路径 - 调用端点路径来调用请求完成的请求。将路径添加到资源方法的原始基础 URL。
完成 - 一个用于表示操作是否完成的 boolean 值。
回应 - 回应对象。此字段为空直到 done 字段具有值 true 。
元数据 -用于请求的特定自定义元数据。

示例操作对象
{
  "path": "v1/assets/12345/operation/xyz",
  "done": true,
  "response": {
    "value1": "myValue",
    "value2": 1234
  },
  "metadata": {
    "metadata1": "string",
    "metadata2": 5678
  }
}

使用 Operation 对象的路径来调查资源准备好时。一个好的策略是使用指数退出。例如，你可能会立即调用，然后一秒钟、两秒钟、四秒钟等等。


def PollForResults(operationPath):
    currentRetries = 0
    maxRetries = 10
    retryPollingDelay = 1
    retryPollingMultiplier = 2
    while (currentRetries < maxRetries):
        # 在第一次检查中没有延迟
        if (currentRetries == 0):
            results = GetOperation(operationPath)
        # 重试逻辑以进行后续检查
        else:
            time.sleep(retryPollingDelay)
            results = GetOperation(operationPath)
            # 指数退出
            retryPollingDelay *= retryPollingMultiplier
        # 检查结果并返回如果存在
        if (results.status_code != 200 or results.json()[doneJSONKey]):
            return results
        # 否则，增加重试次数
        else:
           currentRetries += 1

要了解使用固定重试间隔而不是指数退出的更完整的代码示例，请参阅查询结果。

过滤

一些方法可以让你通过在请求中包含 filter 参数来过滤响应。以下部分描述了指定端点的过滤语法和指南。

列出群组成员

野卡符号 - 可以用于替换群组ID以便列出所有群组的成员：groups/-/memberships。

过滤符合共同表达语言（CEL）。仅支持两个运营商：

==
in [...]

如果您在资源路径中指定组 ID，您可以通过以下格式过滤会员资格：

用户过滤：filter="user == 'users/9876543210'"
角色过滤：filter="role == 'groups/123/roles/7920705'"

如果您为组 ID 指定通配符字符，您必须在以下格式中过滤成员：

用户过滤：filter="user in ['users/1', 'users/156', 'users/9876543210', ...]"

列出库存物品

您可以按收藏品状态、库存物品类输入和库存物品ID过滤。如果你没有提供过滤器，用户的整个库存将返回。

过滤器格式是一个分号分开的列表：

filter={field}={value};{field}={value},{value},...;{field}=...

{field} 可以是以下表中任何一个预定义类型字段或ID字段。
{value} 可以是字符串、 boolean 或枚列。根据领域类输入，这可能是单个值 (boolean 字段) 或多个值 (列字段)。

您不能在同一个过滤器中结合类型和ID字段。

类型字段

ID 字段

| 过滤器 | 类型 | 描述 | | :----------------- | :----- | :--------------------------------------------------------------------------------------------------------------------- | | assetIds | 字符串 | 包含数字资产ID的逗号分隔列表 | | badgeIds | 字符串 | 包含数字徽章ID的逗号分隔列表 | | gamePassIds | 字符串 | 包含数字游戏通行证ID的逗号分隔列表 | | privateServerIds | 字符串 | 包含数字私服 ID 列表，用逗号分开。必须具有库存阅读范围，可以按此字段过滤 |

例子

返回用户拥有的所有收藏品：

filter=onlyCollectibles=true;inventoryItemAssetTypes=*
返回指定类型的所有项目：

filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY
返回列出类型的所有项目或任何游戏通行证。排除徽章从结果中（与如果 badges 未包含在过滤器中的行为相同）：

filter=inventoryItemAssetTypes=HAT,CLASSIC_PANTS,TSHIRT_ACCESSORY;gamePasses=true;badges=false
返回符合指定ID的资产：

filter=assetIds=1,2,3,4
返回符合指定 ID 的资产、徽章、游戏通行证和私服：

filter=assetIds=1,2,3,4;badgeIds=1,2,3,4;gamePassIds=1,2,3,4;privateServerIds=1,2,3,4

模式

在此页面