樣式 | 文件 - 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):
        # 第一次檢查不延遲
        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 指定了通配符字符，必須按以下格式根據用戶（最多 50 個）過濾成員資格：

用戶過濾器：filter=user in ['users/1', 'users/156', 'users/9876543210', ...]

列出庫存項目

您可以按可收集狀態、庫存項目類型和庫存項目 ID 進行過濾。如果不提供過濾器，則返回用戶的整個庫存。

過濾格式為以分號分隔的列表：

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

{field} 可以是以下表格中的任何預定義類型欄位或 ID 欄位。
{value} 可以是字符串、布林值或枚舉。根據欄位類型，它可以是單個值（布林欄位）或多個值（列表欄位）。

您不能在同一過濾器中組合類型和 ID 欄位。

類型欄位

過濾器	類型	描述
badges	布林	在回應中包含徽章。默認為 false。
gamePasses	布林	在回應中包含遊戲通行證。默認為 false。
inventoryItemAssetTypes	有關資產類型的完整列表，請參見 assetDetails。	以逗號分隔的資產類型列表以包含。默認為不包含。指定 * 以包含所有資產類型。必須具備庫存讀取範圍才能根據已購買的地方進行過濾。
onlyCollectibles	布林	僅在回應中包含唯有可收集項目。默認為 false。此欄位必須與 inventoryItemAssetTypes 欄位一起使用才能返回項目，並且只返回非 UGC 限制項目。
privateServers	布林	在回應中包含私人伺服器。默認為 false。必須具備庫存讀取範圍才能根據此欄位進行過濾。

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