模式 | 文件 - 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 或 enum。根據欄位類輸入，這可能是單一值 (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

模式

此頁面