Recuperare le acquisizioni dei componenti aggiuntivi di sottoscrizione
Usare questo metodo nell'API di analisi di Microsoft Store per ottenere dati aggregati sulle acquisizioni per le sottoscrizioni di componenti aggiuntivi dell'app durante un determinato intervallo di date e altri filtri opzionali.
Prerequisiti
Per usare questo metodo, è necessario prima eseguire le operazioni seguenti:
- Se non lo si è ancora fatto, completare i prerequisiti per l'API di analisi di Microsoft Store.
- Ottenere un token di accesso di Azure AD da usare nell'intestazione della richiesta per questo metodo. Dopo aver ottenuto un token di accesso, questo sarà disponibile per 60 minuti prima della scadenza. Dopo la scadenza del token, è possibile ottenerne uno nuovo.
Richiedi
Sintassi della richiesta
| metodo | URI della richiesta |
|---|---|
| GET | https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions |
Intestazione della richiesta
| Intestazione | Type | Descrizione |
|---|---|---|
| Autorizzazione | stringa | Obbligatorio. Token di accesso di Azure AD nel formato Token di<connessione>. |
Parametri della richiesta
| Parametro | Tipo | Descrizione | Richiesto |
|---|---|---|---|
| applicationId | string | ID dello Store dell'app per cui si desidera recuperare i dati sulle acquisizioni del componente aggiuntivo di sottoscrizione. | Sì |
| subscriptionProductId | string | ID dello Store del componente aggiuntivo di sottoscrizione per cui si desidera recuperare i dati sulle acquisizioni. Se non si specifica questo valore, questo metodo restituisce i dati sulle acquisizioni per tutti i componenti aggiuntivi di sottoscrizione per l'app specificata. | No |
| startDate | data | Data di inizio nell'intervallo di date dei dati sulle acquisizioni del componente aggiuntivo di sottoscrizione da recuperare. L'impostazione predefinita è la data corrente. | No |
| endDate | data | Data di fine nell'intervallo di date dei dati sulle acquisizioni del componente aggiuntivo di sottoscrizione da recuperare. L'impostazione predefinita è la data corrente. | No |
| migliori | int | Numero di righe di dati da restituire nella richiesta. Il valore massimo e il valore predefinito, se non specificati, sono pari a 100. Se nella query sono presenti più righe, il corpo della risposta includerà un collegamento che consente di richiedere la pagina successiva dei dati. | No |
| skip | int | Numero di righe da ignorare nella query. Usare questo parametro per scorrere i set di dati di grandi dimensioni. Ad esempio, top=10000 e skip=0 recupera le prime 10.000 righe di dati, top=10000 e skip=10000 recupera le 10.000 righe di dati successive e così via. | No |
| filter | string | Una o più istruzioni che filtrano il corpo della risposta. Ogni istruzione può usare gli operatori eq o ne e le istruzioni possono essere combinate mediante gli operatori and o or. È possibile specificare le stringhe seguenti nelle istruzioni di filtro (che corrispondono ai valori nel corpo della risposta):
Di seguito è riportato un esempio di parametro filter: filter=date eq '2017-07-08'. |
No |
| aggregationLevel | string | Specifica l'intervallo di tempo per il quale recuperare i dati aggregati. Può essere una delle stringhe seguenti: giorno, settimana o mese. Se non è specificato, il valore predefinito è giorno. | No |
| orderby | string | Istruzione che ordina i valori dei dati dei risultati per ogni acquisizione del componente aggiuntivo di sottoscrizione. La sintassi è orderby=field [order],field [order],.... Il parametro field può essere una delle stringhe seguenti:
Il parametro order è facoltativo e può essere asc o desc per specificare l'ordine crescente o decrescente di ogni campo. Il valore predefinito è asc. Di seguito è riportato un esempio di stringa orderby: orderby=date,market |
No |
| groupby | string | Istruzione che applica l'aggregazione dei dati solo ai campi specificati. È possibile specificare i campi seguenti:
Il parametro groupby può essere usato con il parametro aggregationLevel. Ad esempio: groupby=market&aggregationLevel=week |
No |
Esempio di richiesta
Gli esempi seguenti illustrano come ottenere i dati sulle acquisizioni di componenti aggiuntivi di sottoscrizione. Sostituire il valore applicationId con l'ID dello Store appropriato per l'app.
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions?applicationId=9NBLGGGZ5QDR&startDate=2017-07-07&endDate=2017-07-08 HTTP/1.1
Authorization: Bearer <your access token>
Response
Corpo della risposta
| Valore | Tipo | Descrizione |
|---|---|---|
| valore | matrice | Matrice di oggetti che contengono dati aggregati sulle acquisizioni del componente aggiuntivo di sottoscrizione. Per maggiori informazioni sui dati in ogni oggetto, vedere la sezione Valori acquisizioni sottoscrizione seguente. |
| @nextLink | string | Se vi sono ulteriori pagine di dati, la stringa conterrà un URI che è possibile usare per richiedere la pagina di dati successiva. Ad esempio, questo valore viene restituito se il parametro top della richiesta è impostato su 10000 ma vi sono più di 10.000 righe di dati sulle acquisizioni del componente aggiuntivo di sottoscrizione per la query. |
| TotalCount | int | Numero totale di righe nei risultati di dati per la query. |
Valori acquisizioni di sottoscrizione
Gli elementi nella matrice Value contengono i valori seguenti.
| Valore | Tipo | Descrizione |
|---|---|---|
| data | string | Prima data dell'intervallo di date per i dati acquisizione. Se la richiesta ha specificato un singolo giorno, questo valore corrisponde alla data. Se la richiesta ha specificato una settimana, un mese o un altro intervallo di date, questo valore corrisponde alla prima data nell'intervallo di date. |
| subscriptionProductId | string | ID dello Store del componente aggiuntivo di sottoscrizione per cui si stanno recuperando i dati sulle acquisizioni. |
| subscriptionProductName | string | Nome visualizzato del componente aggiuntivo di sottoscrizione. |
| applicationId | string | ID dello Store dell'app per cui si stanno recuperando i dati sulle acquisizioni del componente aggiuntivo di sottoscrizione. |
| applicationName | string | Nome visualizzato dell'app. |
| skuId | string | ID dello SKU del componente aggiuntivo di sottoscrizione per cui si stanno recuperando i dati sulle acquisizioni. |
| deviceType | string | Una delle stringhe seguenti che specifica il tipo di dispositivo che ha completato l'acquisizione:
|
| market | string | Codice Paese ISO 3166 del mercato in cui si è verificata l'acquisizione. |
| currencyCode | string | Codice valuta in formato ISO 4217 per le vendite al lordo delle imposte. |
| grossSalesBeforeTax | integer | Vendite lorde nella valuta locale specificata dal valore currencyCode. |
| totalActiveCount | integer | Numero di sottoscrizioni attive totali durante il periodo di tempo specificato. Equivale alla somma dei valori goodStandingActiveCount, pendingGraceActiveCount, graceActiveCount e lockedActiveCount. |
| totalChurnCount | integer | Numero totale di sottoscrizioni che sono state disattivate durante il periodo di tempo specificato. Equivale alla somma dei valori billingChurnCount, nonRenewalChurnCount, refundChurnCount, chargebackChurnCount, earlyChurnCount e otherChurnCount. |
| newCount | integer | Numero di nuove acquisizioni di sottoscrizioni durante il periodo di tempo specificato, incluse le versioni di valutazione. |
| renewCount | integer | Numero di rinnovi della sottoscrizione durante il periodo di tempo specificato, inclusi i rinnovi avviati dall'utente e i rinnovi automatici. |
| goodStandingActiveCount | integer | Numero di sottoscrizioni attive durante il periodo di tempo specificato la cui data di scadenza è >= al valore endDate per la query. |
| pendingGraceActiveCount | integer | Numero di sottoscrizioni attive durante il periodo di tempo specificato, ma che hanno riscontrato un errore di fatturazione e la cui data di scadenza della sottoscrizione è >= al valore endDate per la query. |
| graceActiveCount | integer | Numero di sottoscrizioni attive durante il periodo di tempo specificato, ma che hanno riscontrato un errore di fatturazione e dove:
|
| lockedActiveCount | integer | Numero di sottoscrizione che erano in stato di sollecito (ossia, la sottoscrizione è prossima alla scadenza e Microsoft sta tentando di acquisire i fondi per rinnovarla automaticamente) durante il periodo di tempo specificato e dove:
|
| billingChurnCount | integer | Numero di sottoscrizioni che sono state disattivate durante il periodo di tempo specificato a causa di un errore di elaborazione di un addebito di fatturazione e che erano in precedenza in stato di sollecito. |
| nonRenewalChurnCount | integer | Numero di sottoscrizioni che sono state disattivate durante il periodo di tempo specificato perché non sono state rinnovate. |
| refundChurnCount | integer | Numero di sottoscrizioni che sono state disattivate durante il periodo di tempo specificato perché sono state rimborsate. |
| chargebackChurnCount | integer | Numero di sottoscrizioni che sono state disattivate durante il periodo di tempo specificato a causa di un chargeback. |
| earlyChurnCount | integer | Numero di sottoscrizioni che sono state disattivate durante il periodo di tempo specificato mentre erano in stato regolare. |
| otherChurnCount | integer | Numero di sottoscrizioni che sono state disattivate durante il periodo di tempo specificato per altri motivi. |
Esempio di richiesta e risposta
I frammenti di codice seguenti illustrano alcune richieste di esempio e il corpo della risposta JSON per tali richieste.
Richiesta di esempio
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions?applicationId=9NBLGGGZ5QDR
HTTP/1.1
Authorization: Bearer <your access token>
Risposta di esempio
{
"Value": [
{
"date": "2022-04-18",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Windows and Doors",
"grossSalesBeforeTax": 3460656.260391250,
"totalActiveCount": 20211321,
"totalChurnCount": 5605,
"newCount": 3810366,
"renewCount": 12102044,
"goodStandingActiveCount": 17893664,
"pendingGraceActiveCount": 2255792,
"graceActiveCount": 61833,
"lockedActiveCount": 32,
"billingChurnCount": 4,
"nonRenewalChurnCount": 0,
"refundChurnCount": 0,
"chargebackChurnCount": 0,
"earlyChurnCount": 2717,
"otherChurnCount": 2884
},
{
"date": "2022-04-18",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Unknown",
"grossSalesBeforeTax": 2342.580615228,
"totalActiveCount": 50550,
"totalChurnCount": 7,
"newCount": 8312,
"renewCount": 31446,
"goodStandingActiveCount": 44047,
"pendingGraceActiveCount": 6503,
"graceActiveCount": 0,
"lockedActiveCount": 0,
"billingChurnCount": 0,
"nonRenewalChurnCount": 0,
"refundChurnCount": 0,
"chargebackChurnCount": 0,
"earlyChurnCount": 5,
"otherChurnCount": 2
}
],
"TotalCount": 2
}
Richiesta di esempio
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/subscriptions?applicationId=9NBLGGGZ5QDR&startDate=12/19/2021&endDate=04/20/2022&top=10&skip=0&orderby=date&groupby=date,subscriptionProductName,applicationName,skuId,market,deviceType&aggregationLevel=week
HTTP/1.1
Authorization: Bearer <your access token>
Risposta di esempio
{
"Value": [
{
"date": "2022-04-18",
"subscriptionProductName": "realms.subscription.monthly.10player.01",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Windows and Doors",
"skuId": "0100",
"market": "IT",
"deviceType": "Console-Xbox One",
"grossSalesBeforeTax": 0.0,
"totalActiveCount": 0,
"totalChurnCount": 0,
"newCount": 2,
"renewCount": 0,
"goodStandingActiveCount": 0,
"pendingGraceActiveCount": 0,
"graceActiveCount": 0,
"lockedActiveCount": 0,
"billingChurnCount": 0,
"nonRenewalChurnCount": 0,
"refundChurnCount": 0,
"chargebackChurnCount": 0,
"earlyChurnCount": 0,
"otherChurnCount": 0
},
{
"date": "2022-04-18",
"subscriptionProductName": "realms.subscription.monthly.10player.01",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Windows and Doors",
"skuId": "0100",
"market": "NO",
"deviceType": "Unknown",
"grossSalesBeforeTax": 0.0,
"totalActiveCount": 0,
"totalChurnCount": 0,
"newCount": 0,
"renewCount": 13,
"goodStandingActiveCount": 0,
"pendingGraceActiveCount": 0,
"graceActiveCount": 0,
"lockedActiveCount": 0,
"billingChurnCount": 0,
"nonRenewalChurnCount": 0,
"refundChurnCount": 0,
"chargebackChurnCount": 0,
"earlyChurnCount": 0,
"otherChurnCount": 0
},
{
"date": "2022-04-18",
"subscriptionProductName": "realms.subscription.monthly.10player.02",
"applicationId": "9NBLGGGZ5QDR",
"applicationName": "Windows and Doors",
"skuId": "0100",
"market": "CA",
"deviceType": "Unknown",
"grossSalesBeforeTax": 0.0,
"totalActiveCount": 152,
"totalChurnCount": 0,
"newCount": 0,
"renewCount": 270,
"goodStandingActiveCount": 133,
"pendingGraceActiveCount": 19,
"graceActiveCount": 0,
"lockedActiveCount": 0,
"billingChurnCount": 0,
"nonRenewalChurnCount": 0,
"refundChurnCount": 0,
"chargebackChurnCount": 0,
"earlyChurnCount": 0,
"otherChurnCount": 0
}
],
"TotalCount": 3
}
Argomenti correlati
- Report Acquisizioni componenti aggiuntivi
- Accedere ai dati di analisi usando i servizi di Microsoft Store