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

Utilisez l’API Consume pour gérer ces types de consommables 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 des consommables gérés par le Store à plusieurs reprises sans que votre service ait à les signaler comme consommés ou traité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 traité 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 traité 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’achèvement du traitement

trackingId fournit une validation du traitement compatible avec les nouvelles tentatives. 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 adressée à l’API doit avoir un trackingId unique. Si la requête d’origine n’a pas abouti, ou si la réponse n’a pas été reçue, le service effectue la transaction demandée lors de la nouvelle tentative de la requête. Si le traitement a été effectué 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 de second traitement ni de seconde déduction du solde de l’utilisateur. L’API répond plutôt par un succès, comme si l’élément 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 de confirmation indiquant que la requête a été traitée. Pour obtenir un exemple, consultez l’exemple de service de jeu. Lorsque votre requête contient le paramètre includeOrderIds, les comportements suivants sont attendus en fonction du type de produit consommable :

Type de consommable	Comportement de la première requête de consommation	Comportement d’une nouvelle tentative de requête de consommation
Géré par le Store	Les OrderIds utilisés pour traiter la requête sont renvoyés	Les mêmes OrderIds utilisés pour traiter la requête sont renvoyés
Géré par le développeur	Les OrderIds utilisés pour traiter la requête sont renvoyés	Aucun OrderID n’est renvoyé, 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 de 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’authentification déléguée.

Limitation de sandbox 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 sandbox de développement (non RETAIL), l’authentification à l’aide de l’ID Store utilisateur ou de Microsoft Entra ID n’est pas prise en charge. Dans les environnements sandbox, 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 sandbox RETAIL.

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

Codes d’erreur d’authentification par ID Store utilisateur

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 a 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é d’ID Microsoft Store 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 a expiré et un nouveau jeton 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 concerne peut-être le mauvais sandbox ou la mauvaise partie de confiance.
429	Throttled	Too frequent calls	Le service a été appelé trop de fois pour l’utilisateur dans les limites d’appel spécifiées. Pour savoir quand votre service peut effectuer un autre appel au service pour cet utilisateur, consultez la réponse.

Requête

Syntaxe de la requête

Méthode	URI de 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. 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 en cas d’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 à des fins de journalisation et d’investigation.
`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
`beneficiary`	`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
`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’achèvement du traitement.	Oui
`productId`	`string`	`productId` du consommable concerné par la requête. Peut être obtenu à partir de Partner Center ou en interrogeant les produits et les droits d’un utilisateur à partir d’un service.	Oui
`removeQuantity`	`int`	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 traiter 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 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. Remarque : pour les consommables gérés par le développeur, l’authentification par ID Store utilisateur avec le paramètre `sbx` ciblant un sandbox de développement n’est pas prise en charge. Utilisez l’authentification par jeton XSTS pour tester en sandbox les consommables gérés par le développeur.	Non

Exemples de requêtes de consommation

Les exemples suivants utilisent un ID Store utilisateur 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 ID Store utilisateur. Toutefois, cette méthode d’authentification ne fonctionne pas pour les consommables gérés par le développeur dans les sandbox de développement. Si vous effectuez des tests dans un environnement sandbox, utilisez plutôt l’authentification par jeton XSTS. Pour plus de détails, consultez Authentification par 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’élément de collection des autres éléments que possède l’utilisateur. Cet ID est unique par produit.	Oui
`productId`	`string`	Également appelé ID Store du produit dans le catalogue du Microsoft Store. Exemple d’ID Store pour un produit : 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 traiter la requête. Renvoyé 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 traiter tout ou partie de la requête de consommation.	Oui
`orderLineItemId`	`GUID`	ID de la ligne de commande contenant le consommable dans le bon de commande passé par 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`	Partie de la requête traitée par cet OrderId / LineItemId spécifique	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 Microsoft Store Utilisation de publisherQuery (Collections v9) pour interroger les produits et les droits 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’achèvement du traitement

Prérequis

Codes d’erreur d’authentification par ID Store utilisateur

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’achèvement du traitement

​Prérequis

​Codes d’erreur d’authentification par ID Store utilisateur

​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’achèvement du traitement

Prérequis

Codes d’erreur d’authentification par ID Store utilisateur

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