Ottenere le acquisizioni dei componenti aggiuntiviGet add-on acquisitions

Usare questo metodo nell'API Microsoft Store Analytics per ottenere i dati di acquisizione aggregati per i componenti aggiuntivi per l'app in formato JSON durante un intervallo di date specificato e altri filtri facoltativi.Use this method in the Microsoft Store analytics API to get aggregate acquisition data for add-ons for your app in JSON format during a given date range and other optional filters. Queste informazioni sono disponibili anche nel report acquisizioni componenti aggiuntivi nel centro per i partner.This information is also available in the Add-on acquisitions report in Partner Center.

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.

RichiestaRequest

Sintassi della richiestaRequest syntax

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

Intestazione della richiestaRequest header

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

Parametri della richiestaRequest parameters

Il parametro applicationId o inAppProductId è obbligatorio.The applicationId or inAppProductId 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 sulle acquisizioni per un unico componente aggiuntivo, specifica il parametro inAppProductId.To retrieve acquisition data for a single add-on, specify the inAppProductId 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 ID dello Store dell'app per cui si desidera recuperare i dati di acquisizione dei componenti aggiuntivi.The Store ID of the app for which you want to retrieve add-on acquisition data. Yes
inAppProductIdinAppProductId stringstring ID dello Store del componente aggiuntivo per il quale si desidera recuperare i dati di acquisizione.The Store ID 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. Per altre informazioni, vedi la sezione Campi di filtro più avanti.For more information, see the filter fields section below. 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
  • ageGroupageGroup
  • 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
  • inAppProductNameinAppProductName
  • acquisitionTypeacquisitionType
  • ageGroupageGroup
  • storeClientstoreClient
  • gendergender
  • mercatomarket
  • osVersionosVersion
  • deviceTypedeviceType
  • orderNameorderName

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
  • inAppProductIdinAppProductId
  • acquisitionQuantityacquisitionQuantity

Il parametro groupby può essere usato con il parametro aggregationLevel.The groupby parameter can be used with the aggregationLevel parameter. Ad esempio: & GroupBy = ageGroup, Market & aggregationLevel = weekFor example: &groupby=ageGroup,market&aggregationLevel=week

NoNo

Campi di filtroFilter fields

Il parametro filter della richiesta include una o più istruzioni per filtrare le righe nella risposta.The filter parameter of the request contains one or more statements that filter the rows in the response. Ogni istruzione contiene un campo e un valore associati con gli operatori eq o ne e le istruzioni possono essere combinate con and o or.Each statement contains a field and value that are associated with the eq or ne operators, and statements can be combined using and or or. Ecco alcuni esempi di parametri filter:Here are some example filter parameters:

  • filter=market eq 'US' and gender eq 'm'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’)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, vedi la tabella seguente.For a list of the supported fields, see the following table. I valori stringa devono essere racchiusi tra virgolette singole nel parametro filter.String values must be surrounded by single quotes in the filter parameter.

CampiFields DescrizioneDescription
acquisitionTypeacquisitionType Una delle stringhe seguenti:One of the following strings:
  • liberofree
  • valutazionetrial
  • pagatopaid
  • promotional codepromotional code
  • iapiap
ageGroupageGroup Una delle stringhe seguenti:One of the following strings:
  • less than 13less than 13
  • 13-1713-17
  • 18-2418-24
  • 25-3425-34
  • 35-4435-44
  • 44-5544-55
  • greater than 55greater than 55
  • UnknownUnknown
storeClientstoreClient Una delle stringhe seguenti:One of the following strings:
  • Windows Phone Store (client)Windows Phone Store (client)
  • Microsoft Store (client)Microsoft Store (client)
  • Microsoft Store (Web)Microsoft Store (web)
  • Volume purchase by organizationsVolume purchase by organizations
  • AltroOther
gendergender Una delle stringhe seguenti:One of the following strings:
  • mm
  • ff
  • UnknownUnknown
marketmarket Stringa che contiene il codice paese ISO 3166 del mercato in cui ha avuto luogo l'acquisizione.A string that contains the ISO 3166 country code of the market where the acquisition occurred.
osVersionosVersion Una delle stringhe seguenti:One of the following strings:
  • Windows Phone 7.5Windows Phone 7.5
  • Windows Phone 8Windows Phone 8
  • Windows Phone 8.1Windows Phone 8.1
  • Windows Phone 10Windows Phone 10
  • Windows 8Windows 8
  • Windows 8.1Windows 8.1
  • Windows 10Windows 10
  • UnknownUnknown
deviceTypedeviceType Una delle stringhe seguenti:One of the following strings:
  • PCPC
  • PhonePhone
  • Console-Xbox OneConsole-Xbox One
  • Console-serie Xbox XConsole-Xbox Series X
  • IoTIoT
  • HolographicHolographic
  • UnknownUnknown
orderNameorderName 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).A string that specifies the name of the order for the promotional code that was used to acquire the add-on (this only applies if the user acquired the add-on by redeeming a promotional code).

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. Sostituisci i valori inAppProductId e applicationId con l'ID dello Store appropriato per il componente aggiuntivo o l'app.Replace the inAppProductId and applicationId values with the appropriate Store ID for your add-on or 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>

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.
inAppProductIdinAppProductId stringstring ID dello Store del componente aggiuntivo per cui stai recuperando i dati sulle acquisizioni.The Store ID of the add-on for which you are retrieving acquisition data.
inAppProductNameinAppProductName 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 nel parametro groupby non sia stato specificato il campo inAppProductName.This value only appears in the response data if the aggregationLevel parameter is set to day, unless you specify the inAppProductName field in the groupby parameter.
applicationIdapplicationId stringstring ID dello Store dell'app per cui vuoi recuperare i dati sulle acquisizioni dei componenti aggiuntivi.The Store ID of the app for which you want to retrieve add-on acquisition data.
applicationNameapplicationName stringstring Nome visualizzato dell'app.The display name of the app.
deviceTypedeviceType stringstring Tipo di dispositivo che ha completato l'acquisizione.The type of device that completed the acquisition. Per un elenco delle stringhe supportate, vedi la sezione Campi di filtro più indietro.For a list of the supported strings, see the filter fields section above.
orderNameorderName stringstring Nome dell'ordine.The name of the order.
storeClientstoreClient stringstring Versione dello Store in cui si è avvenuta l'acquisizione.The version of the Store where the acquisition occurred. Per un elenco delle stringhe supportate, vedi la sezione Campi di filtro più indietro.For a list of the supported strings, see the filter fields section above.
osVersionosVersion stringstring Versione del sistema operativo in cui è avvenuta l'acquisizione.The OS version on which the acquisition occurred. Per un elenco delle stringhe supportate, vedi la sezione Campi di filtro più indietro.For a list of the supported strings, see the filter fields section above.
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 Sesso dell'utente che ha effettuato l'acquisizione.The gender of the user who made the acquisition. Per un elenco delle stringhe supportate, vedi la sezione Campi di filtro più indietro.For a list of the supported strings, see the filter fields section above.
ageGroupageGroup stringstring Fascia d'età dell'utente che ha effettuato l'acquisizione.The age group of the user who made the acquisition. Per un elenco delle stringhe supportate, vedi la sezione Campi di filtro più indietro.For a list of the supported strings, see the filter fields section above.
acquisitionTypeacquisitionType stringstring Tipo di acquisizione (gratis, a pagamento e così via).The type of acquisition (free, paid, and so on). Per un elenco delle stringhe supportate, vedi la sezione Campi di filtro più indietro.For a list of the supported strings, see the filter fields section above.
acquisitionQuantityacquisitionQuantity integerinteger Numero di acquisizioni avvenute.The number of acquisitions that occurred.

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": [
    {
      "date": "2015-01-02",
      "inAppProductId": "9NBLGGH3LHKL",
      "inAppProductName": "Contoso add-on 7",
      "applicationId": "9NBLGGGZ5QDR",
      "applicationName": "Contoso Demo",
      "deviceType": "Phone",
      "orderName": "",
      "storeClient": "Windows Phone Store (client)",
      "osVersion": "Windows Phone 8.1",
      "market": "GB",
      "gender": "m",
      "ageGroup": "50orover",
      "acquisitionType": "iap",
      "acquisitionQuantity": 1
    }
  ],
  "@nextLink": "inappacquisitions?applicationId=9NBLGGGZ5QDR&inAppProductId=&aggregationLevel=day&startDate=2015/01/01&endDate=2016/02/01&top=1&skip=1",
  "TotalCount": 33677
}