Eseguire query sui prodotti

  • Articolo

Usa questo metodo nell'API di raccolta di Microsoft Store per ottenere tutti i prodotti di proprietà di un cliente per le app associate al tuo ID client di Azure AD. Puoi limitare la tua query a un particolare prodotto o utilizzare altri filtri.

Questo metodo è progettato per essere chiamato dal tuo servizio in risposta a un messaggio dalla tua app. Il tuo servizio non dovrebbe eseguire regolarmente il polling per tutti gli utenti secondo una pianificazione.

La libreria Microsoft.StoreServices fornisce la funzionalità di questo metodo tramite l'API StoreServicesClient.CollectionsQueryAsync.

Prerequisiti

Per utilizzare questo metodo, avrai bisogno di:

  • Un token di accesso di Azure AD con il valore dell'URI del destinatario https://onestore.microsoft.com.
  • Una chiave ID di Microsoft Store che rappresenta l'identità dell'utente di cui desideri ottenere i prodotti.

Per maggiori informazioni, vedere Gestire i diritti del prodotto da un servizio.

Richiedi

Sintassi della richiesta

metodo URI della richiesta
POST https://collections.mp.microsoft.com/v6.0/collections/query

Intestazione della richiesta

Intestazione Type Descrizione
Autorizzazione stringa Obbligatorio. Token di accesso di Azure AD nel formato Token di<connessione>.
Host string Deve essere impostato il valore di collections.mp.microsoft.com.
Content-Length number Lunghezza del corpo della richiesta.
Content-Type string Specifica il tipo di richiesta e risposta. Attualmente, l'unico valore supportato è application/json.

Testo della richiesta

Parametro Tipo Descrizione Richiesto
beneficiari elenco<UserIdentity> Un elenco di oggetti UserIdentity che rappresentano gli utenti a cui vengono richiesti i prodotti. Per maggiori informazioni, vedere la tabella qui sotto. Sì
continuationToken string Se sono presenti più set di prodotti, il corpo della risposta restituisce un token di continuazione quando viene raggiunto il limite di pagine. Fornisci qui il token di continuazione nelle chiamate successive per recuperare i prodotti rimanenti. No
maxPageSize number Il numero massimo di prodotti da restituire in una risposta. Il valore predefinito e massimo è 100. No
modifiedAfter datetime Se specificato, il servizio restituisce solo i prodotti che hanno subito modifiche dopo tale data. No
parentProductId string Se specificato, il servizio restituisce solo i componenti aggiuntivi che corrispondono all'app specificata. No
productSkuIds elenco<ProductSkuId> Se specificato, il servizio restituisce solo i prodotti applicabili alle coppie prodotto/SKU fornite. Per maggiori informazioni, vedere la tabella qui sotto. No
productTypes elenco<string> Specifica quali tipi di prodotto restituire nei risultati della query. Tipi di prodotti supportati Applicazione,Durevolezza,Gioco e UnmanagedConsumable. Sì
validityType string Quando configuri su Tutti, verranno restituiti tutti i prodotti per un utente, inclusi gli articoli scaduti. Quando configuri su Valido, verranno restituiti solo i prodotti validi in quel momento (ovvero, hanno uno stato attivo, una data di inizio < ora, e la data di fine è >ora). No

L'oggetto UserIdentity contiene i seguenti parametri.

Parametro Tipo Descrizione Richiesto
identityType string Specifica il valore della stringa b2b. Sì
identityValue string La Microsoft Store ID key che rappresenta l'identità dell'utente per il quale desideri eseguire query sui prodotti.. Sì
localTicketReference string L'identificatore richiesto per i prodotti restituiti. Gli elementi restituiti nel corpo della risposta avranno una corrispondenza localTicketReference. Ti consigliamo di utilizzare lo stesso valore dell'attestazione userId nella chiave ID di Microsoft Store. Sì

L'oggetto ProductSkuId contiene i seguenti parametri.

Parametro Tipo Descrizione Richiesto
productId string LoStore ID per un prodotto nel catalogo del Microsoft Store. Un esempio di ID negozio per un prodotto è 9NBLGGH42CFD.. Sì
skuId string Lo Store ID per un prodottoSKU nel catalogo del Microsoft Store. Un esempio di ID negozio per uno SKU è 0010. Sì

Esempio di richiesta

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

Corpo della risposta

Parametro Tipo Descrizione Richiesto
continuationToken string Se sono presenti più set di prodotti, questo token viene restituito quando viene raggiunto il limite di pagine. È possibile specificare questo token di continuazione nelle chiamate successive per recuperare i prodotti rimanenti. No
articoli CollectionItemContractV6 Una serie di prodotti per l'utente specificato. Per maggiori informazioni, vedere la tabella qui sotto. No

L'oggetto CollectionItemContractV6 contiene i seguenti parametri.

Parametro Tipo Descrizione Richiesto
acquiredDate datetime La data in cui l'utente ha acquistato l'articolo. Sì
campaignId string L'ID campagna fornito al momento dell'acquisto per questo articolo. No
devOfferId string L'ID dell'offerta da un acquisto in-app. No
endDate datetime La data di fine dell'articolo. Sì
fulfillmentData elenco<string> N/D No
inAppOfferToken string La stringa dell'ID prodotto specificata dallo sviluppatore assegnata all'elemento nel Centro per i partner. Un ID prodotto di esempio è product123. No
itemId string Un ID che identifica questo elemento della raccolta da altri elementi di proprietà dell'utente. Questo ID è univoco per prodotto. Sì
localTicketReference string L'ID dell'elemento fornito in precedenza localTicketReference nel corpo della richiesta. Sì
modifiedDate datetime La data dell'ultima modifica dell'elemento. Sì
orderId string Se presente, l'ID dell'ordine da cui è stato ottenuto l'articolo. No
orderLineItemId string Se presente, la voce dell'ordine particolare per il quale è stata ottenuta questa voce. No
ownershipType string La stringa OwnedByBeneficiary. Sì
productId string LoStore ID per il prodotto nel catalogo del Microsoft Store. Un esempio di ID negozio per un prodotto è 9NBLGGH42CFD.. Sì
productType string Uno dei seguenti tipi di prodotto: Applicazione, Durevole, eUnmanagedConsumable. Sì
purchasedCountry string N/D No
acquirente IdentityContractV6 Se presente, rappresenta l'identità dell'acquirente dell'articolo. Vedi i dettagli per questo oggetto di seguito. No
quantity number La quantità dell'articolo. Attualmente, questo sarà sempre 1. No
skuId string Lo Store ID per il prodottoSKU nel catalogo del Microsoft Store. Un esempio di ID negozio per uno SKU è 0010. Sì
skuType string Tipo di SKU. I valori possibili includono ProvaCompleto e Noleggio. Sì
startDate datetime La data in cui l'articolo inizia ad essere valido. Sì
stato string Lo stato dell'articolo. I valori possibili includono Attivo, Scaduto, Revocato, e Bannato. Sì
tag elenco<string> N/D Sì
transactionId guid L'ID della transazione risultante dall'acquisto di questo articolo. Può essere utilizzato per segnalare un articolo come evaso. Sì

L'oggetto IdentityContractV6 contiene i seguenti parametri.

Parametro Tipo Descrizione Richiesto
identityType string Contiene il valore pub. Sì
identityValue string Il valore della stringa publisherUserId dalla chiave ID di Microsoft Store specificata. Sì

Risposta di esempio

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"
    }
  ]
}