Demander des produits

Utilisez cette méthode dans l’API de collecte du Microsoft Store pour obtenir tous les produits qu’un client possède pour les applications associées à votre ID client Azure AD. Vous pouvez limiter votre requête à un produit spécifique ou utiliser d’autres filtres.

Cette méthode est conçue pour être appelée par votre service en réponse à un message de votre application. Votre service ne doit pas interroger régulièrement tous les utilisateurs en fonction d’une planification.

La bibliothèque Microsoft.StoreServices fournit les fonctionnalités de cette méthode via l’API StoreServicesClient.CollectionsQueryAsync.

Prérequis

Pour utiliser cette méthode, vous devez disposer des éléments suivants :

  • Jeton d’accès Azure AD qui a la valeur https://onestore.microsoft.comURI d’audience .
  • Une clé d’ID du Microsoft Store qui représente l’identité de l’utilisateur dont vous souhaitez obtenir les produits.

Pour plus d’informations, consultez Gérer les droits de produit à partir d’un service.

Requête

Syntaxe de la requête

Méthode URI de demande
POST https://collections.mp.microsoft.com/v6.0/collections/query

En-tête de requête

En-tête Type Description
Autorisation string Obligatoire. Jeton d’accès Azure AD sous la formeJeton> du porteur<.
Host string Doit être défini sur la valeur collections.mp.microsoft.com.
Content-Length nombre Longueur du corps de la demande.
Content-Type string Spécifie le type de requête et de réponse. Actuellement, la seule valeur prise en charge est application/json.

Corps de la demande

Paramètre Type Description Obligatoire
beneficiaries liste<UserIdentity> Liste d’objets UserIdentity qui représentent les utilisateurs interrogés pour les produits. Pour plus d’informations, consultez le tableau ci-dessous. Oui
continuationToken string S’il existe plusieurs ensembles de produits, le corps de la réponse retourne un jeton de continuation lorsque la limite de la page est atteinte. Indiquez ce jeton de continuation ici dans les appels ultérieurs pour récupérer les produits restants. Non
maxPageSize nombre Nombre maximal de produits à retourner dans une réponse. La valeur par défaut et maximale est de 100. Non
modifiedAfter DATETIME Si ce paramètre est spécifié, le service retourne uniquement les produits qui ont été modifiés après cette date. Non
parentProductId string Si ce paramètre est spécifié, le service retourne uniquement les extensions correspondant à l’application spécifiée. Non
productSkuIds list<ProductSkuId> S’il est spécifié, le service retourne uniquement les produits applicables aux paires produit/référence SKU fournies. Pour plus d’informations, consultez le tableau ci-dessous. Non
productTypes chaîne de liste<> Spécifie les types de produits à retourner dans les résultats de la requête. Les types de produits pris en charge sont Application, Durable, Jeu et UnmanagedConsumable. Oui
validityType string Si ce paramètre est défini sur All, tous les produits d’un utilisateur sont retournés, y compris les articles arrivés à expiration. S’il est défini sur Valid, seuls les produits qui sont valides à ce stade sont retournés (autrement dit, ils ont un état actif, une date de début < maintenant et une date de fin > maintenant). Non

L’objet UserIdentity contient les paramètres ci-dessous.

Paramètre Type Description Obligatoire
identityType string Spécifiez la valeur chaîne b2b. Oui
identityValue string Clé d’ID du Microsoft Store qui représente l’identité de l’utilisateur pour lequel vous souhaitez interroger des produits. Oui
localTicketReference string Identificateur demandé pour les produits retournés. Les articles retournés dans le corps de la réponse ont un paramètre localTicketReference correspondant. Nous vous recommandons d’utiliser la même valeur que la revendication userId dans la clé d’ID du Microsoft Store. Oui

L’objet ProductSkuId contient les paramètres ci-dessous.

Paramètre Type Description Obligatoire
productId string ID store d’unproduit dans le catalogue microsoft Store. Un exemple d’ID de magasin pour un produit est 9NBLGGH42CFD. Oui
skuId string ID du Store pour la référence SKU d’un produit dans le catalogue du Microsoft Store. Un exemple d’ID de magasin pour une référence SKU est 0010. Oui

Exemple de requête

POST https://collections.mp.microsoft.com/v6.0/collections/query HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Q…….
Host: collections.mp.microsoft.com
Content-Length: 2531
Content-Type: application/json

{
  "maxPageSize": 100,
  "beneficiaries": [
    {
      "localTicketReference": "1055521810674918",
      "identityValue": "eyJ0eXAiOiJ……",
      "identityType": "b2b"
    }
  ],
  "modifiedAfter": "\/Date(-62135568000000)\/",
  "productSkuIds": [
    {
      "productId": "9NBLGGH5WVP6",
      "skuId": "0010"
    }
  ],
  "productTypes": [
    "UnmanagedConsumable"
  ],
  "validityType": "All"
}

response

Response body

Paramètre Type Description Obligatoire
continuationToken string S’il existe plusieurs ensembles de produits, ce jeton est retourné lorsque la limite de la page est atteinte. Vous pouvez spécifier ce jeton de continuation dans les appels ultérieurs pour récupérer les produits restants. Non
items CollectionItemContractV6 Tableau de produits de l’utilisateur spécifié. Pour plus d’informations, consultez le tableau ci-dessous. Non

L’objet CollectionItemContractV6 contient les paramètres ci-dessous.

Paramètre Type Description Obligatoire
acquiredDate DATETIME Date à laquelle l’utilisateur a acquis l’article. Oui
campaignId string ID campagne fourni au moment de l’achat de cet article. Non
devOfferId string ID d’offre d’un achat dans l’application. Non
endDate DATETIME Date de fin de l’article. Oui
fulfillmentData chaîne de liste<> N/A Non
inAppOfferToken string Chaîne d’ID de produit spécifiée par le développeur qui est affectée à l’élément dans l’Espace partenaires. Un exemple d’ID de produit est product123. Non
itemId string ID qui identifie cet élément de collection à partir des autres articles dont l’utilisateur est propriétaire. Cet ID est unique par produit. Oui
localTicketReference string ID du localTicketReference précédemment fourni dans le corps de la demande. Oui
modifiedDate DATETIME Date de la dernière modification de cet article. Oui
orderId string Le cas échéant, référence de la commande par le biais de laquelle cet article a été obtenu. Non
orderLineItemId string Le cas échéant, ligne d’article de la commande spécifique dans laquelle cet article a été obtenu. Non
ownershipType string Chaîne OwnedByBeneficiary. Oui
productId string ID store du produit dans le catalogue du Microsoft Store. Un exemple d’ID de magasin pour un produit est 9NBLGGH42CFD. Oui
productType string L’un des types de produit suivants : Application, Durable et UnmanagedConsumable. Oui
purchasedCountry string N/A Non
purchaser IdentityContractV6 Le cas échéant, représente l’identité de l’acheteur de l’article. Voir les détails de cet objet ci-dessous. Non
quantité nombre Quantité de l’article. Actuellement, il s’agit toujours de la valeur 1. Non
skuId string ID du Store pour la référence SKU du produit dans le catalogue du Microsoft Store. Un exemple d’ID de magasin pour une référence SKU est 0010. Oui
skuType string Type de référence. Valeurs possibles : Trial, Full et Rental. Oui
startDate DATETIME Date de début de validité de l’article. Oui
status string État de l’élément. Valeurs possibles : Active, Expired, Revoked et Banned. Oui
tags chaîne de liste<> N/A Oui
transactionId guid ID de la transaction résultant de l’achat de cet article. Peut être utilisé pour signaler le traitement de la commande d’un article. Oui

L’objet IdentityContractV6 contient les paramètres ci-dessous.

Paramètre Type Description Obligatoire
identityType string Contient la valeur pub. Oui
identityValue string Valeur de chaîne de publisherUserId de la clé d’ID du Microsoft Store spécifiée. Oui

Exemple de réponse

HTTP/1.1 200 OK
Content-Length: 7241
Content-Type: application/json
MS-CorrelationId: 699681ce-662c-4841-920a-f2269b2b4e6c
MS-RequestId: a9988cf9-652b-4791-beba-b0e732121a12
MS-CV: xu2HW6SrSkyfHyFh.0.1
MS-ServerId: 020022359
Date: Tue, 22 Sep 2015 20:28:18 GMT

{
  "items" : [
    {
      "acquiredDate" : "2015-09-22T19:22:51.2068724+00:00",
      "devOfferId" : "f9587c53-540a-498b-a281-8a349491ed47",
      "endDate" : "9999-12-31T23:59:59.9999999+00:00",
      "fulfillmentData" : [],
      "inAppOfferToken" : "consumable2",
      "itemId" : "4b8fbb13127a41f299270ea668681c1d",
      "localTicketReference" : "1055521810674918",
      "modifiedDate" : "2015-09-22T19:22:51.2513155+00:00",
      "orderId" : "4ba5960d-4ec6-4a81-ac20-aafce02ddf31",
      "ownershipType" : "OwnedByBeneficiary",
      "productId" : "9NBLGGH5WVP6",
      "productType" : "UnmanagedConsumable",
      "purchaser" : {
        "identityType" : "pub",
        "identityValue" : "user123"
      },
      "skuId" : "0010",
      "skuType" : "Full",
      "startDate" : "2015-09-22T19:22:51.2068724+00:00",
      "status" : "Active",
      "tags" : [],
      "transactionId" : "4ba5960d-4ec6-4a81-ac20-aafce02ddf31"
    }
  ]
}