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

此页面涵盖 Open Cloud API 的常见模式，例如在处理请求和处理回应。

路径

要向开放云 API 提出请求，您必须首先形成一个 URL。这个 URL 是由基础 URL (https://apis.roblox.com/cloud/v2), 开放云 API 路径 (例如，/universes/{universe-id}/places/{place-id}/user-restrictions 和任何查询参数 (例如


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

许多路径，包括上面的示例，都有路径参数，它们可以通过在 API 引用中的曲括在 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 调用，特别是那些创建或更新资源的 API，需要 JSON 请求体。如果您的请求有一个身体，请确保包含 Content-Length 和 Content-Type 头件。大多数 HTTP 客户自动添加这些头件。

页码

如果您在请求中指定 maxPageSize ，一些方法将返回页面结果 — 基本上是部分响应：


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

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

如果响应包含 nextPageToken 的值，请在下一个请求中使用该值在 pageToken 参数中获取下一页。当 nextPageToken 为空时，您已经到达您的结果的终点：


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

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

除了pageToken之外，您必须使用相同的查询才能使页面正常显示。改变任何过滤器参数结果都会导致 400 错误。

长时间运行操作

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

path - 是要请求完成的调用的端口路径。添加路径到资源方法的原始基地 URL。
done - 一个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。

过滤器按 CommonExpressionLanguage 语言标准进行。目前只支持两个操作器：

==
in [...]

如果您在资源路径中指定群组ID，您可以根据以下格式过滤会员是否为用户或角色：

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

如果您为群组ID指定了狂卡字符，您必须以用户（最多50个）的形式过滤成员的身份：

用户过滤器 : filter="user in [user/1]， users/156]， users/9876543210]，...

列出库存物品

您可以根据可收集状态、物品栏项目类输入和物品栏项目ID进行过滤。如果您不提供过滤器，用户的整个物品栏将返回。

过滤器格式是 semicolon 分开列表：

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

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

您不能在同一个过滤器中结合类型和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

模式

路径

内容长度和类型

页码

长时间运行操作

过滤

列出群组成员

列出库存物品

类型字段

ID 字段

例子