Skip to main content
Les API Collections Query constituent le principal moyen pour les services de déterminer la propriété et l’état des droits d’utilisation des utilisateurs. Comparativement aux API XStore côté client, les requêtes de service à service prennent en charge des scénarios plus vastes au niveau de l’éditeur ainsi que des architectures de services centralisées. Les résultats des API Collections comprennent uniquement les produits que l’utilisateur ciblé possède directement ou qu’il a directement le droit d’utiliser. Les droits d’utilisation partagés valides sur le client ne sont pas renvoyés dans les réponses de service à service. Pour plus d’information sur les scénarios de partage, consultez Modèle de partage de produits pour les jeux. Cet article vous aide à comprendre les API Query et à les intégrer au moyen des sections suivantes :
Consultez les prérequis pour les API de service à service. Si les produits ne sont pas correctement configurés pour votre type d’authentification, les appels peuvent réussir, mais ne renvoyer aucun résultat.

​
Choisir l’API Collections Query adaptée à vos besoins

Il existe deux versions de Collections Query : b2bLicensePreview (v8) et publisherQuery (v9). Dans la plupart des cas, utilisez publisherQuery, car ses paramètres de requête sont simplifiés et elle prend en charge l’état XBOX Game Pass. Utilisez b2bLicensePreview lorsque vous avez besoin de comportements hérités, comme la prise en charge de LegacyProductId.
Bien qu’il n’existe pas d’URI v9 équivalent pour la fonctionnalité de consommation, vous pouvez utiliser publisherQuery et l’URI de consommation v8 ensemble sans problème.

​
Comprendre les droits d’utilisation satisfaisants dans la réponse

Un utilisateur peut avoir un droit d’utilisation sur un produit directement (achat/échange) ou indirectement (ensemble/abonnement). Si le droit d’utilisation est indirect, le tableau satisfiedByProductIds contient le ou les ProductId dont provient le droit d’utilisation. Exemple : Un utilisateur a acheté l’ensemble Édition Deluxe d’un jeu. L’appel des API Query renvoie dans le résultat le produit du jeu et tous les produits inclus dans l’ensemble. Chacun de ces éléments contient le ProductID de l’ensemble Édition Deluxe dans sa liste satisfiedByProductIds.

​
Comprendre les éléments en double dans la réponse

Vous pourriez voir plusieurs éléments ayant le même ProductId/SKU lorsque des utilisateurs ont plusieurs sources de droits d’utilisation. Les différences apparaissent habituellement dans des champs comme acquisitionType, les dates et satisfiedByProductIds. Définissez excludeDuplicates sur true pour regrouper plusieurs sources de droits d’utilisation en un seul élément correspondant au droit de propriété le plus direct, dans cet ordre :
  • Achat direct / code d’échange
  • Droit satisfait par un ensemble acheté directement
  • Droit satisfait par un abonnement
  • Droit satisfait par un achat promotionnel (p. ex. Games With Gold)
Si les doublons proviennent de la même source (par exemple, des périodes d’abonnement Active et Expired), un seul élément est renvoyé (même si excludeDuplicates est désactivé), selon la priorité d’état suivante :
  • Active
  • Invalid (s’il existe plusieurs droits d’utilisation non valides, l’élément invalidé le plus récemment est renvoyé)
  • Revoked
Les scénarios de doublons courants et leurs résultats sont présentés dans le tableau suivant.

​
Exemple

Un utilisateur achète le jeu A et le module complémentaire B, puis achète plus tard un passe saisonnier qui inclut aussi le module complémentaire B. La réponse peut contenir deux entrées pour le module complémentaire B : l’achat direct et le droit d’utilisation satisfaisant provenant du passe saisonnier. Si excludeDuplicates est défini sur true, seule l’entrée de l’achat direct est renvoyée.

​
Documentation de référence des API

​
Voir aussi

Vue d’ensemble du commerce Gérer les produits à partir de vos services Référence de l’API XStore
Last modified on October 6, 2026