API b2bLicensePreview de Collections Microsoft Store v8

L’API b2bLicensePreview permet à vos propres services d’interroger les produits et les droits 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 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. Pour plus d’informations sur les scénarios de partage, consultez Modèle de partage de produits pour les jeux.

Pour éviter les dépassements de délai et les temps de réponse longs, vous devez toujours spécifier les produits exacts que vous souhaitez obtenir dans vos résultats à l’aide du paramètre productSkuIds de 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 et d’achats effectués par l’utilisateur sur XBOX et dans l’application Microsoft Store.

b2bLicensePreview est destiné aux appels provenant des services 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 des utilisateurs, mais il reste disponible pour les partenaires. publisherQuery (Collections v9) est la version la plus récente 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 peuvent souhaiter utiliser b2bLicensePreview, par exemple pour 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 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.

Syntaxe de la requête

Méthode	URI de 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. X-token d’autorisation déléguée ou jeton d’accès Microsoft Entra ID, selon le type d’authentification utilisé.
`Signature`	`string`	Obligatoire pour l’authentification avec des X-tokens. Non obligatoire pour l’authentification par ID Store utilisateur.
`User-Agent`	`string`	Facultatif mais recommandé. Permet d’identifier votre service pour la journalisation et les investigations.
`Host`	`string`	Doit être défini sur la valeur `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>`	Si ce paramètre est spécifié, le service renvoie uniquement les produits correspondant 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 renvoie 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`	Nombre maximal de produits à renvoyer dans une réponse. La valeur par défaut et maximale est 100.	Non
`entitlementFilters`	`list<string>`	Spécifie les types de produits à renvoyer dans les résultats de la requête. Pour obtenir la liste des valeurs valides, consultez Valeurs et signification des types de produits.	Non
`market`	`string`	Pays/région/marché pour lequel vous souhaitez vérifier le droit. 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 éléments accordés par le biais de packs ou d’abonnements. Si la valeur est `false`, les résultats contiennent uniquement les éléments achetés par l’utilisateur, comme les informations produit du pack parent. Si vous utilisez ce paramètre, spécifiez toujours les produits pour lesquels vous souhaitez des résultats afin d’éviter des requêtes longues ou qui expirent.	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

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/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 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`	`CollectionItemContractV8`	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’é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
`devOfferId`	`string`	ID d’offre provenant d’un achat dans l’application.	Non
`endDate`	`datetime`	Date de fin de l’élément.	Oui
`inAppOfferToken`	`string`	Chaîne d’ID de produit spécifiée par le développeur et attribuée à l’élément dans Partner Center. Exemple d’ID de produit : product123.	Non
`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
`legacyOfferInstanceId`	`string`	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`	Ancien format `ProductID` issu 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 si nécessaire.	Non
`localTicketReference`	`string`	ID du `localTicketReference` fourni précédemment dans le corps de la requête.	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
`productFamily`	`string`	Indique le type de produit auquel le produit se rapporte. Généralement « Games », mais peut aussi être vide pour le contenu lié à un jeu.	Non
`productId`	`string`	Également appelé ID Store du produit dans le catalogue du Microsoft Store. Exemple d’ID Store pour un produit : 9NBLGGH42CFD.	Oui
`productType`	`string`	Indique le type de produit. Pour plus d’informations, consultez Valeurs et signification des types de produits.	Oui
`purchasedCountry`	`string`	Code de pays/région ISO 3166 à deux caractères indiquant le Store régional dans lequel le produit a été acquis.	Non
`quantity`	`number`	Quantité de l’élément. Elle est toujours de 1 pour les produits non consommables. Pour les produits consommables, cette valeur représente le solde restant pouvant être consommé ou traité pour l’utilisateur.	Non
`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
`sharingSource`	`string`	Indique si l’utilisateur a droit à l’élément en raison d’un scénario de partage. Toutefois, avec les appels de service à service, les résultats sont toujours limités aux droits directement possédés et la valeur renvoyée devrait toujours être `None`.	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`	`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
`isTrial`	`bool`	Indique si ce produit est concédé sous licence par le biais d’une version d’essai	Oui
`isInTrialPeriod`	`bool`	Indique si le produit est en période d’essai, comme un abonnement	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
`Game`	Produit de jeu de base ou pack de jeu.
`Application`	Application du Microsoft Store qui n’est pas répertoriée comme un jeu.
`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.
`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.
`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 d’un abonnement d’extension, qui est 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. 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: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 ce qui peut être renvoyé dans une seule réponse, un continuationToken est fourni dans la dernière réponse. Vous utilisez ce continuationToken dans une requête de suivi 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, 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 Renouveler une clé d’ID Store utilisateur

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 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

​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 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

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 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