collections.mp.microsoft.com/v8.0/collections/consume

Utilisez l’API Consume pour gérer ces types de consommables du Microsoft Store :

Consommable géré par le Store : Signalez une quantité comme consommée et retirez-la du solde de quantité actuel de l’utilisateur spécifié. Les utilisateurs peuvent racheter les consommables gérés par le Store à plusieurs reprises sans que votre service ait à les signaler comme consommés ou exécutés. Pour plus d’informations, consultez Requête de consommation gérée par le Store.
Consommable géré par le développeur : Signalez un produit consommable comme exécuté pour un utilisateur spécifié. Avant qu’un utilisateur puisse racheter un produit consommable géré par le développeur, votre application ou votre service doit signaler le produit consommable comme exécuté pour cet utilisateur. Pour plus d’informations, consultez Requête de consommation gérée par le développeur.

Utilisation de `trackingId` pour valider l’exécution

trackingId permet une validation de l’exécution sécuritaire en cas de nouvelle tentative. Si votre service ne reçoit pas de réponse de confirmation, renvoyez le même corps de requête. Le service reconnaît les requêtes antérieures et traite les nouvelles tentatives comme des vérifications de confirmation. Chaque requête à l’API doit avoir un trackingId unique. Si la requête d’origine n’a pas réussi ou si la réponse n’a pas été reçue, le service effectue la transaction demandée lors de la nouvelle tentative. Si l’exécution a été effectuée lors d’une requête précédente, l’API reconnaît la requête et envoie une réponse de confirmation. Dans ce cas, l’API n’effectue pas une deuxième exécution ni une deuxième déduction du solde de l’utilisateur. L’API répond plutôt par un succès, comme si l’article avait été consommé, avec le solde restant de l’utilisateur. Par conséquent, mettez en cache les valeurs et le trackingId de chaque requête sur votre serveur ou dans vos journaux jusqu’à ce que vous receviez une réponse confirmant que la requête a été exécutée. Pour un exemple, consultez le Game Service Sample. Lorsque votre requête contient le paramètre includeOrderIds, les comportements suivants sont attendus selon le type de produit du consommable :

Type de consommable	Comportement de la première requête de consommation	Comportement de la nouvelle tentative de consommation
Géré par le Store	Les OrderIds utilisés pour exécuter la requête sont retournés	Les mêmes OrderIds utilisés pour exécuter la requête sont retournés
Géré par le développeur	Les OrderIds utilisés pour exécuter la requête sont retournés	Aucun OrderID n’est retourné, car ces données ne sont pas suivies pour ce type de produit

Si vous utilisez des consommables gérés par le développeur, vous ne pouvez pas obtenir les ID de commande à partir d’une nouvelle tentative.

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.

Limitation des bacs à sable pour les consommables gérés par le développeur : Lorsque vous consommez des produits consommables gérés par le développeur dans un bac à sable de développement (autre que RETAIL), l’authentification au moyen d’un User Store ID ou de Microsoft Entra ID n’est pas prise en charge. Dans les environnements de bac à sable, vous devez utiliser des jetons XSTS d’autorisation déléguée pour consommer correctement les produits consommables gérés par le développeur. Cette limitation ne s’applique pas aux consommables gérés par le Store ni au bac à sable RETAIL.

Si vous ne publiez pas la configuration du produit dans Partner Center, les appels peuvent réussir, mais ne retourner aucun résultat.

Codes d’erreur de l’authentification par User Store ID

Code	Erreur	Code d’erreur interne	Description
401	Unauthorized	AuthenticationTokenInvalid	Le jeton d’accès Microsoft Entra ID n’est pas valide. Dans certains cas, le détail de `ServiceError` contient plus d’informations, par exemple lorsque le jeton est expiré ou que la revendication `appid` est manquante.
401	Unauthorized	PartnerAadTicketRequired	Aucun jeton d’accès Microsoft Entra ID n’a été transmis au service dans l’en-tête d’autorisation.
401	Unauthorized	InconsistentClientId	La revendication `clientId` de la clé Microsoft Store ID dans le corps de la requête et la revendication `appid` du jeton d’accès Microsoft Entra ID dans l’en-tête d’autorisation ne correspondent pas.

Codes d’erreur lors de l’utilisation de l’authentification X-token

Code	Erreur	Code d’erreur interne	Description
401	Unauthorized	Expired Token	Le X-token est expiré, et un nouveau est nécessaire pour effectuer l’appel.
403	Unauthorized	Invalid Token	Le jeton utilisé n’est pas autorisé à s’authentifier auprès de ce point de terminaison. Le jeton pourrait correspondre au mauvais bac à sable ou à la mauvaise partie de confiance (Relying Party).
429	Throttled	Too frequent calls	Le service a été appelé trop de fois pour l’utilisateur par rapport aux limites d’appels spécifiées. Pour savoir quand votre service pourra effectuer un autre appel au service pour cet utilisateur, consultez la réponse.

Requête

Syntaxe de la requête

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

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
`beneficiary`	`UserIdentity`	L’utilisateur pour lequel cet article est consommé. Pour plus d’informations, consultez Authentification avec Microsoft Entra ID et des User Store IDs. Non requis pour l’authentification X-token.	Uniquement pour l’authentification par User Store ID
`trackingId`	`guid`	`trackingId` unique fourni par le développeur pour les vérifications de redondance. Le GUID doit être unique pour chaque requête. Pour plus d’informations, consultez Utilisation de trackingId pour valider l’exécution.	Oui
`productId`	`string`	Le `productId` du consommable visé par la requête. Peut être obtenu à partir de Partner Center ou en interrogeant les produits et les droits d’utilisation d’un utilisateur à partir d’un service.	Oui
`removeQuantity`	`int`	La quantité à consommer à partir du solde actuel de l’utilisateur.	S’applique uniquement aux consommables gérés par le Store.
`includeOrderIds`	`bool`	Inclut les OrderIds et LineItemIds des commandes utilisées pour exécuter la requête de consommation. Ces valeurs peuvent ensuite être utilisées avec les résultats du service d’événements Clawback pour identifier les transactions de consommation remboursées dans votre service de jeu.	Non
`sbx`	`string`	Valeur facultative pour l’authentification avec des UserStoreIds qui spécifie le bac à sable auquel les résultats doivent être limités. Sans cette valeur, le bac à sable RETAIL est utilisé par défaut. L’authentification X-Token n’a pas besoin de cette valeur, car le bac à sable est spécifié dans le X-Token. Remarque : Pour les consommables gérés par le développeur, l’authentification par User Store ID avec le paramètre `sbx` ciblant un bac à sable de développement n’est pas prise en charge. Utilisez l’authentification par jeton XSTS pour tester les consommables gérés par le développeur dans un bac à sable.	Non

Exemples de requêtes de consommation

Les exemples suivants utilisent un User Store ID pour l’authentification et nécessitent l’objet beneficiary dans le corps JSON de la requête.

Requête de consommation gérée par le Store

POST https://collections.mp.microsoft.com/v8.0/collections/consume HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1...
Host: collections.mp.microsoft.com
Content-Type: application/json

{
    "beneficiary" : {
        "localTicketReference": "testReference",
        "identityValue": "eyJ0eXAiOiJ...",
        "identityType": "b2b"
    },
    "productId": "9N0297GK108W",
    "trackingId": "1b3afaa8-8644-40e9-9073-266a3bb8804f",
    "removeQuantity": 1,
    "sandbox": "XDKS.1",
    "includeOrderIds": true
}

Requête de consommation gérée par le développeur

L’exemple suivant utilise l’authentification par User Store ID. Toutefois, cette méthode d’authentification ne fonctionne pas pour les consommables gérés par le développeur dans les bacs à sable de développement. Si vous effectuez des tests dans un environnement de bac à sable, utilisez plutôt l’authentification par jeton XSTS. Pour plus de détails, consultez Authentification au moyen de jetons XSTS d’authentification déléguée.

POST https://collections.mp.microsoft.com/v8.0/collections/consume HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1...
Content-Type: application/json
Host: collections.md.mp.microsoft.com

{
    "beneficiary" : {
        "localTicketReference" : "testReference",
        "identityValue": "eyJ0eXAiOiJ...",
        "identityType": "b2b"
    },
    "productId" : "9NBLGGH5WVP6",
    "trackingId" : "08a14c7c-1892-49fc-9135-190ca4f10490",
    "sbx" : "XDKS.1",
    "includeOrderIds": true
}

Réponse

Corps de la réponse

Paramètre	Type	Description	Obligatoire
`itemId`	string	ID qui distingue l’article de la collection des autres articles que l’utilisateur possède. Cet ID est unique par produit.	Oui
`productId`	`string`	Également appelé Store ID du produit dans le catalogue du Microsoft Store. Un exemple de Store ID de produit est 9NBLGGH42CFD.	Oui
`trackingId`	`GUID`	`trackingId` unique fourni par l’appelant pour la requête de consommation.	Oui
`newQuantity`	`int`	Quantité restante du solde de l’utilisateur pour ce produit consommable. La valeur est 0 pour les consommables gérés par le développeur.	Oui
`orderTransactions`	`List<ConsumeOrderTransaction>`	Tableau d’objets ConsumeOrderTransaction indiquant les commandes utilisées pour exécuter la requête. Retourné uniquement si le paramètre `includeOrderIds` est défini sur true dans la requête. Pour plus d’informations, consultez le tableau suivant.	Non

L’objet ConsumeOrderTransaction contient les paramètres suivants.

Paramètre	Type	Description	Obligatoire
`orderId`	`GUID`	ID du bon de commande de l’utilisateur utilisé pour exécuter la totalité ou une partie de la requête de consommation.	Oui
`orderLineItemId`	`GUID`	ID de l’article de ligne dans lequel se trouvait le consommable dans le bon de commande de l’utilisateur. Cet ID est plus spécifique à un achat de consommable que l’OrderId, car il peut y avoir plusieurs LineItemIds par OrderID.	Oui
`quantityConsumed`	`int`	Quantité de la requête exécutée par cet OrderId / LineItemId particulier	Oui

Exemple de réponse de consommation

HTTP/1.1 200 OK
Date: Sat, 04 Sep 2021 01:59:13 GMT
Content-Type: application/json; charset=utf-8
Server: Kestrel
Content-Length: 140
MS-CorrelationId: c7ed3826-c332-4394-af7e-32800e492695
MS-RequestId: 0702fbcf-01ec-4591-995e-13b92149df4d
MS-CV: rJGMXgDq8E2A1EmX.0
X-Content-Type-Options: nosniff
MS-ServerId: 6

{
    "newQuantity": 0,
    "itemId": "c95fef434d1241d6bdb09090b130b6f4",
    "trackingId": "1b3afaa8-8644-40e9-9073-266a3bb8804f",
    "productId": "9N0297GK108W",
    "orderTransactions": [
        {
            "orderId": "8060a406-85c8-4d01-a105-ff11725499c9",
            "orderLineItemId": "cb054aa0-7392-4cc6-af06-53b285e39259",
            "quantityConsumed": 1
        }
    ]
}

Articles connexes

Gérer les produits à partir de vos services Authentification de votre service avec les API du Microsoft Store Utilisation de publisherQuery (Collections v9) pour interroger les produits et les droits d’utilisation d’un utilisateur Gestion des produits consommables à partir de votre service Gestion des remboursements et des rétrofacturations à partir de votre service

Introduction

Onboarding & Access

Setup & Install

Build Your First Title

Utilisation de `trackingId` pour valider l’exécution

Prérequis

Codes d’erreur de l’authentification par User Store ID

Codes d’erreur lors de l’utilisation de l’authentification X-token

Requête

Syntaxe de la requête

En-tête de la requête

Corps de la requête

Exemples de requêtes de consommation

Requête de consommation gérée par le Store

Requête de consommation gérée par le développeur

Réponse

Corps de la réponse

Exemple de réponse de consommation

Articles connexes

​Utilisation de trackingId pour valider l’exécution

​Prérequis

​Codes d’erreur de l’authentification par User Store ID

​Codes d’erreur lors de l’utilisation de l’authentification X-token

​Requête

​Syntaxe de la requête

​En-tête de la requête

​Corps de la requête

​Exemples de requêtes de consommation

​Requête de consommation gérée par le Store

​Requête de consommation gérée par le développeur

​Réponse

​Corps de la réponse

​Exemple de réponse de consommation

​Articles connexes

Utilisation de `trackingId` pour valider l’exécution

Prérequis

Codes d’erreur de l’authentification par User Store ID

Codes d’erreur lors de l’utilisation de l’authentification X-token

Requête

Syntaxe de la requête

En-tête de la requête

Corps de la requête

Exemples de requêtes de consommation

Requête de consommation gérée par le Store

Requête de consommation gérée par le développeur

Réponse

Corps de la réponse

Exemple de réponse de consommation

Articles connexes