Ottenere i dati sulle acquisizioni dei componenti aggiuntivi per giochi e appGet add-on acquisitions data for your games and apps

Usare questo metodo nell'API Microsoft Store Analytics per ottenere i dati di acquisizione del componente aggiuntivo di aggregazione in formato JSON per le app UWP e i giochi Xbox One che sono stati inseriti tramite il portale per sviluppatori Xbox (XDP) e disponibili nel dashboard del centro per i partner di XDP Analytics.Use this method in the Microsoft Store analytics API to get aggregate add-on acquisition data in JSON format for UWP apps and Xbox One games that were ingested through the Xbox Developer Portal (XDP) and available in the XDP Analytics Partner Center dashboard.

PrerequisitiPrerequisites

Per usare questo metodo, devi prima eseguire le operazioni seguenti:To use this method, you need to first do the following:

  • Se non è già stato fatto, completare tutti i prerequisiti per l'API di analisi del Microsoft Store.If you have not done so already, complete all the prerequisites for the Microsoft Store analytics API.
  • Ottieni un token di accesso di Azure AD da usare nell'intestazione della richiesta per questo metodo.Obtain an Azure AD access token to use in the request header for this method. Dopo aver ottenuto un token di accesso, questo sarà disponibile per 60 minuti prima della scadenza.After you obtain an access token, you have 60 minutes to use it before it expires. Dopo la scadenza del token, puoi ottenerne uno nuovo.After the token expires, you can obtain a new one.

Nota

Questa API non fornisce dati aggregati giornalieri prima del 1 ° ottobre 2016.This API does not provide daily aggregate data before Oct 1st 2016.

RichiestaRequest

Sintassi della richiestaRequest syntax

MetodoMethod URI richiestaRequest URI
GETGET https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions

Intestazione della richiestaRequest header

IntestazioneHeader TipoType DescrizioneDescription
AutorizzazioneAuthorization stringstring Obbligatorio.Required. Il token di accesso Azure AD nel form Bearer <token> .The Azure AD access token in the form Bearer <token>.

Parametri della richiestaRequest parameters

Il parametro ApplicationID o addonProductId è obbligatorio.The applicationId or addonProductId parameter is required. Per recuperare i dati sulle acquisizioni per tutti i componenti aggiuntivi registrati nell'app, specifica il parametro applicationId.To retrieve acquisition data for all add-ons registered to the app, specify the applicationId parameter. Per recuperare i dati di acquisizione per un singolo componente aggiuntivo, specificare il parametro addonProductId .To retrieve acquisition data for a single add-on, specify the addonProductId parameter. Se li specifichi entrambi, il parametro applicationId viene ignorato.If you specify both, the applicationId parameter is ignored.

ParametroParameter TypeType DescriptionDescription ObbligatoriaRequired
applicationIdapplicationId stringstring ProductID del gioco Xbox One per cui si stanno recuperando i dati di acquisizione.The productId of the Xbox One game for which you are retrieving acquisition data. Per ottenere il ProductID del gioco, passare al gioco nel programma XDP Analytics e recuperare il ProductID dall'URL.To get the productId of your game, navigate to your game in the XDP Analytics Program and retrieve the productId from the URL. In alternativa, se si scaricano i dati delle acquisizioni dal report di analisi dei partner Center, il ProductID viene incluso nel file con estensione TSV.Alternatively, if you download your acquisitions data from the Partner Center analytics report, the productId is included in the .tsv file. Yes
addonProductIdaddonProductId stringstring ProductID del componente aggiuntivo per il quale si desidera recuperare i dati di acquisizione.The productId of the add-on for which you want to retrieve acquisition data. Yes
startDatestartDate datedate Data di inizio nell'intervallo di date dei dati sulle acquisizioni del componente aggiuntivo da recuperare.The start date in the date range of add-on acquisition data to retrieve. L'impostazione predefinita è la data corrente.The default is the current date. NoNo
endDateendDate datedate Data di fine nell'intervallo di date dei dati sulle acquisizioni del componente aggiuntivo da recuperare.The end date in the date range of add-on acquisition data to retrieve. L'impostazione predefinita è la data corrente.The default is the current date. NoNo
toptop intint Numero di righe di dati da restituire nella richiesta.The number of rows of data to return in the request. Il valore massimo e il valore predefinito se non specificato è 10000.The maximum value and the default value if not specified is 10000. Se nella query sono presenti più righe, il corpo della risposta include un link successivo che puoi usare per richiedere la pagina successiva dei dati.If there are more rows in the query, the response body includes a next link that you can use to request the next page of data. NoNo
skipskip intint Numero di righe da ignorare nella query.The number of rows to skip in the query. Usa questo parametro per scorrere set di dati di grandi dimensioni.Use this parameter to page through large data sets. Ad esempio, top=10000 e skip=0 recupera le prime 10000 righe di dati, top=10000 e skip=10000 recupera le 10000 righe successive e così via.For example, top=10000 and skip=0 retrieves the first 10000 rows of data, top=10000 and skip=10000 retrieves the next 10000 rows of data, and so on. NoNo
filterfilter stringstring Una o più istruzioni per filtrare le righe nella risposta.One or more statements that filter the rows in the response. Ogni istruzione contiene un nome di campo dal corpo della risposta e il valore associati agli operatori EQ o ne e le istruzioni possono essere combinate tramite and o or.Each statement contains a field name from the response body and value that are associated with the eq or ne operators, and statements can be combined using and or or. I valori stringa devono essere racchiusi tra virgolette singole nel parametro filter.String values must be surrounded by single quotes in the filter parameter. Ad esempio, Filter = Market EQ "US" e Gender EQ ' m'.For example, filter=market eq 'US' and gender eq 'm'.
È possibile specificare i campi seguenti dal corpo della risposta:You can specify the following fields from the response body:
  • acquisitionTypeacquisitionType
  • etàage
  • storeClientstoreClient
  • gendergender
  • mercatomarket
  • osVersionosVersion
  • deviceTypedeviceType
  • sandboxIdsandboxId
NoNo
aggregationLevelaggregationLevel stringstring Specifica l'intervallo di tempo per cui recuperare dati aggregati.Specifies the time range for which to retrieve aggregate data. Può essere una delle stringhe seguenti: day, week o month.Can be one of the following strings: day, week, or month. Se non viene specificato, il valore predefinito è day.If unspecified, the default is day. NoNo
orderbyorderby stringstring Istruzione che ordina i valori dei dati dei risultati per ogni acquisizione del componente aggiuntivo.A statement that orders the result data values for each add-on acquisition. La sintassi è OrderBy = Field [Order], Field [Order],... Il parametro Field può essere una delle seguenti stringhe:The syntax is orderby=field [order],field [order],... The field parameter can be one of the following strings:
  • datedate
  • acquisitionTypeacquisitionType
  • etàage
  • storeClientstoreClient
  • gendergender
  • mercatomarket
  • osVersionosVersion
  • deviceTypedeviceType
  • orderNameorderName
Il parametro order è facoltativo e può essere asc o desc per specificare l’ordine crescente o decrescente per ogni campo.The order parameter is optional, and can be asc or desc to specify ascending or descending order for each field. Il valore predefinito è ASC.The default is asc.
Di seguito è riportato un esempio di stringa OrderBy : OrderBy = date, MarketHere is an example orderby string: orderby=date,market
NoNo
groupbygroupby stringstring Istruzione che applica l'aggregazione dei dati solo ai campi specificati.A statement that applies data aggregation only to the specified fields. Puoi specificare i campi seguenti:You can specify the following fields:
  • datedate
  • applicationNameapplicationName
  • addonProductNameaddonProductName
  • acquisitionTypeacquisitionType
  • etàage
  • storeClientstoreClient
  • gendergender
  • mercatomarket
  • osVersionosVersion
  • deviceTypedeviceType
  • paymentInstrumentTypepaymentInstrumentType
  • sandboxIdsandboxId
  • xboxTitleIdHexxboxTitleIdHex
Le righe di dati restituite conterranno i campi specificati nel parametro groupby, oltre ai seguenti:The returned data rows will contain the fields specified in the groupby parameter as well as the following:
  • datedate
  • applicationIdapplicationId
  • addonProductIdaddonProductId
  • acquisitionQuantityacquisitionQuantity
Il parametro groupby può essere usato con il parametro aggregationLevel.The groupby parameter can be used with the aggregationLevel parameter. Ad esempio: &GroupBy = Age, market&aggregationLevel = weekFor example: &groupby=age,market&aggregationLevel=week
NoNo

Esempio di richiestaRequest example

L'esempio seguente illustra varie richieste per il recupero di dati sulle acquisizioni di componenti aggiuntivi.The following examples demonstrates several requests for getting add-on acquisition data. Sostituire i valori addonProductId e APPLICATIONID con l'ID di archivio appropriato per il componente aggiuntivo o l'app.Replace the addonProductId and applicationId values with the appropriate Store ID for your add-on or app.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions?applicationId=9WZDNCRFJ314&startDate=1/1/2015&endDate=2/1/2015&skip=0 HTTP/1.1 

Authorization: Bearer <your access token> 

 

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/addonacquisitions?applicationId=9WZDNCRFJ314&startDate=1/1/2015&endDate=2/1/2015&skip=0&filter=market eq 'GB' and gender eq 'm' HTTP/1.1 

Authorization: Bearer <your access token>

RispostaResponse

Corpo della rispostaResponse body

ValoreValue TipoType DescrizioneDescription
ValoreValue arrayarray Matrice di oggetti che contengono i dati aggregati sulle acquisizioni di componenti aggiuntivi.An array of objects that contain aggregate add-on acquisition data. Per altre informazioni sui dati in ogni oggetto, vedi la sezione Valori di acquisizione di componenti aggiuntivi di seguito.For more information about the data in each object, see the add-on acquisition values section below.
@nextLink stringstring In presenza di altre pagine di dati, questa stringa contiene un URI che puoi usare per richiedere la pagina successiva dei dati.If there are additional pages of data, this string contains a URI that you can use to request the next page of data. Ad esempio, questo valore viene restituito se il parametro top della richiesta è impostato su 10000 ma sono presenti più di 10000 righe di dati di acquisizione di componenti aggiuntivi per la query.For example, this value is returned if the top parameter of the request is set to 10000 but there are more than 10000 rows of add-on acquisition data for the query.
TotalCountTotalCount intint Numero totale di righe nei dati risultanti dalla query.The total number of rows in the data result for the query.

Valori di acquisizione di componenti aggiuntiviAdd-on acquisition values

Gli elementi nella matrice Value contengono i valori seguenti.Elements in the Value array contain the following values.

ValoreValue TipoType DescrizioneDescription
datedate stringstring Prima data nell'intervallo di date per i dati di acquisizione.The first date in the date range for the acquisition data. Se la richiesta specifica un singolo giorno, questo valore è la data.If the request specified a single day, this value is that date. Se la richiesta specifica una settimana, un mese o un altro intervallo di date, questo valore è la prima data in tale intervallo.If the request specified a week, month, or other date range, this value is the first date in that date range.
addonProductIdaddonProductId stringstring ProductID del componente aggiuntivo per il quale si recuperano i dati di acquisizione.The productId of the add-on for which you are retrieving acquisition data.
addonProductNameaddonProductName stringstring Nome visualizzato del componente aggiuntivo.The display name of the add-on. Questo valore viene visualizzato nei dati di risposta solo se il parametro aggregationLevel è impostato su Day, a meno che non si specifichi il campo addonProductName nel parametro GroupBy .This value only appears in the response data if the aggregationLevel parameter is set to day, unless you specify the addonProductName field in the groupby parameter.
applicationIdapplicationId stringstring ProductID dell'app per cui si desidera recuperare i dati di acquisizione del componente aggiuntivo.The productId of the app for which you want to retrieve add-on acquisition data.
applicationNameapplicationName stringstring Nome visualizzato del gioco.The display name of the game.
deviceTypedeviceType stringstring Una delle stringhe seguenti che specifica il tipo di dispositivo che ha completato l'acquisizione:One of the following strings that specifies the type of device that completed the acquisition:
  • PC"PC"
  • Phone"Phone"
  • "Console-Xbox One""Console-Xbox One"
  • "Console-serie Xbox X""Console-Xbox Series X"
  • Sacco"IoT"
  • Server"Server"
  • Tablet"Tablet"
  • Holographic"Holographic"
  • Sconosciuto"Unknown"
storeClientstoreClient stringstring Una delle stringhe seguenti che indica la versione dell'archivio in cui si è verificata l'acquisizione:One of the following strings that indicates the version of the Store where the acquisition occurred:
  • "Archivio Windows Phone (client)""Windows Phone Store (client)"
  • "Microsoft Store (client)" (o "Windows Store (client)" Se si eseguono query per i dati prima del 23 marzo 2018)"Microsoft Store (client)" (or "Windows Store (client)" if querying for data before March 23, 2018)
  • "Microsoft Store (Web)" (o "Windows Store (Web)" Se si eseguono query per i dati prima del 23 marzo 2018)"Microsoft Store (web)" (or "Windows Store (web)" if querying for data before March 23, 2018)
  • "Volume Purchase by Organizations""Volume purchase by organizations"
  • Altri"Other"
osVersionosVersion stringstring Versione del sistema operativo in cui è avvenuta l'acquisizione.The OS version on which the acquisition occurred. Per questo metodo, questo valore è sempre "Windows 10".For this method, this value is always "Windows 10".
marketmarket stringstring Codice paese ISO 3166 del mercato in cui ha avuto luogo l'acquisizione.The ISO 3166 country code of the market where the acquisition occurred.
gendergender stringstring Una delle stringhe seguenti che specifica il genere dell'utente che ha effettuato l'acquisizione:One of the following strings that specifies the gender of the user who made the acquisition:
  • "m""m"
  • "f""f"
  • Sconosciuto"Unknown"
ageage stringstring Una delle stringhe seguenti che indica il gruppo di età dell'utente che ha effettuato l'acquisizione:One of the following strings that indicates the age group of the user who made the acquisition:
  • "minore di 13""less than 13"
  • "13-17""13-17"
  • "18-24""18-24"
  • "25-34""25-34"
  • "35-44""35-44"
  • "44-55""44-55"
  • "maggiore di 55""greater than 55"
  • Sconosciuto"Unknown"
acquisitionTypeacquisitionType stringstring Una delle stringhe seguenti che indica il tipo di acquisizione:One of the following strings that indicates the type of acquisition:
  • Libero"Free"
  • Valutazione"Trial"
  • Pagato"Paid"
  • "Codice promozionale""Promotional code"
  • IAP"Iap"
  • "Sottoscrizione IAP""Subscription Iap"
  • "Pubblico privato""Private Audience"
  • "Pre-ordine""Pre Order"
  • "Xbox game pass" (o "game pass" Se si esegue una query per i dati prima del 23 marzo 2018)"Xbox Game Pass" (or "Game Pass" if querying for data before March 23, 2018)
  • Disco"Disk"
  • "Codice prepagato""Prepaid Code"
  • "Ordine pre addebitato""Charged Pre Order"
  • "Pre-ordine annullato""Cancelled Pre Order"
  • "Pre-ordinamento non riuscito""Failed Pre Order"
acquisitionQuantityacquisitionQuantity integerinteger Numero di acquisizioni avvenute.The number of acquisitions that occurred.
inAppProductIdinAppProductId stringstring ID prodotto del prodotto in cui viene utilizzato questo componente aggiuntivo.Product ID of the product where this add-on is used.
inAppProductNameinAppProductName stringstring Nome del prodotto in cui viene utilizzato questo componente aggiuntivo.Product Name of the product where this add-on is used.
paymentInstrumentTypepaymentInstrumentType stringstring Tipo di strumento di pagamento utilizzato per l'acquisizione.Payment instrument type used for the acquisition.
sandboxIdsandboxId stringstring ID sandbox creato per il gioco.The Sandbox ID created for the game. Può trattarsi del valore retail o di un ID sandbox privato.This can be the value RETAIL or a private sandbox ID.
xboxTitleIdxboxTitleId stringstring ID del titolo Xbox del prodotto da XDP, se applicabile.Xbox Title ID of the product from XDP, if applicable.
localCurrencyCodelocalCurrencyCode stringstring Codice di valuta locale in base al paese dell'account del centro per i partner.Local Currency code based on the country of the Partner Center account.
xboxProductIdxboxProductId stringstring ID prodotto Xbox del prodotto da XDP, se applicabile.Xbox Product ID of the product from XDP, if applicable.
availabilityIdavailabilityId stringstring ID di disponibilità del prodotto da XDP, se applicabile.Availability ID of the product from XDP, if applicable.
skuIdskuId stringstring ID dello SKU del prodotto da XDP, se applicabile.SKU ID of the product from XDP, if applicable.
skuDisplayNameskuDisplayName stringstring Nome visualizzato dello SKU del prodotto da XDP, se applicabile.SKU Display Name of the product from XDP, if applicable.
xboxParentProductIdxboxParentProductId stringstring ID del prodotto padre Xbox del prodotto da XDP, se applicabile.Xbox Parent Product ID of the product from XDP, if applicable.
parentProductNameparentProductName stringstring Nome del prodotto padre del prodotto da XDP, se applicabile.Parent Product Name of the product from XDP, if applicable.
productTypeNameproductTypeName stringstring Nome del tipo di prodotto del prodotto da XDP, se applicabile.Product Type Name of the product from XDP, if applicable.
purchaseTaxTypepurchaseTaxType stringstring Tipo di imposta di acquisto del prodotto da XDP, se applicabile.Purchase Tax Type of the product from XDP, if applicable.
purchasePriceUSDAmountpurchasePriceUSDAmount d'acquistonumber Importo pagato dal cliente per il componente aggiuntivo, convertito in USD.The amount paid by the customer for the add-on, converted to USD.
purchasePriceLocalAmountpurchasePriceLocalAmount d'acquistonumber Importo dell'imposta applicato al componente aggiuntivo.The tax amount applied to the add-on.
purchaseTaxUSDAmountpurchaseTaxUSDAmount d'acquistonumber Importo dell'imposta applicato al componente aggiuntivo, convertito in USD.The tax amount applied to the add-on, converted to USD.
purchaseTaxLocalAmountpurchaseTaxLocalAmount d'acquistonumber Acquistare l'importo locale dell'imposta sul prodotto da XDP, se applicabile.Purchase Tax Local Amount of the product from XDP, if applicable.

Esempio di rispostaResponse example

L'esempio seguente illustra un esempio di corpo della risposta JSON per questa richiesta.The following example demonstrates an example JSON response body for this request.

{ 
  "Value": [ 
    { 
            "inAppProductId": "9NBLGGH1864K", 
            "inAppProductName": "866879", 
            "addonProductId": "9NBLGGH1864K", 
            "addonProductName": "866879", 
            "date": "2017-11-05", 
            "applicationId": "9WZDNCRFJ314", 
            "applicationName": "Tetris Blitz", 
            "acquisitionType": "Iap", 
            "age": "35-49", 
            "deviceType": "Phone", 
            "gender": "m", 
            "market": "US", 
            "osVersion": "Windows Phone 8.1", 
            "paymentInstrumentType": "Credit Card", 
            "sandboxId": "RETAIL", 
            "storeClient": "Windows Phone Store (client)", 
            "xboxTitleId": "", 
            "localCurrencyCode": "USD", 
            "xboxProductId": "00000000-0000-0000-0000-000000000000", 
            "availabilityId": "", 
            "skuId": "", 
            "skuDisplayName": "Full", 
            "xboxParentProductId": "", 
            "parentProductName": "Tetris Blitz", 
            "productTypeName": "Add-On", 
            "purchaseTaxType": "", 
            "acquisitionQuantity": 1, 
            "purchasePriceUSDAmount": 1.08, 
            "purchasePriceLocalAmount": 0.09, 
            "purchaseTaxUSDAmount": 1.08, 
            "purchaseTaxLocalAmount": 0.09 
        } 
    ], 

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