Eseguire query sui prodotti

Articolo
04/01/2024

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

Condividi tramite

Eseguire query sui prodotti

Prerequisiti

Richiedi

Sintassi della richiesta

Intestazione della richiesta

Testo della richiesta

Esempio di richiesta

Response

Corpo della risposta

Risposta di esempio

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Eseguire query sui prodotti

Prerequisiti

Richiedi

Sintassi della richiesta

Intestazione della richiesta

Testo della richiesta

Esempio di richiesta

Response

Corpo della risposta

Risposta di esempio

Argomenti correlati

Commenti e suggerimenti

Risorse aggiuntive