パターン | 文書 - 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

おそらく 2 つの違いを推測できます：一部のユーザー制限は、宇宙全体 (経験) に適用されますが、他の制限は宇宙内の特定の場所に適用されます。パスと追加のパスパラメータに小さな変更を加える以外、呼び出しは同じです。

多くの 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 パラメータにその値を使用して、次のページを取得します。When 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に追加します。
完了 - オペレーションが完了したかどうかを表すブール値
応答 - 応答オブジェクト。このフィールドは、done フィールドが true の値を持つまで空です。
メタデータ - リクエストされた特定のカスタムメタデータ。

例の操作オブジェクト
{
  "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)
        # 後続のチェックのためのロジックを再試行する
        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) に準拠します。2つのオペレータのみがサポートされます：

==
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} は、文字列、ブール、または枚数であることができます。フィールドの種入力によって、これは単一の値 (ブールフィールド) または複数の値 (リストフィールド) になる可能性があります。

同じフィルターでタイプと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