Ottenere dati sul rendimento degli annunci

  • Articolo

Usare questo metodo nell'API di analisi di Microsoft Store per ottenere dati aggregati sulle prestazioni delle proprie applicazioni durante un determinato intervallo di date e altri filtri opzionali. Questo metodo restituisce i dati in formato JSON.

Questo metodo restituisce gli stessi dati forniti dal report sulle prestazioni pubblicitarie del 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.

Per ulteriori informazioni, vedere Accedere ai dati di analisi usando i servizi di Microsoft Store.

Richiedi

Sintassi della richiesta

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

Intestazione della richiesta

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

Parametri della richiesta

Per recuperare i dati sulle prestazioni degli annunci per un'app specifica, usare il parametro applicationId. Per recuperare i dati sulle prestazioni delle campagne pubblicitarie per tutte le app associate al proprio account sviluppatore, omettere il parametro applicationId.

Parametro Tipo Descrizione Richiesto
applicationId string ID dello Store dell'app per cui si desidera recuperare i dati sulle prestazioni degli annunci. No
startDate data Data di inizio dell'intervallo di date per i dati sulle prestazioni degli annunci da recuperare, nel formato AAAA/MM/GG. Il valore predefinito è la data corrente meno 30 giorni. No
endDate data Data di fine dell'intervallo di date per i dati sulle prestazioni degli annunci da recuperare, nel formato AAAA/MM/GG. Il valore predefinito è la data corrente meno un giorno. 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: giorno, settimana o mese. Se non è specificato, il valore predefinito è giorno. No
orderby string Istruzione che ordina i valori dei dati dei risultati. La sintassi è orderby=field [order],field [order],.... Il parametro field può essere una delle stringhe seguenti:
  • date
  • market
  • deviceType
  • adUnitId

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:

  • applicationId
  • applicationName
  • date
  • accountCurrencyCode
  • market
  • deviceType
  • adUnitName
  • adUnitId
  • pubCenterAppName
  • adProvider

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

 No

Campi filtro

Il parametro filter del corpo 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 è riportato un esempio di parametro filter:

  • filter=market eq 'US' and deviceType eq 'phone'

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

Campo Descrizione
market Stringa contenente il codice Paese ISO 3166 del mercato in cui sono stati recapitati gli annunci.
deviceType Una delle stringhe seguenti PC/Tablet o Phone.
adUnitId Stringa che specifica un ID unità annunci da applicare al filtro.
pubCenterAppName Stringa che specifica il nome pubCenter per l'app corrente da applicare al filtro.
adProvider Stringa che specifica un nome di provider annunci da applicare al filtro.
data Stringa che specifica una data in formato AAAA/MM/GG da applicare al filtro.

Esempio di richiesta

L'esempio seguente illustra diverse richieste di recupero dei dati sulle prestazioni degli annunci. Sostituire il valore applicationId con l'ID dello Store dell'app.

GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/adsperformance?applicationId=9NBLGGH4R315&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/adsperformance?applicationId=9NBLGGH4R315&startDate=8/1/2015&endDate=8/31/2015&skip=0&$filter=market eq 'US' and deviceType eq 'phone’ 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 dati aggregati sulle prestazioni degli annunci. Per ulteriori informazioni sui dati in ogni oggetto, vedere la sezione Valori delle prestazioni degli annunci 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 5 ma vi sono più di 5 elementi di dati per la query.
TotalCount int Numero totale di righe nei risultati di dati per la query.

Valori delle prestazioni degli annunci

Gli elementi nella matrice Value contengono i valori seguenti.

Valore Tipo Descrizione
data string Prima data dell'intervallo di date per i dati sulle prestazioni degli annunci. 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 ID dello Store dell'app per cui si stanno recuperando i dati sulle prestazioni degli annunci.
applicationName string Nome visualizzato dell'app.
adUnitId string ID dell'unità annunci.
adUnitName string Nome dell'unità annunci, come specificato dallo sviluppatore nel Centro per i partner.
adProvider string Nome del provider di annunci
deviceType string Tipo di dispositivo in cui sono stati recapitati gli annunci. Per un elenco delle stringhe supportate, vedere la sezione Campi filtro precedente.
market string Codice Paese ISO 3166 del mercato in cui sono stati recapitati gli annunci.
accountCurrencyCode string Codice valuta per l'account.
pubCenterAppName string Nome dell'app pubCenter associata all'app nel Centro per i partner.
adProviderRequests int Numero di richieste di annunci per il provider di annunci specificato.
impressions int Numero di impression degli annunci.
clicks int Numero di clic sugli annunci.
revenueInAccountCurrency number Ricavi, nella valuta del Paese o dell'area geografica dell'account.
requests int Numero di richieste di annunci.

Risposta di esempio

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

{
  "Value": [
    {
      "date": "2015-03-09",
      "applicationId": "9NBLGGH4R315",
      "applicationName": "Contoso Demo",
      "market": "US",
      "deviceType": "phone",
      "adUnitId":"10765920",
      "adUnitName":"TestAdUnit",
      "revenueInAccountCurrency": 10.0,
      "impressions": 1000,
      "requests": 10000,
      "clicks": 1,
      "accountCurrencyCode":"USD"
    },
    {
      "date": "2015-03-09",
      "applicationId": "9NBLGGH4R315",
      "applicationName": "Contoso Demo",
      "market": "US",
      "deviceType": "phone",
      "adUnitId":"10795110",
      "adUnitName":"TestAdUnit2",
      "revenueInAccountCurrency": 20.0,
      "impressions": 2000,
      "requests": 20000,
      "clicks": 3,
      "accountCurrencyCode":"USD"
    },
  ],
  "@nextLink": "adsperformance?applicationId=9NBLGGH4R315&aggregationLevel=week&startDate=2015/03/01&endDate=2016/02/01&top=2&skip=2",
  "TotalCount": 191753
}