Segnala i prodotti di consumo come evasi

  • Articolo

Utilizza questo metodo nell'API di raccolta di Microsoft Store per segnalare un prodotto di consumo come evaso per un determinato cliente. Prima che un utente possa riacquistare un prodotto di consumo, la tua app o il tuo servizio deve segnalare il prodotto di consumo come evaso per quell'utente.

Esistono due modi per utilizzare questo metodo per segnalare un prodotto di consumo come evaso:

  • Fornire l'ID articolo del materiale di consumo (come restituito nel parametro itemId di una query per i prodotti), e un ID di tracciamento univoco da te fornito. Se viene utilizzato lo stesso ID di tracciamento per più tentativi, verrà restituito lo stesso risultato anche se l'articolo è già stato consumato. Se non sei sicuro che una richiesta di consumo abbia avuto esito positivo, il tuo servizio dovrebbe inviare nuovamente le richieste di consumo con lo stesso ID di monitoraggio. L'ID di tracciamento sarà sempre legato a quella richiesta di consumo e potrà essere reinviato a tempo indeterminato.
  • Fornire l'ID prodotto (come restituito nel parametro productId di una query per i prodotti) e un ID transazione ottenuto da una delle fonti elencate nella descrizione del parametrotransactionIdnella sezione corpo della richiesta sottostante.

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

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 per il quale vuoi segnalare un prodotto di consumo come evaso.

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/consume

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
beneficiario UserIdentity L'utente a cui è destinato il consumo di questo articolo. Per altre informazioni, vedere la tabella seguente. Sì
itemId string Il valore itemId restituito da una query per prodottu. Utilizza questo parametro con trackingId No
trackingId guid Un ID di monitoraggio univoco fornito dallo sviluppatore. Utilizza questo parametro con itemId No
productId string Il valore productId restituito da una query per prodotti. Utilizza questo parametro con transactionId No
transactionId guid Un valore dell'ID transazione ottenuto da una delle seguenti origini. Utilizza questo parametro con productId. 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 si vuole segnalare un prodotto di consumo come evaso. Sì
localTicketReference string L'identificatore richiesto per la risposta restituita. È consigliabile usare lo stesso valore dell'attestazione userIdnella chiave ID di Microsoft Store. Sì

Esempi di richiesta

Il seguente esempio utilizza itemId e trackingId.

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

{
    "beneficiary": {
        "localTicketReference": "testreference",
        "identityValue": "eyJ0eXAiOi…..",
        "identityType": "b2b"
    },
    "itemId": "44c26106-4979-457b-af34-609ae97a084f",
    "trackingId": "44db79ca-e31d-49e9-8896-fa5c7f892b40"
}

Il seguente esempio utilizza productId e transactionId.

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

{
    "beneficiary" : {
        "localTicketReference" : "testReference",
        "identityValue" : "eyJ0eXAiOiJ…..",
        "identitytype" : "b2b"
    },
    "productId" : "9NBLGGH5WVP6",
    "transactionId" : "08a14c7c-1892-49fc-9135-190ca4f10490"
}

Response

Nessun contenuto verrà restituito se il consumo è stato eseguito correttamente.

Risposta di esempio

HTTP/1.1 204 No Content
Content-Length: 0
MS-CorrelationId: 386f733d-bc66-4bf9-9b6f-a1ad417f97f0
MS-RequestId: e488cd0a-9fb6-4c2c-bb77-e5100d3c15b1
MS-CV: 5.1
MS-ServerId: 030011326
Date: Tue, 22 Sep 2015 20:40:55 GMT

Codici di errore

Codice Error Codice di errore interno Descrizione
401 Non autorizzata AuthenticationTokenInvalid Il token di accesso di Azure AD non è valido. In alcuni casi i dettagli del ServiceError conterranno più informazioni, ad esempio quando il token è scaduto o manca l'attestazione appid.
401 Non autorizzata PartnerAadTicketRequired Un token di accesso di Azure AD non è stato passato al servizio nell'intestazione dell'autorizzazione.
401 Non autorizzata InconsistentClientId L'attestazioneclientId nella Microsoft Store ID key e nel corpo della richiesta e l'attestazione appid nel token di accesso nell'intestazione dell'autorizzazione di Azure AD non corrispondono.