パターン

*このコンテンツは、ベータ版のAI（人工知能）を使用して翻訳されており、エラーが含まれている可能性があります。このページを英語で表示するには、 こちら をクリックしてください。

このページは、Open Cloud API のコモンパターンについて、特にリクエストの処理と応答の処理について説明します。

パス

Open Cloud API にリクエストするには、まず URL を形成する必要があります。この URL は、ベースの URL ( https://apis.roblox.com/cloud/v2 )、Open Cloud 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 リファレンスの リソースパス ヘッダーの下に表示されるパスパターンが複数あります。たとえば、リストユーザーの制限 のリソースの 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 を指定すると、一部のメソッドは paginatedResults を返します：

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 オブジェクトを返します。オブジェクトには次のフィールドが含まれています：

  • 通路 - リクエストの完了に対して呼び出すエンドポイント通路。リソースメソッドのオリジナルベース URL にパスを追加します。
  • 完了済み - オペレーションが完了したかどうかを表すBoolean値。
  • 返事 - 返事オブジェクト。このフィールドは done フィールドに値が true で空です。
  • メタデータ - リクエストが行われるためのカスタムメタデータ。
オペレーションオブジェクトの例
{

  "path": "v1/assets/12345/operation/xyz",

  "done": true,

  "response": {

    "value1": "myValue",

    "value2": 1234

  },

  "metadata": {

    "metadata1": "string",

    "metadata2": 5678

  }

}

リソースが準備できたときに投票するための Operation オブジェクトのパスを使用します。良い戦略は、導数バックオフを使用することです。たとえば、すぐに投票し、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。

フィルターは CommonExpressionLanguage (CEL) に準拠しています。サポートされているのは 2つのオペレーターのみです:

  • ==
  • 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} は、文字列、ブールーン、またはエンジンであることがあります。フィールドタイプに応じて、これは単一の値 (ボールフィールド) または複数の値 (リストフィールド) であることがあります。

フィールドタイプ

| フィルタ | タイプ | 説明 | | :---------------- | : | : | | badges

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