API b2bLicensePreview de Microsoft Store v8 Collections

L’API b2bLicensePreview permet à vos propres services d’interroger les produits et les droits d’utilisation d’un utilisateur. Vous pouvez limiter votre requête à des produits ou à des types de produits particuliers, ou utiliser d’autres filtres dans votre requête. 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. Pour plus d’informations sur les scénarios de partage, consultez Modèle de partage de produits pour les jeux.

Pour éviter les expirations de délai de réponse et les longs temps de réponse, vous devez toujours spécifier les produits exacts que vous souhaitez obtenir dans vos résultats à l’aide du paramètre productSkuIds dans la requête.

Un appel sans la liste productSkuIds entraîne des temps de réponse plus longs, qui augmentent en fonction du nombre total de droits d’utilisation et d’achats effectués par l’utilisateur sur XBOX et dans l’application Microsoft Store.

b2bLicensePreview est destiné aux appels provenant des services de partenaires.

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

b2bLicensePreview (Collections v8) ou publisherQuery (Collections v9) pour interroger les produits

b2bLicensePreview (Collections v8) est l’ancien service Collections permettant d’interroger les droits d’utilisation des utilisateurs, mais il reste disponible pour les partenaires. publisherQuery (Collections v9) est le plus récent et offre des fonctionnalités étendues, comme l’exposition de l’état de l’abonnement XBOX Game Pass. Il existe encore des scénarios dans lesquels les partenaires pourraient vouloir utiliser b2bLicensePreview, comme la prise en charge des LegacyProductIds utilisés par le service XBOX Inventory. Pour plus d’informations, consultez l’article correspondant Sélection de l’API de requête Collections adaptée à vos besoins

Requête

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.

Syntaxe de la requête

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

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 Microsoft Entra ID, selon le type d’authentification utilisé.
`Signature`	`string`	Obligatoire lors de l’authentification avec des X-tokens. Non requis pour l’authentification par User Store ID.
`User-Agent`	`string`	Facultatif, mais recommandé. Aide à identifier votre service pour la journalisation et les enquêtes.
`Host`	`string`	Doit être défini sur la valeur `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>`	S’il est spécifié, le service retourne uniquement les produits applicables aux paires produit/SKU fournies. Recommandé pour toutes les requêtes de service à service afin d’obtenir des résultats plus rapides et plus fiables. Pour plus d’informations, consultez le tableau suivant.	Non
`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. Pour récupérer les résultats restants de votre requête, fournissez le `continuationToken` dans les appels suivants.	Non
`maxPageSize`	`number`	Le nombre maximal de produits à retourner dans une réponse. La valeur par défaut et maximale est 100.	Non
`entitlementFilters`	`list<string>`	Spécifie les types de produits à retourner dans les résultats de la requête. Pour obtenir la liste des valeurs valides, consultez Valeurs de type de produit et leur signification.	Non
`market`	`string`	Le pays, la région ou le marché pour lequel vous souhaitez vérifier le droit d’utilisation. L’utilisation de « neutral » (recommandé) effectue la recherche dans tous les marchés. Sinon, utilisez le code de pays/région ISO 3166 à deux caractères, par exemple US.	Oui
`expandSatisfyingItems`	`bool`	Inclut dans les résultats les articles accordés par l’intermédiaire d’ensembles ou d’abonnements. S’il est défini sur `false`, les résultats contiennent uniquement les articles achetés par l’utilisateur, comme les informations du produit de l’ensemble parent. Si vous utilisez ce paramètre, spécifiez toujours les produits pour lesquels vous voulez des résultats afin d’éviter les requêtes longues ou expirées.	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

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/v8.0/collections/b2bLicensePreview HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1EtNTBjQ0g0e...
User-Agent: MicrosoftStoreServiceSample_1.21.9.0
Content-Type: application/json; charset=utf-8
Content-Length: 2032

{
    "maxPageSize": 2,
    "excludeDuplicates": true,
    "entitlementFilters": [
        "*:Game",
        "*:Consumable",
        "*:UnmanagedConsumable",
        "*:Durable",
        "*:Pass"
    ],
    "market": "neutral",
    "expandSatisfyingItems": true,
    "productSkuIds": [
        {"productId": "9N30KZZF4BR9"},
        {"productId": "9MXL21XPWWWK"},
        {"productId": "9PLRFWZWWF91"},
        {"productId": "9MZ0MGGFPLTP"}
    ],
    "beneficiaries": [
        {
            "identityType": "b2b",
            "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4...",
            "localTicketReference": ""
        }
    ],
    "sbx": "XDKS.1"
}

Réponse

Corps de la réponse

Paramètre	Type	Description	Obligatoire
`continuationToken`	`string`	S’il existe plusieurs ensembles de produits, 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`	`CollectionItemContractV8`	Un tableau de produits pour l’utilisateur spécifié. Pour plus d’informations, consultez le tableau suivant.	Non

L’objet CollectionItemContractV8 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
`devOfferId`	`string`	L’ID d’offre provenant d’un achat intégré à l’application.	Non
`endDate`	`datetime`	La date de fin de l’article.	Oui
`inAppOfferToken`	`string`	La chaîne d’ID de produit spécifiée par le développeur et attribuée à l’article dans Partner Center. Un exemple d’ID de produit est product123.	Non
`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
`legacyOfferInstanceId`	`string`	La valeur `offerInstanceId` fournie si la requête était adressée à l’ancien service XBOX Inventory. Ne devrait pas être nécessaire dans la plupart des cas.	Non
`legacyProductId`	`string`	L’ancien format de `ProductID` provenant du XBOX Developer Portal et utilisé par le service XBOX Inventory. Les nouveaux produits créés dans Partner Center n’ont pas cette valeur par défaut, mais peuvent être inscrits pour l’obtenir au besoin.	Non
`localTicketReference`	`string`	L’ID du `localTicketReference` fourni précédemment dans le corps de la requête.	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
`productFamily`	`string`	Indique le type de produit auquel le produit est lié. Habituellement « Games », mais peut aussi être vide pour le contenu lié aux jeux.	Non
`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
`productType`	`string`	Indique le type de produit. Pour plus d’informations, consultez Valeurs de type de produit et leur signification.	Oui
`purchasedCountry`	`string`	Le code de pays/région ISO 3166 à deux caractères indiquant le magasin régional dans lequel le produit a été acquis.	Non
`quantity`	`number`	La quantité de l’article. Les produits non consommables ont toujours la valeur 1. Pour les produits consommables, cette valeur représente le solde restant qui peut être consommé ou exécuté pour l’utilisateur.	Non
`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
`sharingSource`	`string`	Indique si l’utilisateur a droit à l’article en raison d’un scénario de partage. Cependant, avec les appels de service à service, les résultats sont toujours limités aux droits d’utilisation détenus directement, et la valeur retournée devrait toujours être `None`.	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`	`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
`isTrial`	`bool`	Indique si ce produit est concédé sous licence par l’intermédiaire d’une version d’évaluation	Oui
`isInTrialPeriod`	`bool`	Indique si le produit est dans une période d’essai, comme pour un abonnement	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
`Game`	Un produit de jeu de base ou un ensemble de jeux.
`Application`	Une application du Microsoft Store qui n’est pas répertoriée comme un jeu.
`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.
`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é.
`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 abonnement d’extension, qui est 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. 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:29:18 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1744
MS-CorrelationId: aadb976e-634e-4e63-92b1-93af49883b43
MS-RequestId: afeb8062-41e3-486e-b6c5-ec53a417bef3
MS-CV: BW/uJSvAbU6p3rbS.0
X-Content-Type-Options: nosniff

{
    "continuationToken": "{\"checkSatisfactionIndex\":2}",
    "items": [
        {
            "acquiredDate": "2021-08-30T21:53:08.2565331+00:00",
            "acquisitionType": "Single",
            "beneficiary": {
                "identityType": "pub",
                "identityValue": "NoUserIdProvided"
            },
            "devOfferId": "",
            "endDate": "2021-08-31T21:53:07.4374279+00:00",
            "id": "1046015f83a8478397064c915224e5d3",
            "legacyOfferInstanceId": "fb758141-05cf-406d-b004-57e2a7c0d889",
            "legacyProductId": "fb758141-05cf-406d-b004-57e2a7c0d889",
            "localTicketReference": "",
            "modifiedDate": "2021-08-30T21:53:08.2589804+00:00",
            "purchasedCountry": "US",
            "productFamily": "",
            "productId": "9N30KZZF4BR9",
            "productKind": "Durable",
            "quantity": 1,
            "recurrenceData": {},
            "satisfiedByProductIds": [],
            "sharingSource": "None",
            "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",
            "beneficiary": {
                "identityType": "pub",
                "identityValue": "NoUserIdProvided"
            },
            "endDate": "9999-12-31T23:59:59.9999999+00:00",
            "id": "27662ad4749342608ec09130b76601f9",
            "legacyOfferInstanceId": "4c584d39-3132-3058-c050-5757574b8500",
            "legacyProductId": "4c584d39-3132-3058-c050-5757574b8500",
            "localTicketReference": "",
            "modifiedDate": "2021-08-30T19:55:44.8043849+00:00",
            "purchasedCountry": "US",
            "productFamily": "Games",
            "productId": "9MXL21XPWWWK",
            "productKind": "Game",
            "quantity": 1,
            "recurrenceData": {},
            "satisfiedByProductIds": [],
            "sharingSource": "None",
            "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, un continuationToken est fourni dans la dernière réponse. Vous utilisez ce continuationToken dans une requête subséquente en l’ajoutant à une copie du corps de la requête précédente. Exemple :

POST https://collections.mp.microsoft.com/v8.0/collections/b2bLicensePreview HTTP/1.1
Host: collections.mp.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imwzc1EtNTBjQ0g0e...
User-Agent: MicrosoftStoreServiceSample_1.21.9.0
Content-Type: application/json; charset=utf-8
Content-Length: 2032

{
    "continuationToken": "{\"checkSatisfactionIndex\":2}",
    "maxPageSize": 2,
    "excludeDuplicates": true,
    "entitlementFilters": [
        "*:Game",
        "*:Consumable",
        "*:UnmanagedConsumable",
        "*:Durable",
        "*:Pass"
    ],
    "market": "neutral",
    "expandSatisfyingItems": true,
    "productSkuIds": [
        {"productId": "9N30KZZF4BR9"},
        {"productId": "9MXL21XPWWWK"},
        {"productId": "9PLRFWZWWF91"},
        {"productId": "9MZ0MGGFPLTP"}
    ],
    "beneficiaries": [
        {
            "identityType": "b2b",
            "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4...",
            "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 Renouvellement d’une clé User Store ID

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

b2bLicensePreview (Collections v8) ou publisherQuery (Collections v9) pour interroger les produits

Requête

Prérequis

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

​b2bLicensePreview (Collections v8) ou publisherQuery (Collections v9) pour interroger les produits

​Requête

​Prérequis

​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

b2bLicensePreview (Collections v8) ou publisherQuery (Collections v9) pour interroger les produits

Requête

Prérequis

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