collections.mp.microsoft.com/v9.0/collections/publisherQuery

publisherQuery permet à vos propres services d’interroger les produits et les droits d’utilisation d’un utilisateur, y compris l’état de son abonnement XBOX Game Pass. Votre service ne doit pas interroger régulièrement les achats des utilisateurs, afin d’éviter les limites de fréquence d’appels basées sur une fenêtre de temps par utilisateur. Actuellement, la limite est de 100 requêtes dans une fenêtre de cinq minutes pour un même utilisateur. Le déclenchement d’une limite de fréquence entraîne une réponse HTTP 429 contenant des informations sur le moment où la prochaine requête pourra être effectuée. Les résultats incluent uniquement les produits détenus directement par le compte d’utilisateur au nom duquel votre service effectue l’appel, ou auxquels ce compte a droit. Les droits d’utilisation partagés qui peuvent apparaître sur le client ne sont pas retournés. Consultez Modèle de partage de produits pour les jeux. Pour obtenir des informations précises sur l’interrogation de l’état de l’abonnement Game Pass d’un utilisateur, consultez Détection de l’accès à l’abonnement XBOX Game Pass à partir de votre service.

publisherQuery prend uniquement en charge les appels provenant des services de partenaires.

Les applications clientes ou les jeux ne peuvent pas appeler ce service directement.

Mises à jour et améliorations de publisherQuery (Collections Query v9)

publisherQuery est la plus récente API Collections Query (v9). Si vous effectuez une migration à partir de b2bLicensePreview (v8), consultez cette section pour connaître les différences de comportement. publisherQuery présente les modifications et améliorations suivantes par rapport à b2bLicensePreview :

Possibilité d’interroger l’état de l’abonnement XBOX Game Pass d’un utilisateur
Nécessite une liste prédéfinie de produits à retourner. Il s’agit d’une pratique exemplaire, mais elle n’est pas obligatoire avec b2bLicensePreview v8. Les titres qui ne suivaient pas cette pratique exemplaire ont souvent connu des problèmes après leur lancement, la requête expirant en raison de la grande quantité de contenu visée par leurs paramètres de requête. Cela empêchait les utilisateurs d’obtenir leurs crédits en jeu jusqu’à ce que le service du jeu soit mis à jour pour spécifier les ProductIds souhaités dans la requête.
Champs de données de réponse simplifiés afin de supprimer les valeurs inutilisées ou superflues
Paramètres de requête simplifiés en fonction des commentaires des développeurs

Éléments retirés du corps de la requête :

Market - Toutes les requêtes ont un contexte couvrant toutes les régions dans publisherQuery
ExpandSatisfyingItems - Tous les résultats développent les droits d’utilisation satisfaisants dans publisherQuery
EntitlementsFilter - Non utilisé, car une liste prédéfinie de productIds est requise pour la requête

publisherQuery ne prend pas en charge les LegacyProductIds (ProductIds générés à partir de l’ancien XBOX Developer Portal, désormais retiré, et utilisés comme ProductId par le service XBOX Inventory).

Si vous migrez votre service à partir de XBOX Inventory, vous devez mapper en interne le StoreId (valeur ProductId de Collections) au LegacyProductId correspondant dans votre propre service. Sinon, vous pouvez envisager b2bLicensePreview v8, qui retourne à la fois le StoreId et les LegacyProductIds. Pour plus d’informations, consultez l’article correspondant Sélection de l’API de requête Collections adaptée à vos besoins

Prérequis

Consultez Prérequis pour les API de service à service. Cette API prend en charge les types d’authentification Microsoft Entra ID et X-token avec authentification déléguée. Si la configuration du produit n’est pas publiée dans Partner Center, les appels peuvent réussir, mais ne retourner aucun résultat.

Requête

Syntaxe de la requête

Méthode	URI de la requête
`POST`	`https://collections.mp.microsoft.com/v9.0/collections/publisherQuery`

En-tête de la requête

En-tête	Type	Description
`Authorization`	`string`	Obligatoire. Soit le X-token d’autorisation déléguée, soit le jeton d’accès au service Microsoft Entra ID, selon le type d’authentification utilisé.
`Signature`	`string`	Obligatoire lors de l’authentification avec des X-tokens.
`User-Agent`	`string`	Recommandé. Aide à identifier votre service pour la journalisation et les enquêtes.
`Host`	`string`	Doit être `collections.mp.microsoft.com`.
`Content-Length`	`number`	La longueur du corps de la requête.
`Content-Type`	`string`	Spécifie le type de la requête et de la réponse. Actuellement, la seule valeur prise en charge est `application/json`.

Corps de la requête

Paramètre	Type	Description	Obligatoire
`beneficiaries`	`UserIdentity`	Utilisateur pour lequel cet article est consommé. Pour plus d’informations, consultez Authentification avec Microsoft Entra ID et les User Store IDs. Non requis pour l’authentification par X-token.	Uniquement pour l’authentification par User Store ID
`productSkuIds`	`list<ProductSkuId>`	Liste des produits ciblés. Pour plus d’informations, consultez le tableau suivant. L’API publisherQuery v9 prend en charge un maximum de 100 productSkuIds par requête.	Oui
`continuationToken`	`string`	S’il existe plusieurs ensembles de produits qui ne tiennent pas dans `maxPageSize`, le corps de la réponse retourne un jeton de continuation lorsque la limite de page est atteinte. Fournissez le jeton de continuation dans les appels suivants pour obtenir plus de résultats.	Non
`maxPageSize`	`number`	Le nombre maximal de produits à retourner dans une réponse. La valeur par défaut est 100 et la valeur maximale est de 200 articles par page.	Non
`excludeDuplicates`	`bool`	Supprime les droits d’utilisation en double lorsque l’utilisateur peut avoir droit à un même produit à partir de plusieurs sources.	Non
`validityType`	`string`	Lorsqu’il est défini sur All, tous les produits d’un utilisateur sont retournés, y compris les articles expirés. Valid retourne les produits ayant un état actif, une date de début < maintenant et une date de fin > maintenant). Invalid retourne les produits qui ne répondent pas aux exigences de l’option Valid.	Non
`sbx`	`string`	Valeur facultative pour l’authentification avec des UserStoreIds qui spécifie le Sandbox auquel les résultats doivent être limités. Sans cette valeur, le sandbox par défaut est RETAIL. L’authentification par X-Token n’a pas besoin de cette valeur, car le Sandbox est spécifié dans le X-Token.	Non
`filterSatisfiedByProductIds`	`bool`	La valeur par défaut est False si elle n’est pas fournie. Lorsque la valeur est False (valeur recommandée), fournit une vue complète d’un droit d’utilisation satisfaisant à partir des ensembles ou produits qui l’accordent dans le champ satisfiedByProductIds. Lorsque la valeur est True, filtre la plupart des ProductIDs satisfaisants du champ satisfiedByProductIds; cette option est fournie à des fins de compatibilité, selon les besoins des services.	Non

L’objet ProductSkuId contient les paramètres suivants.

Paramètre	Type	Description	Obligatoire
`productId`	`string`	Également appelé Store ID du produit dans le catalogue du Microsoft Store. Un exemple de Store ID pour un produit est 9NBLGGH42CFD.	Oui
`skuId`	`string`	L’identificateur de SKU spécifique s’il existe plusieurs offres du produit dans le catalogue du Microsoft Store. Un exemple de Store ID pour un SKU est 0010.	Non

Exemple de requête

L’API publisherQuery v9 prend en charge un maximum de 100 productSkuIds par requête. Si vous fournissez plus de 100 productIds dans productSkuIds, l’API retourne une erreur HTTP 400.

La valeur par défaut de maxPageSize est 100, mais elle est plus basse dans l’exemple afin de montrer comment demander les articles restants.

POST https://collections.mp.microsoft.com/v9.0/collections/publisherQuery HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1...
User-Agent: {identifier string of your service}
Content-Type: application/json; charset=utf-8
Content-Length: 2243

{
  "maxPageSize":2,
  "excludeDuplicates":true,
  "productSkuIds":[
    {"productId": "9N30KZZF4BR9"},
    {"productId": "9MXL21XPWWWK"},
    {"productId": "9PLRFWZWWF91"},
    {"productId": "9MZ0MGGFPLTP"}
  ],
  "beneficiaries": [
    {
      "identityType": "b2b",
      "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
      "localTicketReference": ""
    }
  ],
  "sbx":"XDKS.1",
}

Réponse

Corps de la réponse

Paramètre	Type	Description	Obligatoire
`continuationToken`	`string`	Ce jeton est retourné lorsque la limite de page est atteinte. Vous pouvez spécifier ce jeton de continuation dans les appels suivants pour récupérer les produits restants.	Non
`items`	`PublisherQueryItemContractV9`	Un tableau de produits pour l’utilisateur spécifié. Pour plus d’informations, consultez le tableau suivant.	Non

L’objet PublisherQueryItemContractV9 contient les paramètres suivants.

Paramètre	Type	Description	Obligatoire
`acquiredDate`	`datetime`	Date à laquelle l’utilisateur a acquis l’article.	Oui
`acquisitionType`	`string`	Indique de quelle façon l’utilisateur détient ce droit d’utilisation. Pour plus d’informations, consultez Valeurs d’acquisitionType de produit et leur signification.	Non
`endDate`	`datetime`	La date de fin de l’article.	Oui
`id`	`string`	Un ID qui distingue cet article de collection des autres articles que possède l’utilisateur. Cet ID est unique par produit.	Oui
`modifiedDate`	`datetime`	La date de la dernière modification de cet article. Pour les produits consommables, cette valeur change lorsque le solde de quantité de l’utilisateur change à la suite d’un autre achat du produit consommable ou lorsqu’une requête de consommation est émise.	Oui
`productId`	`string`	Également appelé Store ID du produit dans le catalogue du Microsoft Store. Un exemple de Store ID pour un produit est 9NBLGGH42CFD.	Oui
`productKind`	`string`	Indique le type de produit. Pour plus d’informations, consultez Valeurs de type de produit et leur signification.	Oui
`quantity`	`number`	La quantité de l’article. Les produits non consommables ont toujours la valeur 1. Pour les produits consommables, la valeur représente le solde restant qui peut être consommé ou exécuté pour l’utilisateur.	Non
`recurrenceData`	`string`	ID de l’article utilisé comme paramètre `recurrenceId` des API de gestion des récurrences. Même valeur que `id` de l’API RecurrenceQuery et que `recurrenceId` dans un événement Clawback.	Oui
`satisfiedByProductIds`	`list<string>`	Si l’utilisateur a droit à ce produit en raison d’un ensemble ou d’un abonnement, les `ProductIds` de ces produits parents sont fournis ici. REMARQUE : l’utilisation du paramètre de requête `filterSatisfiedByProductIds` avec la valeur `True` entraînera l’absence de certains résultats dans ce paramètre.	Non
`skuId`	`string`	L’identificateur de SKU spécifique s’il existe plusieurs offres du produit dans le catalogue du Microsoft Store. Un exemple de Store ID pour un SKU est 0010.	Oui
`startDate`	`datetime`	La date à laquelle l’article commence à être valide.	Oui
`status`	`string`	L’état de l’article. Pour plus d’informations, consultez Valeurs d’état de produit et leur signification.	Oui
`tags`	`list<string>`	S.O.	Oui
`transactionId`	`GUID`	L’ID de transaction résultant de l’achat de cet article. Peut être utilisé pour signaler un article comme exécuté. Cette valeur est l’OrderID associé au moment où l’utilisateur a acheté l’article. Ne doit pas être utilisé comme identificateur unique du droit d’utilisation de cet utilisateur	Non
`trialData`	`TrialInformation`	Informations sur ce produit : s’il s’agit d’une version d’évaluation et le temps restant.	Oui

L’objet TrialInformation contient les paramètres présentés dans le tableau suivant.

Paramètre	Type	Description	Obligatoire
`isInTrialPeriod`	`bool`	Indique si le produit est dans une période d’essai, comme pour un abonnement	Oui
`isTrial`	`bool`	Indique si ce produit est concédé sous licence par l’intermédiaire d’une version d’évaluation	Oui
`trialTimeRemaining`	`timespan`	Indique le temps restant pendant lequel la version d’évaluation est valide, au format JJ:HH:MM:SS.MS	Non

Valeurs de type de produit et leur signification

Valeur	Description
`Application`	Une application du Microsoft Store qui n’est pas répertoriée comme un jeu.
`Consumable`	Un consommable géré par le Store, dont le solde (ou la quantité) de l’utilisateur est conservé et géré dans le service Collections. Lors de l’achat, la quantité est ajoutée au solde de l’utilisateur et peut ensuite être retirée en effectuant une requête de consommation. Les utilisateurs peuvent acheter à nouveau ce type de consommable sans qu’il ait d’abord été exécuté.
`Durable`	Un contenu téléchargeable acheté une seule fois et détenu jusqu’à la date de fin du produit. Il s’agit également du type de produit des ensembles d’extensions et des ensembles de laissez-passer saisonniers.
`Game`	Un produit de jeu de base.
`Pass`	Certains types d’abonnements, comme Game Pass
`UnmanagedConsumable`	Également appelé consommable géré par le développeur. Doit être exécuté à partir du jeu ou du service du jeu avant que l’utilisateur puisse acheter le produit à nouveau.
`Pass`	Un abonnement géré par le Store. Différent d’un type d’abonnement d’extension configuré sous la page Extensions d’une application dans Partner Center.

Valeurs d’état de produit et leur signification

Valeur	Description
`Active`	Le droit d’utilisation du produit est actif (y compris pour les articles précommandés). L’utilisateur devrait y avoir accès.
`Revoked`	Indique le plus souvent que l’utilisateur a demandé un remboursement.
`Expired`	Le produit faisait partie d’un droit d’utilisation (généralement un abonnement) qui a depuis expiré.
`Banned`	S.O.
`Suspended`	S.O.

Valeurs d’acquisitionType de produit et leur signification

Valeur	Description
`Single`	Achat numérique direct ou échange de code.
`Recurring`	Détenu ou accordé par l’intermédiaire d’un abonnement.
`Conditional`	Détenu, mais nécessite d’autres produits pour continuer à être utilisé. Ex. : jeux obtenus par Games With Gold

Comprendre les résultats des droits d’utilisation satisfaits avec le champ `satisfiedByProductIds`

Si le tableau satisfiedByProductIds est vide, l’utilisateur détient un droit d’utilisation direct sur l’article à la suite d’un achat direct. Sinon, si le tableau satisfiedByProductIds contient un ou plusieurs ProductIds, l’utilisateur a droit à l’article grâce à ces produits (ensembles, abonnements, etc.). Si l’utilisateur détient à la fois un droit d’utilisation direct et un droit d’utilisation satisfaisant sur un article, et que excludeDuplicates est True dans la requête, le droit d’utilisation direct aura priorité et satisfiedByProductIds sera vide.

Exemple de réponse

HTTP/1.1 200 OK
Date: Wed, 10 Nov 2021 02:21:22 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1115
MS-CorrelationId: d46cbd11-c2cf-4d8b-99b3-ea63ea976f39
MS-RequestId: 76b82179-2c83-41b2-b9f7-6e775f2c0fed
MS-CV: zpiOM+izH0iubCuw.0

{
    "continuationToken": "{\"checkSatisfactionIndex\":2}",
    "items": [
        {
            "acquiredDate": "2021-08-30T21:53:08.2565331+00:00",
            "acquisitionType": "Single",
            "endDate": "2021-08-31T21:53:07.4374279+00:00",
            "id": "1046015f83a8478397064c915224e5d3",
            "modifiedDate": "2021-08-30T21:53:08.2589804+00:00",
            "productId": "9N30KZZF4BR9",
            "productKind": "Durable",
            "quantity": 1,
            "satisfiedByProductIds": [],
            "skuId": "0010",
            "startDate": "2021-08-30T21:53:07.4374279+00:00",
            "status": "Active",
            "tags": [],
            "transactionId": "995ec667-8114-4ab9-9f11-597a8419a775",
            "trialData": {
                "isInTrialPeriod": false,
                "isTrial": false
            }
        },
        {
            "acquiredDate": "2021-08-30T19:55:44.7994325+00:00",
            "acquisitionType": "Single",
            "endDate": "9999-12-31T23:59:59.9999999+00:00",
            "id": "27662ad4749342608ec09130b76601f9",
            "modifiedDate": "2021-08-30T19:55:44.8043849+00:00",
            "productId": "9MXL21XPWWWK",
            "productKind": "Game",
            "quantity": 1,
            "satisfiedByProductIds": [],
            "skuId": "0010",
            "startDate": "2021-08-30T19:40:44.7994325+00:00",
            "status": "Active",
            "tags": [
                "4c584d39-3132-3058-c050-5757574b8500"
            ],
            "transactionId": "8d5ed958-6c72-4812-87fc-57b105d3d197",
            "trialData": {
                "isInTrialPeriod": true,
                "isTrial": true,
                "trialTimeRemaining": "09:43:52.8580690"
            }
        }
    ]
}

Demande des résultats restants avec le jeton de continuation

Si votre requête comporte plus de résultats que ne peut en retourner une seule réponse (selon la valeur de maxPageSize), la réponse à votre requête initiale contient un continuationToken. Vous pouvez ensuite utiliser ce continuationToken dans une requête subséquente en ajoutant le jeton de continuation à une copie du corps de la requête précédente. Exemple de requête de continuation :

POST https://collections.mp.microsoft.com/v9.0/collections/publisherQuery HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1...
User-Agent: {identifier string of your service}
Content-Type: application/json; charset=utf-8
Content-Length: 2243

{
  "continuationToken":"{\"checkSatisfactionIndex\":2}",
  "maxPageSize":2,
  "excludeDuplicates":true,
  "productSkuIds":[
    {"productId": "9N30KZZF4BR9"},
    {"productId": "9MXL21XPWWWK"},
    {"productId": "9PLRFWZWWF91"},
    {"productId": "9MZ0MGGFPLTP"}
  ],
  "beneficiaries": [
    {
      "identityType": "b2b",
      "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
      "localTicketReference": ""
    }
  ],
  "sbx":"XDKS.1",
}

Même si vous spécifiez l’indicateur excludeDuplicates, lorsque vous utilisez un jeton de continuation, il est possible d’obtenir des entrées de droits d’utilisation ayant un état différent. Vérifiez donc les résultats pour repérer les entrées en double et déterminer si leur état est autre que Active.

Voir aussi

Gérer les produits à partir de vos services Authentification de votre service avec les API du Microsoft Store Gestion des produits consommables à partir de votre service

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

collections.mp.microsoft.com/v9.0/collections/publisherQuery

Mises à jour et améliorations de publisherQuery (Collections Query v9)

Prérequis

Requête

Syntaxe de la requête

En-tête de la requête

Corps de la requête

Exemple de requête

Réponse

Corps de la réponse

Valeurs de type de produit et leur signification

Valeurs d’état de produit et leur signification

Valeurs d’acquisitionType de produit et leur signification

Comprendre les résultats des droits d’utilisation satisfaits avec le champ `satisfiedByProductIds`

Exemple de réponse

Demande des résultats restants avec le jeton de continuation

Voir aussi

​Mises à jour et améliorations de publisherQuery (Collections Query v9)

​Prérequis

​Requête

​Syntaxe de la requête

​En-tête de la requête

​Corps de la requête

​Exemple de requête

​Réponse

​Corps de la réponse

​Valeurs de type de produit et leur signification

​Valeurs d’état de produit et leur signification

​Valeurs d’acquisitionType de produit et leur signification

​Comprendre les résultats des droits d’utilisation satisfaits avec le champ satisfiedByProductIds

​Exemple de réponse

​Demande des résultats restants avec le jeton de continuation

​Voir aussi

Mises à jour et améliorations de publisherQuery (Collections Query v9)

Prérequis

Requête

Syntaxe de la requête

En-tête de la requête

Corps de la requête

Exemple de requête

Réponse

Corps de la réponse

Valeurs de type de produit et leur signification

Valeurs d’état de produit et leur signification

Valeurs d’acquisitionType de produit et leur signification

Comprendre les résultats des droits d’utilisation satisfaits avec le champ `satisfiedByProductIds`

Exemple de réponse

Demande des résultats restants avec le jeton de continuation

Voir aussi