SearchItems

Economy v2 が一般提供 (GA) されました。サポートとフィードバックについては、PlayFab フォーラムを参照してください。

SearchItems API は、指定された検索パラメーターを使用して公開カタログに対する検索を実行し、アイテムのページ分割されたリストを返します。もっとも基本的な形では、Search パラメーターは Title、Description、Keywords、および Searchable String Display Properties フィールドに対するプレーンテキストのあいまい検索です。ただし Filter、OrderBy、および Select は、検索パラメーターを変更するために使用できる OData クエリの拡張です。検索結果は、検索ドキュメント内の任意のフィールド (Title と Description を除く) でフィルターおよび並べ替えできます。 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 フィールドに対しても行うことができます。タイトルは、Game Manager の Display Properties Mappings 設定でカスタム検索およびフィルターのプロパティを構成できます。

Game Manager の Display Properties のスクリーンショット

DisplayProperties にフィールドを追加すると、データベースに新しいインデックスが作成されます。インデックス作成後に追加または更新されたドキュメントのみが対象となります。表示プロパティをすべてのアイテムに適用する必要がある場合は、カタログ全体を再公開する必要があります。 DateTime、Double、Queryable String の表示プロパティは クエリ可能 で、これらのプロパティは Filter および OrderBy ステートメントで使用できます。 Searchable String 表示プロパティは 検索可能 で、これらのプロパティは Search フィールドに対するあいまい検索でクエリされます。検索可能なプロパティは、Filter および OrderBy ステートメントでは使用できません。タイトルは、各種類につき 5 つの表示プロパティに制限されています。

表示プロパティのマッピングは、キーと値のペアのインデックス付きリストとして格納されます。既存の表示プロパティマッピングを削除するとインデックスがシフトし、残りのすべてのプロパティの動作が壊れる可能性があります。既存のものを削除または編集するのではなく、追加のプロパティを追加することを推奨します。また、絶対に必要な場合を除き、プロパティマッピングを削除しないようにしてください。

Filter

Filter パラメーターを使用すると、検索リクエストによって返されるアイテムのコレクションをフィルタリングできます。filter で指定された式は結果内の各カタログアイテムに対して評価され、式が “true” と評価されるアイテムのみが含まれます。 Filter は OData の論理演算子と、括弧を使用した優先順位をサポートします。

Equal: ‘eq’
Not Equal: ‘ne’
Greater Than: ‘gt’
Greater than or Equal: ‘ge’
Less than: ‘lt’
Less than or Equal: ‘le’
Logical And: ‘and’
Logical Or: ‘or’
Logical Negation ‘not’

Filter は算術演算子および文字列関数をサポートしません。以下は Filter の例です。

ContentType によるフィルタリング

  "Filter": "ContentType eq 'Sword'"

結合を用いたフィルタリング

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

null 値を用いたフィルタリング

OData はフィルタリング用に null 型をサポートしています。

"Filter": "rating eq null"

上記のリクエストは、レビューのないすべてのアイテムを返します。

Creator 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 チェックを用いたフィルタリング

以下のフィルターは、contents フィールドに null 以外の値を持つ任意のアイテムをチェックします。

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

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

表示プロパティによるフィルタリング

フィルタリングは、クエリ可能な 表示プロパティでのみ実行できます。

  "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 による並べ替え

title/<LANG> パラメーターに asc または desc を組み合わせて、並び順を指定します。

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

ニュートラル文字列で並べ替えるには NEUTRAL を使用します。

  "OrderBy": "description/NEUTRAL desc"

表示プロパティによる並べ替え

並べ替えは、クエリ可能な 表示プロパティでのみ実行できます。

  "OrderBy": "DisplayProperties/DifficultyRating desc"

Select

デフォルトでは、Search は次の豊富なアイテムメタデータを返します。

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

デフォルトでは、title と description で使用されているニュートラル文字列のみが返されます。Thumbnail 画像が存在する場合はデフォルトで返されます。各アイテムには “Thumbnail” タイプの画像を 1 つだけ含めることができます。 Select を使用すると、コンテンツメタデータ (contents)、images、StartDate、EndDate、および title と description のローカライズされた文字列のフルセットを含む、追加のフィールドをページ分割された検索結果内でオプションで返すことができます。select フィールドが空のままの場合、検索結果は読み込み時間を高速化するために、完全なドキュメントメタデータのサブセットになります。このリクエストは、デフォルトのアイテムメタデータ に加えて contents と images も返します。

"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

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

ストアの検索

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

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

​SearchItems

​継続トークン

​表示プロパティ

​Filter

​ContentType によるフィルタリング

​結合を用いたフィルタリング

​null 値を用いたフィルタリング

​Creator ID によるフィルタリング

​配列フィールドによるフィルタリング

​配列と null チェックを用いたフィルタリング

​表示プロパティによるフィルタリング

​OrderBy

​Title による並べ替え

​表示プロパティによる並べ替え

​Select

​ローカライゼーション

​制限

​ストアの検索

SearchItems

継続トークン

表示プロパティ

Filter

ContentType によるフィルタリング

結合を用いたフィルタリング

null 値を用いたフィルタリング

Creator ID によるフィルタリング

配列フィールドによるフィルタリング

配列と null チェックを用いたフィルタリング

表示プロパティによるフィルタリング

OrderBy

Title による並べ替え

表示プロパティによる並べ替え

Select

ローカライゼーション

制限

ストアの検索