Ottenere le sottoscrizioni per un utente

  • Articolo

Usare questo metodo nell'API di acquisto di Microsoft Store per ottenere i componenti aggiuntivi di sottoscrizione che un determinato utente ha diritto di usare.

Nota

Questo metodo può essere usato solo dagli account degli sviluppatori di cui è stato effettuato il provisioning da Microsoft per consentire loro di creare componenti aggiuntivi di sottoscrizione per le app UWP (Universal Windows Platform). I componenti aggiuntivi di sottoscrizione non sono attualmente disponibili per la maggior parte degli account degli sviluppatori.

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

Prerequisiti

Per usare questo metodo, è necessario:

  • Un token di accesso di Azure AD con il valore URI del gruppo di destinatari https://onestore.microsoft.com.
  • Una chiave ID di Microsoft Store che rappresenta l'identità dell'utente di cui si desidera ottenere le sottoscrizioni.

Per ulteriori informazioni, vedere Gestire i diritti dei prodotti di un servizio.

Richiedi

Sintassi della richiesta

metodo URI della richiesta
POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/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 sul valore purchase.mp.microsoft.com.
Content-Length Numero Lunghezza del corpo della richiesta.
Content-Type string Specifica il tipo di richiesta e risposta. Attualmente, l'unico valore supportato è application/json.

Corpo della richiesta

Parametro Tipo Descrizione Richiesto
b2bKey string La chiave ID di Microsoft Store che rappresenta l'identità dell'utente di cui si desidera ottenere le sottoscrizioni. Sì
continuationToken string Se l'utente ha diritti per più sottoscrizioni, il corpo della risposta restituisce un token di continuazione quando viene raggiunto il limite di pagina. Specificare questo token di continuazione nelle chiamate successive per recuperare i prodotti rimanenti. No
pageSize string Numero massimo di sottoscrizioni da restituire in una risposta. Il valore predefinito è 25. No

Esempio di richiesta

L'esempio seguente illustra come usare questo metodo per ottenere i componenti aggiuntivi di sottoscrizione che un determinato utente ha diritto di usare. Sostituire il valore b2bKey con la chiave ID di Microsoft Store che rappresenta l'identità dell'utente di cui si desidera recuperare le sottoscrizioni.

POST https://purchase.mp.microsoft.com/v8.0/b2b/recurrences/query HTTP/1.1
Authorization: Bearer <your access token>
Content-Type: application/json
Host: purchase.mp.microsoft.com

{
  "b2bKey":  "eyJ0eXAiOiJ..."
}

Response

Questo metodo restituisce un corpo della risposta JSON che contiene una raccolta di oggetti dati che descrivono i componenti aggiuntivi di sottoscrizione che l'utente ha diritto di usare. Nell'esempio seguente viene illustrato il corpo della risposta per un utente che ha diritto a una sottoscrizione.

{
  "items": [
    {
      "autoRenew":true,
      "beneficiary":"pub:gFVuEBiZHPXonkYvtdOi+tLE2h4g2Ss0ZId0RQOwzDg=",
      "expirationTime":"2017-06-11T03:07:49.2552941+00:00",
      "id":"mdr:0:bc0cb6960acd4515a0e1d638192d77b7:77d5ebee-0310-4d23-b204-83e8613baaac",
      "lastModified":"2017-01-08T21:07:51.1459644+00:00",
      "market":"US",
      "productId":"9NBLGGH52Q8X",
      "skuId":"0024",
      "startTime":"2017-01-10T21:07:49.2552941+00:00",
      "recurrenceState":"Active"
    }
  ]
}

Corpo della risposta

Il corpo della risposta contiene i dati seguenti:

Valore Tipo Descrizione
articoli array Matrice di oggetti che contengono dati su ogni componente aggiuntivo di sottoscrizione che l'utente specificato ha diritto di usare. Per ulteriori informazioni sui dati in ogni oggetto, vedere la tabella seguente.

Ogni oggetto nella matrice items contiene i valori seguenti.

Valore Tipo Descrizione
autoRenew Booleano Indica se la sottoscrizione è configurata per il rinnovo automatico alla fine del periodo di sottoscrizione corrente.
beneficiary string ID del beneficiario del diritto associato a questa sottoscrizione.
expirationTime string Data e ora di scadenza della sottoscrizione, in formato ISO 8601. Questo campo è disponibile solo quando la sottoscrizione è in determinati stati. L'ora di scadenza indica in genere quando scade lo stato corrente. Ad esempio, per una sottoscrizione attiva, la data di scadenza indica quando si verificherà il successivo rinnovo automatico.
expirationTimeWithGrace string Data e ora in cui la sottoscrizione scadrà, incluso il periodo di tolleranza, in formato ISO 8601. Questo valore indica quando l'utente perderà l'accesso alla sottoscrizione dopo che la sottoscrizione non è stata rinnovata automaticamente.
id string ID della sottoscrizione. Usare questo valore per indicare quale sottoscrizione si desidera modificare quando si chiama il metodo di modifica dello stato di fatturazione di una sottoscrizione per un utente.
isTrial Booleano Indica se la sottoscrizione è relativa a una versione di valutazione.
LastModified string Data e ora dell'ultima modifica della sottoscrizione, in formato ISO 8601.
market string Codice del Paese (in formato ISO 3166-1 alpha-2 a due lettere) in cui l'utente ha acquisito la sottoscrizione.
productId string ID dello Store per il prodotto che rappresenta il componente aggiuntivo di sottoscrizione nel catalogo di Microsoft Store. Un esempio di ID dello Store per un prodotto è 9NBLGGH42CFD.
skuId string ID dello Store per lo SKU che rappresenta il componente aggiuntivo di sottoscrizione nel catalogo di Microsoft Store. Un esempio di ID dello Store per uno SKU è 0010.
startTime string Data e ora di inizio della sottoscrizione, in formato ISO 8601.
recurrenceState string Uno dei valori seguenti:
  • None: indica una sottoscrizione perpetua.
  • Active: la sottoscrizione è attiva e l'utente ha diritto di usare i servizi.
  • Inactive: la sottoscrizione ha superato la data di scadenza e l'utente ne ha disattivato l'opzione di rinnovo automatico.
  • Annullata: la sottoscrizione è stata terminata intenzionalmente prima della data di scadenza, con o senza rimborso.
  • InDunning: la sottoscrizione è in stato di sollecito (ossia, è prossima alla scadenza e Microsoft sta tentando di acquisire i fondi per rinnovarla automaticamente).
  • Failed: il periodo di sollecito è terminato è non è stato possibile rinnovare la sottoscrizione dopo diversi tentativi.

Nota:

  • Inactive/Canceled/Failed sono stati di terminazione. Quando una sottoscrizione entra in uno di questi stati, l'utente deve riacquistarla per attivarla di nuovo. L'utente non ha diritto di usare i servizi in questi stati.
  • Quando una sottoscrizione è Canceled, il valore expirationTime verrà aggiornato con la data e l'ora dell'annullamento.
  • L'ID della sottoscrizione rimarrà invariato durante l'intera durata. Non cambierà se l'opzione di rinnovo automatico è attivata o disattivata. Se un utente acquista nuovamente una sottoscrizione dopo aver raggiunto uno stato di terminazione, verrà creato un nuovo ID sottoscrizione.
  • L'ID di una sottoscrizione deve essere usato per eseguire qualsiasi operazione su una singola sottoscrizione.
  • Quando un utente acquista nuovamente una sottoscrizione dopo averla annullata o interrotta, se si eseguono query sui risultati per l'utente, si otterranno due voci: una con l'ID sottoscrizione precedente in uno stato di terminazione e una con il nuovo ID sottoscrizione in uno stato attivo.
  • È sempre consigliabile controllare sia recurrenceState che expirationTime, poiché gli aggiornamenti di recurrenceState possono ritardare di alcuni minuti (o anche ore).
cancellationDate string Data e ora di annullamento della sottoscrizione dell'utente, in formato ISO 8601.