模式 | 文件 - 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 引用中的弯括命名。路径参数是您插入請求前的變量，通常是數字，但不見得總是是：用戶ID、群組ID、位置ID、等。ID 通常是數字，但不見得總是是；例如，數據存取和記憶體存取的 ID 支持更廣泛的角色設定。

一些資源具有多個路徑模式，可以在 API 參考中的資源路徑標題下查看。例如，列出用戶限制的網址可以是任何一追蹤中：

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/{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 對象，代表一個長時間執行的請求，之後會返回一個異步回應。對象包含以下字段：

路徑 - 路徑是要邀請完成的呼叫。將路徑添加到資源方法的原始網頁。
完成 - 代表是否完成操作的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

要獲得使用 exponential 回退後不會發生的更完整代碼示例，請參閱測試結果用途。

過濾

有些方法讓您過濾回應，包括 filter 參數在請邀請中。下列部分描述過濾語法和指向指定端點的指引。

列出群組成員資格

狂野卡字元 - 可以用作群組 ID 來清單所有群組的會員資格：groups/-/memberships。

過濾符合 CommonExpressionLanguage (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 來過濾。如果您沒有提供過篩選器器，用戶的整個物品欄將返回。

過濾器格式是 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
返回列出的類型或任何遊戲通行證的所有項目。包括結果中的徽章（與過篩選器器包含在一起）：

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

模式

道路

內容長度和類型

頁面

長度運行操作

過濾

列出群組成員資格

清單物品

類型 Fields

ID 欄

例子