Ottenere i dati sulle acquisizioni per giochi e app

  • Articolo

Usare questo metodo nell'API di analisi di Microsoft Store per ottenere dati aggregati sulle acquisizioni in formato JSON per le app UWP e i giochi per Xbox One inseriti tramite il portale per sviluppatori Xbox (XDP) e disponibili nel dashboard del XDP Analytics.

Nota

Questa API non fornisce dati aggregati giornalieri prima del 1 ottobre 2016.

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

Intestazione della richiesta

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

Parametri della richiesta

Parametro Tipo Descrizione Richiesto
applicationId string L'ID prodotto del gioco Xbox One per il quale si stanno recuperando i dati di acquisizione. Per ottenere l'ID prodotto del gioco, passare al gioco nel programma XDP Analytics e recuperare l'ID prodotto dall'URL. In alternativa, se si scaricano i dati sulle acquisizioni dal report di analisi del Partner Center, il valore dell'ID prodotto viene incluso nel file con estensione .tsv. Sì
startDate data Data di inizio nell'intervallo di date dei dati sulle acquisizioni da recuperare. L'impostazione predefinita è la data corrente. No
endDate data Data di fine nell'intervallo di date dei dati sulle acquisizioni da recuperare. L'impostazione predefinita è la data corrente. No
filter string Una o più istruzioni che filtrano le righe nella risposta. Ogni istruzione contiene un nome di campo del corpo della risposta e un valore associati agli operatori eq o ne e le istruzioni possono essere combinate usando and o or. I valori stringa devono essere racchiusi tra virgolette singole nel parametro filter. Ad esempio, filter=market eq 'US' and gender eq 'm'.
È possibile specificare i campi seguenti del corpo della risposta:
  • acquisitionType
  • età
  • storeClient
  • sesso
  • market
  • osVersion
  • deviceType
  • sandboxId
 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. La sintassi è orderby=field [order],field [order],.... Il parametro field può essere una delle stringhe seguenti:
  • date
  • acquisitionType
  • età
  • storeClient
  • sesso
  • market
  • osVersion
  • deviceType
  • paymentInstrumentType
  • sandboxId
  • xboxTitleId
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
  • acquisitionType
  • età
  • storeClient
  • sesso
  • market
  • osVersion
  • deviceType
  • paymentInstrumentType
  • sandboxId
  • xboxTitleId
Le righe di dati restituite conterranno i campi specificati nel parametro groupby e i seguenti:
  • date
  • applicationId
  • acquisitionQuantity
Il parametro groupby può essere usato con il parametro aggregationLevel. Ad esempio: &groupby=age,market&aggregationLevel=week		 No

Esempio di richiesta

L'esempio seguente illustra diverse richieste di recupero dei dati sulle acquisizioni Xbox One game. Sostituire il valore applicationId con l'ID prodotto per il gioco.

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

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/acquisitions?applicationId=9WZDNCRFHXHT&startDate=1/1/2017&endDate=2/1/2019&skip=0&filter=market eq 'US' and gender eq 'm' HTTP/1.1 
Authorization: Bearer <your access token>

Response

Corpo della risposta

Valore Tipo Descrizione
valore matrice Matrice di oggetti che contengono i dati aggregati sulle acquisizioni per il gioco. Per ulteriori informazioni sui dati in ogni oggetto, vedere la sezione Valori delle acquisizioni seguente.
TotalCount integer Numero totale di righe nei risultati di dati per la query.

Valori di acquisizione

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.
applicationId string L'ID prodotto del gioco Xbox One per il quale si stanno recuperando i dati di acquisizione.
applicationName string Nome visualizzato del gioco.
acquisitionType string Una delle stringhe seguenti che indica il tipo di acquisizione:
  • Gratuito
  • Prova
  • Pagato
  • Promotional code
  • Iap
  • Subscription Iap
  • Destinatari privati
  • Pre Order
  • Xbox Game Pass (o Game Pass se si eseguono query sui dati prima del 23 marzo 2018)
  • Disco
  • Prepaid Code
  • Ordine pre-addebitato
  • Pre-ordine annullato
  • Pre-ordine non riuscito
età string Una delle stringhe seguenti che indica la fascia di età dell'utente che ha eseguito l'acquisizione:
  • Meno di 13
  • 13 - 17
  • 18 - 24
  • 25 - 34
  • 35 - 44
  • 44 - 55
  • Maggiore di 55
  • Unknown
deviceType string Una delle stringhe seguenti che specifica il tipo di dispositivo che ha completato l'acquisizione:
  • PC
  • Telefono
  • Console-Xbox One
  • Console-Xbox Series X
  • IoT
  • Server
  • Tablet
  • Holographic
  • Unknown
sesso string Una delle stringhe seguenti che specifica il sesso dell'utente che ha eseguito l'acquisizione:
  • m
  • f
  • Unknown
market string Codice Paese ISO 3166 del mercato in cui si è verificata l'acquisizione.
osVersion string Versione del sistema operativo in cui si è verificata l'acquisizione. Per questo metodo, questo valore è sempre Windows 10 o Windows 11.
paymentInstrumentType string Una delle stringhe seguenti che indica l'istruzione di pagamento usata per l'acquisizione:
  • Carta di credito
  • Carta di debito diretta
  • Acquisto dedotto
  • MS Balance
  • Operatore di telefonia mobile
  • Bonifico bancario online
  • PayPal
  • Divisione transazione
  • Riscatto dei token
  • Importo zero pagato
  • eWallet
  • Unknown
sandboxId string ID sandbox creato per il gioco. Può trattarsi del valore RETAIL o di un ID sandbox privato.
storeClient string Una delle stringhe seguenti che indica la versione dello Store in cui si è verificata l'acquisizione:
  • Windows Phone Store (client)
  • Microsoft Store (client) (o Windows Store (client) se si eseguono query su dati anteriori al 23 marzo 2018)
  • Microsoft Store (web) (o Windows Store (web) se si eseguono query su dati anteriori al 23 marzo 2018)
  • Volume purchase by organizations
  • Altro
xboxTitleId string ID titolo Xbox Live (rappresentato in valore esadecimale) assegnato dal portale per sviluppatori Xbox (XDP) per i giochi abilitati per Xbox Live.
acquisitionQuantity number Numero di acquisizioni che sono state effettuate al livello di aggregazione specificato.
purchasePriceUSDAmount number Importo pagato dal cliente per l'acquisizione, convertito in USD, utilizzando il tasso di cambio mensile.
purchaseTaxUSDAmount number Importo fiscale applicato all'acquisizione, convertito in USD.
localCurrencyCode string Codice valuta locale in base al paese dell'account del Partner Center.
xboxProductId string ID Prodotto Xbox del prodotto da XDP, se applicabile.
availabilityId string ID disponibilità del prodotto da XDP, se applicabile.
skuId string ID SKU del prodotto da XDP, se applicabile.
skuDisplayName string Nome SKU visualizzato del prodotto da XDP, se applicabile.
xboxParentProductId string ID Prodotto genitore Xbox del prodotto da XDP, se applicabile.
parentProductName string Nome Prodotto genitore Xbox del prodotto da XDP, se applicabile.
productTypeName string Nome tipo Prodotto del prodotto da XDP, se applicabile.
purchaseTaxType string Tipo di imposta per l'acquisto del prodotto da XDP, se applicabile.
purchasePriceLocalAmount number Importo del prezzo di acquisto locale del prodotto da XDP, se applicabile.
purchaseTaxLocalAmount number Importo delle tasse di acquisto locale del prodotto da XDP, se applicabile.

Risposta di esempio

L'esempio seguente illustra un esempio di corpo della risposta JSON per questa richiesta.

{ 
    "Value": [ 
        { 
            "date": "2019-01-15T01:00:00.0000000Z", 
            "applicationId": "9WZDNCRFHXHT", 
            "applicationName": null, 
            "acquisitionType": "Paid", 
            "age": null, 
            "deviceType": "Phone", 
            "gender": null, 
            "market": "US", 
            "osVersion": "Windows 11", 
            "paymentInstrumentType": null, 
            "sandboxId": "RETAIL", 
            "storeClient": "Microsoft Store (client)", 
            "xboxTitleId": null, 
            "localCurrencyCode": "USD", 
            "xboxProductId": null, 
            "availabilityId": "B42LRTSZ2MCJ", 
            "skuId": "0010", 
            "skuDisplayName": null, 
            "xboxParentProductId": null, 
            "parentProductName": null, 
            "productTypeName": "Game", 
            "purchaseTaxType": "TaxesNotIncluded", 
            "acquisitionQuantity": 1, 
            "purchasePriceUSDAmount": 3.08, 
            "purchasePriceLocalAmount": 3.08, 
            "purchaseTaxUSDAmount": 0.09, 
            "purchaseTaxLocalAmount": 0.09 
        } 
    ], 

    "@nextLink": null,
    
    "TotalCount": 12221 
}