Ottenere i dati sulle prestazioni delle campagne
Usare questo metodo dell'API di analisi di Microsoft Store per ottenere un riepilogo aggregato dei dati delle prestazioni delle campagne pubblicitarie promozionali per le 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 campagne pubblicitarie del Centro per i partner. Per ulteriori informazioni sulle campagne pubblicitarie, vedere Creare una campagna pubblicitaria per l'app.
Per creare, aggiornare o recuperare i dettagli per le campagne pubblicitarie, è possibile usare i metodi di gestione delle campagne pubblicitarie nell'API delle promozioni di Microsoft Store.
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/promotion |
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 delle campagne pubblicitarie 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 delle campagne pubblicitarie. | No |
| startDate | data | Data di inizio dell'intervallo di date per i dati sulle prestazioni delle campagne pubblicitarie 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 delle campagne pubblicitarie 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. L'unico filtro supportato è campaignId. Ogni istruzione può usare gli operatori eq o ne e le istruzioni possono essere combinate mediante gli operatori and o or. Di seguito è riportato un esempio di parametro filter: filter=campaignId eq '100023'. |
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 relativi ai dati sulle prestazioni delle campagne pubblicitarie. La sintassi è orderby=field [order],field [order],.... Il parametro field può essere una delle stringhe seguenti:
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,campaignId |
No |
| groupby | string | Istruzione che applica l'aggregazione dei dati solo ai campi specificati. È possibile specificare i campi seguenti:
Il parametro groupby può essere usato con il parametro aggregationLevel. Ad esempio: &groupby=applicationId&aggregationLevel=week |
No |
Esempio di richiesta
L'esempio seguente illustra diverse richieste di recupero dei dati sulle prestazioni delle campagne pubblicitarie.
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/promotion?aggregationLevel=week&groupby=applicationId,campaignId,date HTTP/1.1
Authorization: Bearer <your access token>
GET https://manage.devcenter.microsoft.com/v1.0/my/analytics/promotion?applicationId=9NBLGGH0XK8Z&startDate=2015/1/20&endDate=2016/8/31&skip=0&filter=campaignId eq '31007388' 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 delle campagne pubblicitarie. Per ulteriori informazioni sui dati in ogni oggetto, vedere la sezione Oggetto prestazioni delle campagne 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. |
Oggetto prestazioni delle campagne
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 delle campagne pubblicitarie. 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 delle campagne pubblicitarie. |
| campaignId | string | ID della campagna pubblicitaria. |
| lineId | string | ID della riga di consegna della campagna pubblicitaria che ha generato questi dati sulle prestazioni. |
| currencyCode | string | Codice valuta del budget della campagna. |
| spend | string | Importo del budget speso per la campagna pubblicitaria. |
| impressions | long | Numero di impression degli annunci per la campagna. |
| installs | long | Numero di installazioni dell'app correlate alla campagna. |
| clicks | long | Numero di clic sugli annunci per la campagna. |
| iapInstalls | long | Numero di installazioni di componenti aggiuntivi (anche denominate acquisti in-app o IAP) relative alla campagna. |
| activeUsers | long | Numero di utenti che hanno fatto clic su un annuncio che fa parte della campagna e sono tornati all'app. |
Risposta di esempio
L'esempio seguente illustra un esempio di corpo della risposta JSON per questa richiesta.
{
"Value": [
{
"date": "2015-04-12",
"applicationId": "9WZDNCRFJ31Q",
"campaignId": "4568",
"lineId": "0001",
"currencyCode": "USD",
"spend": 700.6,
"impressions": 200,
"installs": 30,
"clicks": 8,
"iapInstalls": 0,
"activeUsers": 0
},
{
"date": "2015-05-12",
"applicationId": "9WZDNCRFJ31Q",
"campaignId": "1234",
"lineId": "0002",
"currencyCode": "USD",
"spend": 325.3,
"impressions": 20,
"installs": 2,
"clicks": 5,
"iapInstalls": 0,
"activeUsers": 0
}
],
"@nextLink": "promotion?applicationId=9NBLGGGZ5QDR&aggregationLevel=day&startDate=2015/1/20&endDate=2016/8/31&top=2&skip=2",
"TotalCount": 1917
}