Ottenere le acquisizioni dei componenti aggiuntivi

  • Articolo

Usare questo metodo nell'API di analisi di Microsoft Store per ottenere dati aggregati sulle acquisizioni per i componenti aggiuntivi dell'app in formato JSON durante un determinato intervallo di date e altri filtri opzionali. Queste informazioni sono disponibili anche nel report sulle acquisizioni dei componenti aggiuntivi nel Centro per i partner.

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.

Richiesta

Sintassi della richiesta

metodo URI della richiesta
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions

Intestazione della richiesta

Intestazione Type Descrizione
Autorizzazione stringa Obbligatorio. Token di accesso di Azure AD nel formato Token di<connessione>.

Parametri della richiesta

Il parametro applicationId o inAppProductId è obbligatorio. Per recuperare i dati sulle acquisizioni di tutti i componenti aggiuntivi registrati nell'app, specificare il parametro applicationId. Per recuperare i dati sulle acquisizioni di un singolo componente aggiuntivo, specificare il parametro inAppProductId. Se si specificano entrambi, il parametro applicationId viene ignorato.

Parametro Tipo Descrizione Richiesto
applicationId string ID dello Store dell'app per cui si desidera recuperare i dati sulle acquisizioni del componente aggiuntivo. Sì
inAppProductId string ID dello Store del componente aggiuntivo per cui si desidera recuperare i dati sulle acquisizioni del componente aggiuntivo. Sì
startDate data Data di inizio nell'intervallo di date dei dati sulle acquisizioni del componente aggiuntivo 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 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 10000. 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 le righe nella risposta. Per ulteriori informazioni, vedere la sezione Campi filtro seguente. No
aggregationLevel string Specifica l'intervallo di tempo per il quale recuperare i dati aggregati. Può essere una delle stringhe seguenti: day, week o month. Se non è specificato, il valore predefinito è day. No
orderby string Istruzione che ordina i valori dei dati dei risultati per ogni acquisizione del componente aggiuntivo. La sintassi è orderby=field [order],field [order],.... Il parametro field può essere una delle stringhe seguenti:
  • date
  • acquisitionType
  • ageGroup
  • storeClient
  • sesso
  • market
  • osVersion
  • deviceType
  • orderName

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:
  • date
  • applicationName
  • inAppProductName
  • acquisitionType
  • ageGroup
  • storeClient
  • sesso
  • market
  • osVersion
  • deviceType
  • orderName

Le righe di dati restituite conterranno i campi specificati nel parametro groupby e i seguenti:

  • date
  • applicationId
  • inAppProductId
  • acquisitionQuantity

Il parametro groupby può essere usato con il parametro aggregationLevel. Ad esempio: &groupby=ageGroup,market&aggregationLevel=week

 No

Campi filtro

Il parametro filter della richiesta contiene una o più istruzioni che filtrano le righe nella risposta. Ogni istruzione contiene un campo e un valore associati agli operatori eq o ne e le istruzioni possono essere combinate usando gli operatori and o or. Di seguito sono riportati alcuni esempi di parametri filter:

  • filter=market eq 'US' and gender eq 'm'
  • filter=(market ne 'US') and (gender ne 'Unknown') and (gender ne 'm') and (market ne 'NO') and (ageGroup ne 'greater than 55' or ageGroup ne ‘less than 13’)

Per un elenco dei campi supportati, vedere la tabella seguente. I valori stringa devono essere racchiusi tra virgolette singole nel parametro filter.

Campi Descrizione
acquisitionType Una delle stringhe seguenti:
  • free
  • prova
  • pagato
  • promotional code
  • iap
ageGroup Una delle stringhe seguenti:
  • Meno di 13
  • 13 - 17
  • 18 - 24
  • 25 - 34
  • 35 - 44
  • 44 - 55
  • greater than 55
  • Unknown
storeClient Una delle stringhe seguenti:
  • Windows Phone Store (client)
  • Microsoft Store (client)
  • Microsoft Store (web)
  • Volume purchase by organizations
  • Altro
sesso Una delle stringhe seguenti:
  • m
  • f
  • Unknown
market Stringa contenente il codice Paese ISO 3166 del mercato in cui è stata effettuata l'acquisizione.
osVersion Una delle stringhe seguenti:
  • Windows Phone 7.5
  • Windows Phone 8
  • Windows Phone 8.1
  • Windows Phone 10
  • Windows 8
  • Windows 8.1
  • Windows 10
  • Windows 11
  • Unknown
deviceType Una delle stringhe seguenti:
  • PC
  • Telefono
  • Console-Xbox One
  • Console-Xbox Series X
  • IoT
  • Holographic
  • Unknown
orderName Stringa che specifica il nome dell'ordine per il codice promozionale usato per acquisire il componente aggiuntivo (si applica solo se l'utente ha acquisito il componente aggiuntivo riscattando un codice promozionale).

Esempio di richiesta

Gli esempi seguenti illustrano diverse richieste di recupero dei dati sulle acquisizioni del componenti aggiuntivo. Sostituire i valori inAppProductId e applicationId con l'ID dello Store ID appropriato per il componente aggiuntivo o l'app.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions?inAppProductId=9NBLGGGZ5QDR&startDate=1/1/2015&endDate=2/1/2015&top=10&skip=0 HTTP/1.1
Authorization: Bearer <your access token>

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions?applicationId=9NBLGGGZ5QDR&startDate=1/1/2015&endDate=2/1/2015&top=10&skip=0 HTTP/1.1
Authorization: Bearer <your access token>

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions?inAppProductId=9NBLGGGZ5QDR&startDate=1/1/2015&endDate=7/3/2015&top=100&skip=0&filter=market ne 'US' and gender ne 'Unknown' and gender ne 'm' and market ne 'NO' and ageGroup ne '>55' 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. Per maggiori informazioni sui dati in ogni oggetto, vedere la sezione Valori acquisizioni componente aggiuntivo 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 per la query.
TotalCount int Numero totale di righe nei risultati di dati per la query.

Valori acquisizione componente aggiuntivo

Gli elementi nella matrice Value contengono i valori seguenti.

Valore Tipo Descrizione
data string Prima data dell'intervallo di date per i dati sulle acquisizioni. 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.
inAppProductId string ID dello Store del componente aggiuntivo per cui si stanno recuperando i dati sulle acquisizioni.
inAppProductName string Nome visualizzato del componente aggiuntivo. Questo valore viene visualizzato nei dati della risposta solo se il parametro aggregationLevel è impostato su day, a meno che non si specifichi il campo inAppProductName nel parametro groupby.
applicationId string ID dello Store dell'app per cui si desidera recuperare i dati sulle acquisizioni del componente aggiuntivo.
applicationName string Nome visualizzato dell'app.
deviceType string Tipo di dispositivo che ha completato l'acquisizione. Per un elenco delle stringhe supportate, vedere la sezione Campi filtro precedente.
orderName string Nome dell'ordine.
storeClient string Versione dello Store in cui si è verificata l'acquisizione. Per un elenco delle stringhe supportate, vedere la sezione Campi filtro precedente.
osVersion string Versione del sistema operativo in cui si è verificata l'acquisizione. Per un elenco delle stringhe supportate, vedere la sezione Campi filtro precedente.
market string Codice Paese ISO 3166 del mercato in cui si è verificata l'acquisizione.
sesso string Sesso dell'utente che ha effettuato l'acquisizione. Per un elenco delle stringhe supportate, vedere la sezione Campi filtro precedente.
ageGroup string Fascia di età dell'utente che ha effettuato l'acquisizione. Per un elenco delle stringhe supportate, vedere la sezione Campi filtro precedente.
acquisitionType string Tipo di acquisizione (gratuita, a pagamento e così via). Per un elenco delle stringhe supportate, vedere la sezione Campi filtro precedente.
acquisitionQuantity integer Numero di acquisizioni che si sono verificate.

Esempio di richiesta e risposta

Il frammento di codice seguente illustra una richiesta di esempio e il corpo della risposta JSON per tali richieste.

Richiesta di esempio

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/inappacquisitions?applicationId=9NBLGGGZ5QDR
HTTP/1.1
Authorization: Bearer <your access token>

Risposta di esempio

{
    "Value": [
        {
            "applicationId": "9NBLGGGZ5QDR",
            "inAppProductName": "Deluxe Collector's Edition",
            "addonProductId": "9NBLGGAAGZDQ",
            "date": "2022-07-29",
            "acquisitionQuantity": 1,
            "purchasePriceUSDAmount": 18.12,
            "purchasePriceLocalAmount": 18.12,
            "purchaseTaxUSDAmount": 1.13,
            "purchaseTaxLocalAmount": 1.13
        },
        {
            "applicationId": "9NBLGGGZ5QDR",
            "inAppProductName": "Episode 4",
            "addonProductId": "9NAAAAAAAAAQ",
            "date": "2017-01-07",
            "acquisitionQuantity": 1,
            "purchasePriceUSDAmount": 4.147206,
            "purchasePriceLocalAmount": 3.99,
            "purchaseTaxUSDAmount": 0.686004,
            "purchaseTaxLocalAmount": 0.66
        },
        {
            "applicationId": "9NBLGGGZ5QDR",
            "inAppProductName": "Deluxe Collector's Edition",
            "addonProductId": "9NALGGGZ5QDQ",
            "date": "2018-04-01",
            "acquisitionQuantity": 1,
            "purchasePriceUSDAmount": 1.99,
            "purchasePriceLocalAmount": 1.99,
            "purchaseTaxUSDAmount": 0.0,
            "purchaseTaxLocalAmount": 0.0
        },
        {
            "applicationId": "9NBLGGGZ5QDR",
            "inAppProductName": "Strategy Guide Episode 4",
            "addonProductId": "9NBLGGGZ5QDQ",
            "date": "2021-11-25",
            "acquisitionQuantity": 1,
            "purchasePriceUSDAmount": 1.31902922876179,
            "purchasePriceLocalAmount": 150.0,
            "purchaseTaxUSDAmount": 0.114315866492689,
            "purchaseTaxLocalAmount": 13.0
        },
    ],
    "TotalCount": 4,
    "DataFreshnessTimestamp": "2022-07-29T05:54:00"
}