> ## 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 Microsoft Store v9 Collections qui permet aux services de jeu d'interroger les produits, les droits d'utilisation 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'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](https://learn.microsoft.com/fundamentals/xstore-product-sharing-model-for-games). 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](/fr-CA/publishing/xstore-commerce/xstore-detecting-game-pass). 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](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 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](https://learn.microsoft.com/reference/xstore-authenticating-your-service#authenticating-with-microsoft-entra-id-and-user-store-ids). Non requis pour l'authentification par X-token. | Uniquement pour l'authentification par User Store ID | | `productSkuIds` | `list` | 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. ```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 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](#product-acquisitiontype-values-and-meaning). | 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](#product-type-values-and-meaning). | 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](/fr-CA/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 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](#product-status-values-and-meaning). | Oui | | `tags` | `list` | 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 ```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 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 : ```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, 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](https://learn.microsoft.com/reference/service-to-service-nav) [Authentification de votre service avec les API du Microsoft Store](https://learn.microsoft.com/reference/xstore-authenticating-your-service) [Gestion des 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)