SearchItems

Economy v2 est maintenant en disponibilité générale. Pour obtenir du soutien et transmettre vos commentaires, rendez-vous sur le forum PlayFab.

L’API SearchItems exécute une recherche dans le catalogue public à l’aide des paramètres de recherche fournis et retourne une liste paginée d’articles. Dans sa forme la plus simple, le paramètre Search est une recherche approximative en texte brut dans les champs Title, Description, Keywords et Searchable String Display Properties. Cependant, Filter, OrderBy et Select sont des ajouts de requête OData qui peuvent être utilisés pour modifier les paramètres de recherche. Les résultats de recherche peuvent être filtrés et triés selon n’importe quel champ du document de recherche (à l’exception de Title et Description). Vous trouverez plus d’information sur la syntaxe des requêtes OData ici Exemple de requête SearchItems :

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

Exemple de réponse :

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

Jetons de continuation

Le champ ContinuationToken retourné dans une réponse de recherche peut être transmis dans une requête de recherche pour parcourir plusieurs pages de résultats.

Propriétés d’affichage

Les recherches, les filtres et les tris peuvent également être effectués sur des champs DisplayProperties précis configurés pour la recherche personnalisée. Les titres peuvent configurer leurs propriétés de recherche et de filtre personnalisées dans le paramètre Display Properties Mappings de Game Manager.

Lorsque vous ajoutez un champ à DisplayProperties, un nouvel index est créé pour vous dans la base de données. Seuls les documents ajoutés ou mis à jour après la création de l’index y seront inclus. Si vous devez appliquer la propriété d’affichage à tous les articles, vous devez republier l’ensemble du catalogue. Les propriétés d’affichage DateTime, Double et Queryable String sont interrogeables; ces propriétés peuvent être utilisées dans les instructions Filter et OrderBy. Les propriétés d’affichage Searchable String sont consultables par recherche; ces propriétés sont interrogées par recherche approximative au moyen du champ Search. Les propriétés consultables par recherche ne peuvent pas être utilisées dans les instructions Filter et OrderBy. Les titres sont limités à cinq propriétés d’affichage de chaque type.

Les mappages de propriétés d’affichage sont stockés sous forme de liste indexée de paires clé-valeur. La suppression de mappages de propriétés d’affichage existants peut décaler les index et perturber le comportement de toutes les propriétés restantes. Il est suggéré d’ajouter une propriété supplémentaire plutôt que de supprimer ou de modifier une propriété existante, et vous devriez éviter de supprimer des mappages de propriétés sauf en cas d’absolue nécessité

Filter

Le paramètre Filter vous permet de filtrer la collection d’articles retournée par la requête de recherche. L’expression spécifiée avec le filtre est évaluée pour chaque article du catalogue dans les résultats, et seuls les articles pour lesquels l’expression est évaluée à « true » sont inclus. Filter prend en charge les opérateurs logiques OData et la priorité à l’aide de parenthèses :

Égal : ‘eq’
Différent : ‘ne’
Supérieur à : ‘gt’
Supérieur ou égal à : ‘ge’
Inférieur à : ‘lt’
Inférieur ou égal à : ‘le’
ET logique : ‘and’
OU logique : ‘or’
Négation logique ‘not’

Filter ne prend pas en charge les opérateurs arithmétiques ni les fonctions de chaîne. Voici des exemples de Filter :

Filtrage par ContentType

  "Filter": "ContentType eq 'Sword'"

Filtrage avec des conjonctions

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

Filtrage avec des valeurs null

OData prend en charge un type null pour le filtrage

"Filter": "rating eq null"

La requête ci-dessus retourne tous les articles sans critique

Filtrage par ID de créateur

Pour filtrer selon un créateur précis, vous devez utiliser la syntaxe title_player_account!<ID>

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

Filtrage par champs de tableau

Filter prend également en charge any() pour filtrer des tableaux. Par exemple : alternateIds/any(a: a/value eq 'StoreOfferId')

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

Filtrage avec des tableaux et des vérifications de valeurs null

Le filtre ci-dessous recherche tous les articles dont le champ contents comporte des valeurs non null

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

Par défaut, la recherche ne retourne PAS le contenu des articles, sauf si cela est spécifié avec une instruction Select. Si la requête ci-dessus est exécutée sans instruction `“Select”: “contents”“, le filtre sera correctement appliqué, mais tous les résultats de recherche retournés auront des champs de contenu vides

Filtrage par propriétés d’affichage

Le filtrage ne peut être effectué qu’avec des propriétés d’affichage interrogeables

  "Filter": "DisplayProperties/DifficultyRating ge 5"

OrderBy

OrderBy est une liste séparée par des virgules utilisée pour trier les résultats de recherche.

  "OrderBy": "rating/average asc"

Vous pouvez transmettre une propriété secondaire pour départager les « égalités » de tri :

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

Les articles du catalogue sans valeur secondaire ont un attribut interne de « score » utilisé pour départager les égalités. Ce score est fondé sur l’ordre de stockage dans la base de données sous-jacente et change constamment à mesure que des articles sont ajoutés et supprimés. OrderBy prend en charge quelques propriétés OData pour le tri :

asc
desc

Si vous ne précisez pas de direction, l’ordre par défaut est croissant. S’il y a des valeurs null dans le champ, elles apparaissent en premier pour asc et en dernier pour desc. Si aucune valeur OrderBy n’est transmise, la valeur par défaut id asc est utilisée. Voici des exemples de OrderBy :

Tri par titre

Utilisez le paramètre title/<LANG> combiné avec asc ou desc pour indiquer l’ordre souhaité.

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

Utilisez NEUTRAL pour trier selon les chaînes neutres

  "OrderBy": "description/NEUTRAL desc"

Tri par propriétés d’affichage

Le tri ne peut être effectué qu’avec des propriétés d’affichage interrogeables

  "OrderBy": "DisplayProperties/DifficultyRating desc"

Select

Par défaut, la recherche retourne un ensemble riche de métadonnées d’article :

Id
Type
AlternateIds
Title (paramètres régionaux NEUTRAL ou Language)
Description (paramètres régionaux NEUTRAL ou Language)
Keywords (paramètres régionaux NEUTRAL ou Language)
ContentType
Images (miniature seulement)
Tags
CreationDate
LastModifiedDate
CreatorEntityKey (CreatorId dans les versions antérieures de l’API)
DisplayProperties
ItemReferences

Seules les chaînes neutres utilisées dans le titre et la description sont retournées par défaut. Si une image miniature existe, elle est retournée par défaut. Chaque article est limité à une seule image de type « Thumbnail ». Avec Select, d’autres champs peuvent éventuellement être retournés dans les résultats de recherche paginés, notamment les métadonnées du contenu (contents), les images, StartDate, EndDate et l’ensemble complet des chaînes localisées du titre et de la description. Si le champ select est laissé vide, les résultats de recherche constituent un sous-ensemble des métadonnées complètes du document, afin d’accélérer les temps de chargement. Cette requête retournerait les métadonnées d’article par défaut en plus du contenu et des images :

"Select": "contents,images"

La sélection de title, description ou keywords retourne l’ensemble complet des données de chaînes localisées :

"Select": "title,description,keywords"

Localisation

Des paramètres régionaux peuvent être transmis dans le paramètre Language. La transmission de paramètres régionaux fait en sorte que tous les champs Title, Description et Keywords retournent ces paramètres régionaux par défaut, ou NEUTRAL si l’article ne dispose pas de cette localisation. Un exemple de requête SearchItems avec un paramètre Language se trouve en haut de cette page. Pour plus d’information sur la localisation, consultez Localisation.

Limites

La complexité des requêtes de filtre de recherche est limitée par requête. Les requêtes coûteuses peuvent être rejetées, et les titres doivent s’assurer de ne pas tenter des requêtes trop complexes. Voici des exemples de requêtes proches de la complexité maximale :

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

Les requêtes de filtre très complexes génèrent une erreur 400 avec le message : "The filter provided in the request does not meet the complexity requirements for source".

Recherche dans un magasin

L’une des propriétés que vous pouvez transmettre est le paramètre Store. Celui-ci vous permet d’effectuer une recherche dans le contexte d’un magasin. En plus de permettre de vérifier si un article existe dans un magasin donné, il peut également servir à afficher les prix remplacés des articles ou du contenu du magasin. Vous pouvez également utiliser l’AlternateId du magasin pour le rechercher. Pour en savoir plus sur l’utilisation des magasins, cliquez ici

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

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

Recherche

SearchItems

Jetons de continuation

Propriétés d’affichage

Filter

Filtrage par ContentType

Filtrage avec des conjonctions

Filtrage avec des valeurs null

Filtrage par ID de créateur

Filtrage par champs de tableau

Filtrage avec des tableaux et des vérifications de valeurs null

Filtrage par propriétés d’affichage

OrderBy

Tri par titre

Tri par propriétés d’affichage

Select

Localisation

Limites

Recherche dans un magasin

​SearchItems

​Jetons de continuation

​Propriétés d’affichage

​Filter

​Filtrage par ContentType

​Filtrage avec des conjonctions

​Filtrage avec des valeurs null

​Filtrage par ID de créateur

​Filtrage par champs de tableau

​Filtrage avec des tableaux et des vérifications de valeurs null

​Filtrage par propriétés d’affichage

​OrderBy

​Tri par titre

​Tri par propriétés d’affichage

​Select

​Localisation

​Limites

​Recherche dans un magasin

SearchItems

Jetons de continuation

Propriétés d’affichage

Filter

Filtrage par ContentType

Filtrage avec des conjonctions

Filtrage avec des valeurs null

Filtrage par ID de créateur

Filtrage par champs de tableau

Filtrage avec des tableaux et des vérifications de valeurs null

Filtrage par propriétés d’affichage

OrderBy

Tri par titre

Tri par propriétés d’affichage

Select

Localisation

Limites

Recherche dans un magasin