パターン | 文書 - 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 リファレンスの Resource Paths ヘッダーに表示される複数のパスパターンがあります。例えば、ユーザー制限のリストの 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 - リクエストに特有のカスタムメタデータ。

例 Operation オブジェクト
{
  "path": "v1/assets/12345/operation/xyz",
  "done": true,
  "response": {
    "value1": "myValue",
    "value2": 1234
  },
  "metadata": {
    "metadata1": "string",
    "metadata2": 5678
  }
}

Operation オブジェクトのパスを使用して、リソースが準備できたときにポーリングします。良い戦略は、指数バックオフを使用することです。たとえば、最初はすぐにポーリングを行い、次に1秒後、2秒後、4秒後、などとすることができます。


def PollForResults(operationPath):
    currentRetries = 0
    maxRetries = 10
    retryPollingDelay = 1
    retryPollingMultiplier = 2
    while (currentRetries < maxRetries):
        # 最初のチェックで遅延なし
        if (currentRetries == 0):
            results = GetOperation(operationPath)
        # Subsequent checksのための再試行ロジック
        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。

フィルタリングは Common Expression Language (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 を参照してください。	含めるアセットタイプのカンマ区切りリスト。デフォルトはなし。すべてのアセットタイプに対して * を指定できます。購入したプレイスによるフィルタリングには Inventory 読取スコープが必要です。
onlyCollectibles	boolean	レスポンスにのみ収集可能なアイテムを含めます。デフォルトは false です。このフィールドを inventoryItemAssetTypes フィールドと一緒に使用してアイテムを返し、UGC 制限のないアイテムのみを返します。
privateServers	boolean	レスポンスにプライベートサーバーを含めます。デフォルトは false です。このフィールドでフィルタリングするには Inventory 読取スコープが必要です。

IDフィールド

フィルタ	タイプ	説明
assetIds	string	含める数値アセット ID のカンマ区切りリスト。
badgeIds	string	含める数値バッジ ID のカンマ区切りリスト。
gamePassIds	string	含める数値ゲームパス ID のカンマ区切りリスト。
privateServerIds	string	含める数値プライベートサーバー ID のカンマ区切りリスト。このフィールドでフィルタリングするには Inventory 読取スコープが必要です。

例

ユーザーが所有するすべての収集可能なアイテムを返します：

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