SearchItems

Economy v2 est désormais en disponibilité générale. Pour obtenir de l’aide et donner votre avis, 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 effectue une recherche approximative en texte brut sur les champs Title, Description, Keywords et Searchable String Display Properties. Cependant, Filter, OrderBy et Select sont des ajouts de requête OData qui permettent de 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’informations 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, filtres et tris peuvent également être effectués sur des champs DisplayProperties spécifiques 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 sont inclus. Si vous avez besoin que la propriété d’affichage s’applique à tous les articles, vous devez republier l’intégralité 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 recherchables : ces propriétés sont interrogées par recherche approximative via le champ Search. Les propriétés recherchables 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 conseillé d’ajouter une propriété supplémentaire plutôt que de supprimer ou de modifier une propriété existante, et vous devez éviter de supprimer des mappages de propriétés, sauf en cas de nécessité absolue

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 Filter 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 avis

Filtrage par ID de créateur

Pour filtrer par créateur spécifique, 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 sur 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 contient des valeurs non null

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

Par défaut, Search ne retourne PAS le contenu des articles, sauf s’il 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 disposent d’un attribut interne de « score » utilisé pour départager les égalités. Ce score est basé 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 spécifiez pas de sens, l’ordre croissant est utilisé par défaut. Si le champ contient des valeurs null, 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 d’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, Search retourne un ensemble riche de métadonnées d’article :

Id
Type
AlternateIds
Title (NEUTRAL ou paramètres régionaux de Language)
Description (NEUTRAL ou paramètres régionaux de Language)
Keywords (NEUTRAL ou paramètres régionaux de Language)
ContentType
Images (miniature uniquement)
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 de 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 retourne 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 et/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 que tous les champs Title, Description et Keywords retournent par défaut ces paramètres régionaux, ou NEUTRAL si l’article ne dispose pas de cette localisation. Un exemple de requête SearchItems avec un paramètre Language est disponible en haut de cette page. Pour plus d’informations 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 veiller à 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 de grande complexité 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 une boutique

L’une des propriétés que vous pouvez transmettre est le paramètre Store. Il vous permet d’effectuer une recherche dans le contexte d’une boutique. En plus de pouvoir vérifier si un article existe dans une boutique donnée, il peut également servir à afficher les prix remplacés des articles/contenus de la boutique. Vous pouvez également utiliser l’AlternateId de la boutique pour la rechercher. Pour en savoir plus sur l’utilisation des boutiques, cliquez ici

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

catalog

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 une boutique

​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 une boutique

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 une boutique