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

本页面涵盖了 Open Cloud API 的常见模式，特别是关于发出请求和处理响应的内容。

路径

要向 Open Cloud API 发出请求，您必须首先构建一个 URL。这个 URL 是基本 URL（例如 https://apis.roblox.com）、Open Cloud API 路径（例如 /cloud/v2/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 调用，特别是那些创建或更新的调用，要求使用 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 错误。

Open Cloud v2

多个路径

某些资源具有多个路径模式，在 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 在处理请求时需要超过几秒钟的时间，它通常会返回一个操作而不是资源或响应本身。

长时间运行的操作

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

path - 用于轮询请求完成的端点路径。将该路径附加到资源方法的原始基本 URL。
done - 表示操作是否完成的布尔值。
response - 响应对象。此字段在 done 字段为 true 之前为空。
metadata - 特定于所做请求的自定义元数据。

示例操作对象
{
  "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):
        # No delay on the first check
        if (currentRetries == 0):
            results = GetOperation(operationPath)
        # Retry logic for subsequent checks
        else:
            time.sleep(retryPollingDelay)
            results = GetOperation(operationPath)
            # Exponential backoff
            retryPollingDelay *= retryPollingMultiplier
        # Check for results and return if they exist
        if (results.status_code != 200 or results.json()[doneJSONKey]):
            return results
        # Otherwise, increment the retry count
        else:
           currentRetries += 1

有关使用固定重试间隔而不是指数退避的完整代码示例，请参见轮询结果。

过滤

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

列出组成员资格

通配符字符 - 可以用来替代组 ID，以列出所有组的成员资格：groups/-/memberships。

过滤符合通用表达式语言 (CEL)。仅支持两个运算符：

==
in [...]

如果在资源路径中指定了组 ID，则可以按以下格式过滤成员资格，使用用户或角色：

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

如果您为组 ID 指定了通配符字符，则必须按以下格式过滤成员资格，以用户（最多 50 个）为主：

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

列出库存项目

您可以按可收集状态、库存项目类型和库存项目 ID 过滤。如果不提供过滤器，将返回用户的整个库存。

过滤格式为分号分隔的列表：

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

{field} 可以是以下表格中的任何预定义类型字段或 ID 字段。
{value} 可以是字符串、布尔值或枚举。取决于字段类型，这可以是单个值（布尔字段）或多个值（列表字段）。

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

类型字段

过滤器	类型	描述
badges	boolean	在响应中包含徽章。默认值为 false。
gamePasses	boolean	在响应中包含游戏通行证。默认值为 false。
inventoryItemAssetTypes	请参见 assetDetails 获取完整的资产类型列表。	逗号分隔的资产类型列表。默认值为 none。指定 * 以获取所有资产类型。必须具有库存读取范围才能按购买的地点进行过滤。
onlyCollectibles	boolean	在响应中仅包含可收集项目。默认值为 false。此字段必须与 inventoryItemAssetTypes 字段一起使用，以便返回物品，并仅返回非 UGC 限定物品。
privateServers	boolean	在响应中包含私人服务器。默认值为 false。必须具有库存读取范围才能按此字段进行过滤。

ID 字段

过滤器	类型	描述
assetIds	string	逗号分隔的数值资产 ID 列表。
badgeIds	string	逗号分隔的数值徽章 ID 列表。
gamePassIds	string	逗号分隔的数值游戏通行证 ID 列表。
privateServerIds	string	逗号分隔的数值私人服务器 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