SearchItems

  • [アーティクル]

Important

エコノミー v2 が一般提供になりました。 サポートとフィードバックについては、 PlayFab フォーラムにアクセスしてください。

SearchItems API は、指定された検索パラメーターを使用してパブリック カタログに対して検索を実行し、ページ化された項目の一覧を返します。

最も基本的な部分として、Search パラメーターは、タイトル、説明、キーワード、および 検索可能な文字列の画面のプロパティ フィールドに対するプレーンテキストのあいまい検索です。 ただし、Filter、OrderBy、および Select は、検索パラメーターを変更するために使用できる OData クエリの追加です。 検索結果は、検索ドキュメント内の任意のフィールドでフィルター処理および並べ替えをすることができます (タイトルと説明を除く)。

OData クエリ構文の詳細については、こちらを参照してください。

SearchItems 要求の一例:

{
  "Search": "Pirates",
  "Filter": "Tags/any(t:t eq 'desert') and ContentType eq 'map'",
  "OrderBy": "lastModifiedDate asc",
  "ContinuationToken": "abc=",
  "Count": 2,
  "Language": "en-GB"
}

サンプル応答:

{
    "code": 200,
    "status": "OK",
    "data": {
        "Items": [
            {
               <item metadata> 
            }
        ],
      "ContinuationToken": "MTA="
    }
}

継続トークン

検索応答から返される ContinuationToken フィールドは、複数の結果をページ分割するために検索要求に渡すことができます。

画面のプロパティ

検索、フィルター、順序付けは、カスタム検索用に構成されている特定の DisplayProperties フィールドでも実行できます。 タイトルは、ゲーム マネージャーの 画面のプロパティ マッピング 設定でカスタム検索とフィルターのプロパティを構成できます。

ゲーム マネージャーでの画面のプロパティのスクリーンショット

フィールドを DisplayProperties に追加すると、データベースに新しいインデックスが作成されます。 インデックスの作成後に追加または更新されたドキュメントのみが含まれます。 すべてのアイテムに画面のプロパティを適用する必要がある場合は、カタログ全体を再発行する必要があります。

DateTime、Double、および Queryable String の画面のプロパティは queryable (クエリ可能) です。これらのプロパティは Filter ステートメントと OrderBy ステートメントで使用できます。

Searchable String の画面のプロパティは searchable (検索可能) です。これらのプロパティは Search フィールドに対してあいまい検索でクエリされます。 Filter ステートメントと OrderBy ステートメントでは、検索可能なプロパティを使用できません。

タイトルは、各種類 5 つの画面のプロパティに制限されています。

Warning

画面のプロパティ マッピングは、キーと値のペアのインデックス付きリストとして格納されます。 既存の画面のプロパティ マッピングを削除すると、インデックスがシフトされ、残りのすべてのプロパティの動作が中断される可能性があります。 既存のプロパティを削除または編集するのではなく、追加のプロパティを追加することをお勧めします。絶対に必要でない限り、プロパティ マッピングの削除は避けるべきです

フィルター

Filter パラメーターを使用すると、検索要求によって返されるアイテムのコレクションをフィルター処理できます。 フィルターで指定された式は、結果内の各カタログ アイテムに対して評価され、式が "true" と評価される項目のみが含まれます。

Filter では、かっこを使用した OData 論理演算子と優先順位がサポートされます。

  • 等しい: 'eq'
  • 等しくない: ‘ne’
  • 超え: ‘ gt’
  • 以上: ‘ge’
  • 未満: ‘ lt’
  • 以下: ‘ le’
  • 論理席: 'and'
  • 論理和: ‘or’
  • 論理的否定 'not'

フィルターでは、算術演算子や文字列関数はサポートされていません。

次に、フィルターの例をいくつか示します:

ContentType によるフィルター処理

  "Filter": "ContentType eq 'Sword'"

組み合わせによるフィルター処理

  "Filter": "rating/average gt 1 and rating/average lt 4"

null 値を使用したフィルター処理

OData では、フィルター処理の null の種類がサポートされています

"Filter": "rating eq null"

上記の要求は、レビューのないすべてのアイテムを返します

作成者 ID によるフィルター処理

特定の作成者でフィルター処理するには、構文を使用する必要がありますtitle_player_account!<ID>

  "Filter": "creatorId eq 'title_player_account!C88F55C6A734B1DC'"

配列フィールドによるフィルター処理

Filter では、配列に対するフィルター処理の any() もサポートされています。 例: alternateIds/any(a: a/value eq ‘StoreOfferId’)

  "Filter": "tags/any(t: t eq 'featured')"

配列と null チェックによるフィルター処理

次のフィルターは、null 以外の値を持つコンテンツ フィールドを持つアイテムを確認します

  "Filter": "contents/any(content: content ne null)"

注意

既定では、Select ステートメントで指定しない限り、Search はアイテムのコンテンツを返しません。 上記のクエリを `"Select": "contents"`` ステートメントなしで実行すると、フィルターが正しく適用されますが、返されるすべての検索結果に空のコンテンツ フィールドが含まれます

画面のプロパティによるフィルター処理

フィルター処理は、queryable (クエリ可能) な画面のプロパティでのみ実行できます

  "Filter": "DisplayProperties/DifficultyRating ge 5"

OrderBy

OrderBy は、検索結果の並べ替えに使用されるコンマ区切りのリストです。

  "OrderBy": "rating/average asc"

セカンダリ プロパティを渡して、並べ替えの際の "同位" を解消できます:

  "OrderBy": "rating/average asc, rating/totalCount desc"

セカンダリ値を持たないカタログアイテムには、同位を解消するために使用される内部の "score" 属性があります。 そのスコア付けは元となるデータベースの保存順に基づいており、アイテムが追加や削除される度に常に変動します。

OrderBy では、順序付けのためにいくつかの OData プロパティがサポートされています。

  • asc
  • desc

方向を指定しない場合、既定値は昇順です。 フィールドに null 値がある場合は、 asc の最初と desc の最後に表示されます。 OrderBy 値が渡されない場合は、既定の id asc 値が使用されます。

次に、OrderBy の例を示します:

タイトルによる並べ替え

title/<LANG> パラメーターを asc または desc と組み合わせて使用し、順序の優先順位を示します。

  "OrderBy": "title/en-GB asc"

ニュートラル文字列の順序を指定するには、NEUTRAL を使用します

  "OrderBy": "description/NEUTRAL desc"

画面のプロパティによる並べ替え

並べ替えは queryable な画面のプロパティでのみ実行できます

  "OrderBy": "DisplayProperties/DifficultyRating desc"

選択

既定では、Search は豊富な項目メタデータのセットを返します:

  • Id
  • Type
  • AlternateIds
  • Title(NEUTRAL または Language ロケール)
  • Description(NEUTRAL または Language ロケール)
  • Keywords(NEUTRAL または Language ロケール)
  • ContentType
  • Images(サムネイルのみ)
  • Tags
  • CreationDate
  • LastModifiedDate
  • CreatorEntityKey (以前の API バージョンでは CreatorId)
  • DisplayProperties
  • ItemReferences

既定では、タイトルと説明で使用されているニュートラル文字列のみが返されます。 縮小版画像が存在する場合は、既定で返されます。 各アイテムは、"縮小版" 型の 1 つの画像のみに制限されます。

Select を使用すると、必要に応じて、コンテンツ メタデータ (コンテンツ)、画像、StartDate、EndDate、タイトルと説明のローカライズされた文字列の完全なセットなど、ページ化された検索結果内でさらに多くのフィールドをオプションで返すことができます。 Select フィールドを空のままにすると、検索結果は完全なドキュメント メタデータのサブセットになり、読み込み時間が短縮されます。

この要求は、コンテンツとイメージに加え、既定のアイテムのメタデータを返します。

"Select": "contents,images"

title、description、および/または keywords を選択すると、ローカライズされた文字列データの完全なセットが返されます。

"Select": "title,description,keywords"

ローカライズ

ロケールは、Language パラメーターに渡すことができます。 ロケールを渡すと、すべての Title、Description、Keywords フィールドは既定でロケールを返し、アイテムにそのローカライズがない場合は NEUTRAL を返します。

Language パラメーターを持つSearchItems 要求の例は、このページの上部にあります。

ローカライズの詳細については、「 ローカライズ」を参照してください。

制限

検索フィルター クエリの複雑さは、要求ごとに制限されます。 負荷の高いクエリは拒否される可能性があり、タイトルは過度に複雑なクエリを試みないようにする必要があります。 最大の複雑さに近いクエリの例を次に示します。

contentType eq 'testType' and tags/any(t: t eq 'blue' or t eq 'green' or t eq 'violet') and platforms/any(p: p eq 'square' or p eq 'circle' or p eq 'triangle') and displayProperties/isFavorite eq true

contents/any(c: c/minClientVersion gt '1.2.3' and c/maxClientVersion lt '4.5.6' and c/tags/any(t: t eq 'map')) and rating/totalRatingsCount ge 20 and rating/averageRating ge 4.0

複雑度の高いフィルター クエリでは、次のメッセージを含む 400 エラーがスローされます: "The filter provided in the request does not meet the complexity requirements for source"。

ストアの検索

渡すことができるプロパティの 1 つは、 Store パラメーターです。 これを使用すると、ストアのコンテキスト内で検索できます。 特定のストアにアイテムがあるかどうかを確認できるだけでなく、ストアのアイテムやコンテンツの上書きされた価格を表示するためにも使用できます。 ストアの AlternateId を使用して検索することもできます。 ストアの使用の詳細については、こちらをご覧ください。

{
  "Search": "",
  "Filter": "ContentType eq 'weapons'",
  "Store": {
    "Id": "{{StoreID}}"
  },
}