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

publisherQuery permet à vos propres services d’interroger les produits et les droits 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 indiquant quand la prochaine requête peut être effectuée. Les résultats incluent uniquement les produits directement possédés par le compte d’utilisateur pour le compte duquel votre service effectue l’appel, ou auxquels ce compte a droit. Les droits partagés qui peuvent apparaître sur le client ne sont pas renvoyés. Consultez Modèle de partage de produits pour les jeux. Pour obtenir des informations spécifiques 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 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 dernière API Collections Query (v9). Si vous effectuez une migration depuis 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
Exige une liste prédéfinie de produits à renvoyer. Il s’agissait d’une bonne pratique, mais non obligatoire, avec b2bLicensePreview v8. Les titres qui ne suivaient pas cette bonne pratique rencontraient souvent des problèmes après leur sortie, la requête expirant en raison de l’étendue importante du contenu déterminé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 pour supprimer les valeurs inutilisées ou superflues
Paramètres de requête simplifiés en fonction des commentaires des développeurs

Supprimés du corps de la requête :

Market : toutes les requêtes disposent du contexte de toutes les régions dans publisherQuery
ExpandSatisfyingItems : tous les résultats développent les droits satisfaisants dans publisherQuery
EntitlementsFilter : non utilisé, car une liste prédéfinie de productIds est obligatoire 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 depuis XBOX Inventory, vous devez mapper en interne le StoreId (valeur ProductId de Collections) au LegacyProductId correspondant sur votre propre service. Sinon, vous pouvez utiliser b2bLicensePreview v8, qui renvoie à 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 d’autorisation déléguée. Si la configuration du produit n’est pas publiée dans Partner Center, les appels peuvent réussir mais ne renvoyer aucun résultat.

Requête

Syntaxe de la requête

Méthode	URI de 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. X-token d’autorisation déléguée ou jeton d’accès au service Microsoft Entra ID, selon le type d’authentification utilisé.
`Signature`	`string`	Obligatoire pour l’authentification avec des X-tokens.
`User-Agent`	`string`	Recommandé. Permet d’identifier votre service pour la journalisation et les investigations.
`Host`	`string`	Doit être `collections.mp.microsoft.com`.
`Content-Length`	`number`	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 élément est consommé. Pour plus d’informations, consultez Authentification avec Microsoft Entra ID et les ID Store utilisateur. Non obligatoire pour l’authentification X-token.	Uniquement pour l’authentification par ID Store utilisateur
`productSkuIds`	`list<ProductSkuId>`	Liste des produits cibles. 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 renvoie un jeton de continuation lorsque la limite de page est atteinte. Fournissez ce jeton de continuation dans les appels suivants pour obtenir davantage de résultats.	Non
`maxPageSize`	`number`	Nombre maximal de produits à renvoyer dans une réponse. La valeur par défaut est 100 et la valeur maximale est de 200 éléments par page.	Non
`excludeDuplicates`	`bool`	Supprime les droits en double lorsque l’utilisateur peut avoir droit à un même produit par plusieurs sources.	Non
`validityType`	`string`	Lorsque la valeur est All, tous les produits d’un utilisateur sont renvoyés, y compris les éléments expirés. Valid renvoie les produits dont l’état est actif, dont la date de début est < maintenant et dont la date de fin est > maintenant). Invalid renvoie 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 RETAIL est utilisé par défaut. L’authentification 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. Avec False (valeur recommandée), le champ satisfiedByProductIds fournit une vue complète d’un droit satisfaisant issu des packs ou produits qui l’accordent. Avec True, la plupart des ProductIDs satisfaisants sont filtrés 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é ID Store du produit dans le catalogue du Microsoft Store. Exemple d’ID Store pour un produit : 9NBLGGH42CFD.	Oui
`skuId`	`string`	Identificateur de SKU spécifique s’il existe plusieurs offres du produit dans le catalogue du Microsoft Store. Exemple d’ID Store pour une SKU : 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 renvoie une erreur HTTP 400.

La valeur par défaut de maxPageSize est 100, mais elle est plus faible dans cet exemple afin d’illustrer la demande des éléments 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 renvoyé 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`	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’élément.	Oui
`acquisitionType`	`string`	Indique la manière dont l’utilisateur dispose de ce droit. Pour plus d’informations, consultez Valeurs et signification de acquisitionType.	Non
`endDate`	`datetime`	Date de fin de l’élément.	Oui
`id`	`string`	ID qui distingue cet élément de collection des autres éléments que possède l’utilisateur. Cet ID est unique par produit.	Oui
`modifiedDate`	`datetime`	Date de la dernière modification de cet élément. Pour les produits consommables, cette valeur change lorsque le solde de quantité de l’utilisateur change à la suite d’un nouvel achat du produit consommable ou de l’émission d’une requête de consommation.	Oui
`productId`	`string`	Également appelé ID Store du produit dans le catalogue du Microsoft Store. Exemple d’ID Store pour un produit : 9NBLGGH42CFD.	Oui
`productKind`	`string`	Indique le type de produit. Pour plus d’informations, consultez Valeurs et signification des types de produits.	Oui
`quantity`	`number`	Quantité de l’élément. Elle est toujours de 1 pour les produits non consommables. Pour les produits consommables, la valeur représente le solde restant pouvant être consommé ou traité pour l’utilisateur.	Non
`recurrenceData`	`string`	ID de l’élément utilisé comme paramètre `recurrenceId` des API de gestion des récurrences. Même valeur que `id` dans 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 pack 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îne l’absence de certains résultats dans ce paramètre.	Non
`skuId`	`string`	Identificateur de SKU spécifique s’il existe plusieurs offres du produit dans le catalogue du Microsoft Store. Exemple d’ID Store pour une SKU : 0010.	Oui
`startDate`	`datetime`	Date à partir de laquelle l’élément devient valide.	Oui
`status`	`string`	État de l’élément. Pour plus d’informations, consultez Valeurs et signification des états de produit.	Oui
`tags`	`list<string>`	N/A.	Oui
`transactionId`	`GUID`	ID de transaction résultant de l’achat de cet élément. Peut être utilisé pour signaler qu’un élément a été traité. Cette valeur est l’OrderID associé au moment où l’utilisateur a acheté l’élément. Ne doit pas être utilisé comme identificateur unique du droit de cet utilisateur	Non
`trialData`	`TrialInformation`	Informations sur ce produit : s’il s’agit d’une version d’essai 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 en période d’essai, comme un abonnement	Oui
`isTrial`	`bool`	Indique si ce produit est concédé sous licence par le biais d’une version d’essai	Oui
`trialTimeRemaining`	`timespan`	Indique la durée de validité restante de la version d’essai au format DD:HH:MM:SS.MS	Non

Valeurs et signification des types de produits

Valeur	Description
`Application`	Application du Microsoft Store qui n’est pas répertoriée comme un jeu.
`Consumable`	Consommable géré par le Store, dont le solde (ou la quantité) de l’utilisateur est conservé et géré par le service Collections. Lors de l’achat, la quantité est ajoutée au solde de l’utilisateur et peut ensuite être retirée au moyen d’une requête de consommation. Les utilisateurs peuvent racheter ce type de consommable sans qu’il ait été traité au préalable.
`Durable`	Contenu téléchargeable acheté une seule fois et possédé jusqu’à la date de fin du produit. Il s’agit également du type de produit des packs d’extensions et des packs Season Pass.
`Game`	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 traité par le jeu ou le service du jeu avant que l’utilisateur puisse racheter le produit.
`Pass`	Abonnement géré par le Store. Différent du type d’abonnement d’extension configuré dans la page Extensions d’une application dans Partner Center.

Valeurs et signification des états de produit

Valeur	Description
`Active`	Le droit sur le produit est actif (y compris les éléments précommandés). L’utilisateur doit y avoir accès.
`Revoked`	Indique le plus souvent que l’utilisateur a demandé un remboursement.
`Expired`	Le produit faisait partie d’un droit (généralement un abonnement) qui a depuis expiré.
`Banned`	N/A.
`Suspended`	N/A.

Valeurs et signification de acquisitionType

Valeur	Description
`Single`	Achat numérique direct ou utilisation d’un code.
`Recurring`	Possédé ou accordé par le biais d’un abonnement.
`Conditional`	Possédé, mais nécessite d’autres produits pour continuer à être utilisé. Ex. : jeux obtenus avec Games With Gold

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

Si le tableau satisfiedByProductIds est vide, l’utilisateur dispose d’un droit direct sur l’élément, issu d’un achat direct. Sinon, si le tableau satisfiedByProductIds contient un ou plusieurs ProductIds, l’utilisateur a droit à l’élément par le biais de ces produits (packs, abonnements, etc.). Si l’utilisateur dispose à la fois d’un droit direct et d’un droit satisfaisant sur un élément, et que excludeDuplicates a la valeur True dans la requête, le droit direct est prioritaire et satisfiedByProductIds est 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 ce qui peut être renvoyé dans une seule réponse (contrôlé par maxPageSize), la réponse à votre requête initiale contient un continuationToken. Vous pouvez ensuite utiliser ce continuationToken dans une requête de suivi 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, lors de l’utilisation d’un jeton de continuation, il est possible d’obtenir des entrées de droits ayant des états différents. Vérifiez donc les résultats pour détecter les entrées en double et celles dont l’état n’est pas Active.

Voir aussi

Gérer les produits à partir de vos services Authentifier votre service auprès des API du Microsoft Store Gérer les 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 et signification des types de produits

Valeurs et signification des états de produit

Valeurs et signification de acquisitionType

Comprendre les résultats des droits 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 et signification des types de produits

​Valeurs et signification des états de produit

​Valeurs et signification de acquisitionType

​Comprendre les résultats des droits 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 et signification des types de produits

Valeurs et signification des états de produit

Valeurs et signification de acquisitionType

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

Exemple de réponse

Demande des résultats restants avec le jeton de continuation

Voir aussi