> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# collections.mp.microsoft.com/v9.0/collections/publisherQuery
> API publisherQuery de Collections Microsoft Store v9 permettant aux services de jeu d'interroger les produits, les droits et l'état de l'abonnement XBOX Game Pass d'un utilisateur.
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](https://learn.microsoft.com/fundamentals/xstore-product-sharing-model-for-games).
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](/fr/publishing/xstore-commerce/xstore-detecting-game-pass).
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](https://learn.microsoft.com/reference/xstore-query-user-entitlements#selecting-the-right-collections-query-api-for-your-needs)
### Prérequis
Consultez [Prérequis pour les API de service à service](https://learn.microsoft.com/reference/service-to-service-nav#prerequisites-for-service-to-service-apis).
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](https://learn.microsoft.com/reference/xstore-authenticating-your-service#authenticating-with-microsoft-entra-id-and-user-store-ids). Non obligatoire pour l'authentification X-token. | Uniquement pour l'authentification par ID Store utilisateur |
| `productSkuIds` | `list` | 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.
```html theme={null}
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](#product-acquisitiontype-values-and-meaning). | 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](#product-type-values-and-meaning). | 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](/fr/reference/microsoft-store-apis/xstore-v8-recurrence-query) et que `recurrenceId` dans un événement Clawback. | Oui |
| `satisfiedByProductIds` | `list` | 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](#product-status-values-and-meaning). | Oui |
| `tags` | `list` | 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
```json theme={null}
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 :
```html theme={null}
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](https://learn.microsoft.com/reference/service-to-service-nav)
[Authentifier votre service auprès des API du Microsoft Store](https://learn.microsoft.com/reference/xstore-authenticating-your-service)
[Gérer les produits consommables à partir de votre service](https://learn.microsoft.com/reference/xstore-managing-consumables-and-refunds)
## Related topics
- [collections.mp.microsoft.com/v9.0/collections/publisherQuery](/reference/microsoft-store-apis/xstore-v9-query-for-products.md)
- [Microsoft Store service APIs](/reference/microsoft-store-apis/xstore-nav.md)
- [Detect XBOX Game Pass subscription access from your service](/publishing/xstore-commerce/xstore-detecting-game-pass.md)
- [APIs de servicio de Microsoft Store](/es/reference/microsoft-store-apis/xstore-nav.md)
- [Detección del acceso a la suscripción a XBOX Game Pass desde su servicio](/es/publishing/xstore-commerce/xstore-detecting-game-pass.md)