Questo documento fornisce il riferimento completo sia per le query sia per le risposte per l'API di reporting Canalizzazioni multicanale.
Introduzione
L'API di reporting Canalizzazioni multicanale ti consente di richiedere i dati del report Canalizzazioni multicanale di Google Analytics. Ogni report è costituito da statistiche ricavate dai dati che il codice di monitoraggio restituisce ad Analytics, organizzate come dimensioni e metriche. Scegliendo le tue combinazioni di dimensioni e metriche, puoi utilizzare l'API di reporting per creare report personalizzati in base alle tue specifiche.
L'API contiene un unico metodo che richiede i dati del report: report.get. Con questo metodo, devi fornire l'ID tabella corrispondente alla vista (profilo) per la quale vuoi recuperare i dati. Inoltre, devi specificare quanto segue:
- Una combinazione di dimensioni e metriche.
- Un intervallo di date.
- Un insieme di parametri di opzione che controllano quali dati vengono restituiti
L'API rende disponibile il metodo report.get su un endpoint REST: https://www.googleapis.com/analytics/v3/data/mcf. La seguente sezione mostra una richiesta di esempio e descrive ciascuno dei parametri.
Richiesta
L'API fornisce un singolo metodo per richiedere i dati:
analytics.data.mcf.get()
L'API può essere eseguita anche come endpoint REST:
Authorization: Bearer {oauth2-token} GET https://www.googleapis.com/analytics/v3/data/mcf ?ids=ga:12345 &metrics=mcf:totalConversions,mcf:totalConversionValue &start-date=2011-10-01 &end-date=2011-10-31
Ogni parametro di query dell'URL specifica un parametro di query dell'API che deve essere codificato nell'URL.
Tutte le richieste all'API Multi-ChannelFunnel Reporting devono essere autorizzate, preferibilmente tramite OAuth 2.0.
Riepilogo dei parametri di query
La seguente tabella riassume tutti i parametri di query accettati dall'API di reporting delle canalizzazioni multicanale. Fai clic sul nome di ciascun parametro per una descrizione dettagliata.
| Nome | Valore | Obbligatorio | Riepilogo |
|---|---|---|---|
ids |
string |
yes | L'ID tabella univoco nel formato ga:XXXX, dove XXXX è l'ID vista (profilo) di Analytics per cui la query recupererà i dati. |
start-date |
string |
yes |
Data di inizio per il recupero dei dati di Analytics. Le richieste possono specificare una data di inizio nel formato YYYY-MM-DD o come data relativa (ad es. today, yesterday o
NdaysAgo, dove N è un numero intero positivo).
|
end-date |
string |
yes |
Data di fine per il recupero dei dati di Analytics. La richiesta può specificare una data di fine nel formato YYYY-MM-DD o come data relativa (ad es.
today, yesterday o NdaysAgo
dove N è un numero intero positivo).
|
metrics |
string |
yes | Un elenco di metriche separate da virgole, come
mcf:totalConversions,mcf:totalConversionValue.
Una query valida deve specificare almeno una metrica. |
dimensions |
string |
no | Un elenco di dimensioni separate da virgole per il report Canalizzazioni multicanale,
ad esempio mcf:source,mcf:keyword. |
sort |
string |
no | Un elenco di dimensioni e metriche separate da virgole che indicano l'ordinamento e la direzione di ordinamento dei dati restituiti. |
filters |
string |
no | Filtri di dimensioni o metriche che limitano i dati restituiti per la tua richiesta. |
samplingLevel |
string |
no | Il livello di campionamento desiderato. Valori consentiti:
|
start-index |
integer |
no | La prima riga di dati da recuperare, a partire da 1.
Utilizza questo parametro come meccanismo di impaginazione insieme al parametro max-results. |
max-results |
integer |
no | Il numero massimo di righe da includere nella risposta. |
Dettagli parametro di query
ids
ids=ga:12345
ga: con l'ID vista (profilo) del report. Puoi recuperare l'ID vista (profilo) per il report utilizzando il metodo analytics.management.profiles.list, che fornisce il valore id nella risorsa Vista (profilo) nell'
API Google Analytics Management.
data di inizio
start-date=2011-10-01
start-date e end-date nella richiesta, il server restituisce un errore.
I valori di data possono riferirsi a una data specifica utilizzando il pattern
YYYY-MM-DD o relativo utilizzando today,
yesterday o il pattern NdaysAgo.
I valori devono corrispondere a
[0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo).
start-date valido è 2011-01-01.
Non esiste una limitazione di limite massimo per un start-date.Esempio di intervallo di date per gli ultimi 7 giorni (a partire da ieri) utilizzando date relative:
&start-date=7daysAgo &end-date=yesterday
data di fine
end-date=2011-10-31
start-date e end-date nella richiesta, il server restituisce un errore.
I valori di data possono riferirsi a una data specifica utilizzando il pattern
YYYY-MM-DD o relativo utilizzando today,
yesterday o il pattern NdaysAgo.
I valori devono corrispondere a
[0-9]{4}-[0-9]{2}-[0-9]{2}|today|yesterday|[0-9]+(daysAgo).
end-date valido è
2005-01-01. Non esiste una limitazione di limite superiore per un end-date. Esempio di intervallo di date per gli ultimi 10 giorni (a partire da oggi) utilizzando date relative:
&start-date=9daysAgo &end-date=today
dimensioni
dimensions=mcf:source,mcf:keyword
Il parametro delle dimensioni definisce le chiavi principali dei dati per il report Canalizzazioni multicanale, ad esempio mcf:source o mcf:medium.
Utilizza le dimensioni per segmentare le metriche di conversione. Ad esempio, anche se puoi richiedere il numero totale di conversioni sul tuo sito, potrebbe essere più interessante chiedere il numero di conversioni segmentate per mezzo.
In questo caso, vedrai il numero di conversioni da ricerca organica, referral, email e così via.
Quando utilizzi dimensions in una richiesta di dati, tieni presenti i seguenti vincoli:
- Puoi fornire un massimo di 7 dimensioni per qualsiasi query.
- Non puoi inviare una query composta solo da dimensioni: devi combinare eventuali dimensioni richieste con almeno una metrica.
Valori non disponibili
Quando non è possibile determinare il valore della dimensione, Analytics utilizza la stringa speciale (not set).
metrics
metrics=mcf:totalConversions,mcf:totalConversionValue
Le statistiche aggregate relative all'attività degli utenti sul tuo sito, ad esempio il conteggio totale delle conversioni o il valore di conversione totale.
Se una query non contiene alcun parametro dimensions, le metriche restituite forniscono valori aggregati per l'intervallo di date richiesto, come il valore di conversione totale complessivo. Tuttavia, quando vengono richieste le dimensioni, i valori vengono segmentati per valore di dimensione.
Ad esempio, mcf:totalConversions richiesto con
mcf:source restituisce le conversioni totali per origine.
Quando richiedi le metriche, tieni presente quanto segue:
- Qualsiasi richiesta deve fornire almeno una metrica; una richiesta non può essere composta solo da dimensioni.
- Puoi fornire un massimo di 10 metriche per qualsiasi query.
ordinare
sort=mcf:source,mcf:medium
Un elenco di metriche e dimensioni che indicano l'ordinamento e la direzione di ordinamento dei dati restituiti.
- L'ordine di ordinamento è specificato in base all'ordine da sinistra a destra delle metriche e delle dimensioni elencate.
- Per impostazione predefinita, la direction di ordinamento è crescente e può essere
modificata in decrescente utilizzando un segno meno (
-) come prefisso nel campo richiesto.
L'ordinamento dei risultati di una query ti consente di porre diverse domande sui dati. Ad esempio, per rispondere alla domanda "Quali sono le mie principali sorgenti di conversione e tramite quali mezzi?"
puoi creare una query con il seguente parametro. Ordina prima per mcf:source e poi per mcf:medium, entrambi in ordine crescente:
sort=mcf:source,mcf:medium
Per rispondere alla domanda correlata "Quali sono i miei principali mezzi di conversione
e da quali sorgenti?", puoi creare una query con il
seguente parametro. Ordina prima per mcf:medium e poi per mcf:source, entrambi in ordine crescente:
sort=mcf:medium,mcf:source
Quando utilizzi il parametro sort, tieni presente quanto segue:
- Ordina solo per dimensioni o valori delle metriche utilizzati nei parametri
dimensionsometrics. Se la richiesta viene ordinata in base a un campo non indicato nel parametro delle dimensioni o delle metriche, verrà visualizzato un errore. - Per impostazione predefinita, le stringhe sono ordinate in ordine alfabetico crescente nelle impostazioni internazionali en-US.
- Per impostazione predefinita, i numeri sono ordinati in ordine numerico crescente.
- Per impostazione predefinita, le date sono ordinate in ordine crescente in base alla data.
filtri
filters=mcf:medium%3D%3Dreferral
Il parametro della stringa di query filters limita i dati restituiti dalla richiesta. Per utilizzare il parametro filters, specifica una dimensione o una metrica in base alla quale filtrare, seguita dall'espressione di filtro. Ad esempio, la seguente query richiede mcf:totalConversions e mcf:source per la vista (profilo) 12134, dove la dimensione mcf:medium è la stringa referral:
https://www.googleapis.com/analytics/v3/data/mcf ?ids=mcf:12134 &dimensions=mcf:source &metrics=mcf:totalConversions &filters=mcf:medium%3D%3Dreferral &start-date=2011-10-01 &end-date=2011-10-31
Per maggiori dettagli, consulta Riferimento API di reporting principale.
samplingLevel
samplingLevel=DEFAULT
DEFAULT: restituisce la risposta con una dimensione del campione che bilancia velocità e precisione.FASTER: restituisce una risposta rapida con un campione di dimensioni inferiori.HIGHER_PRECISION: restituisce una risposta più accurata utilizzando un campione di grandi dimensioni, ma ciò potrebbe rallentare la risposta.
DEFAULT.max-results
max-results=100
Numero massimo di righe da includere in questa risposta. Puoi utilizzarla in combinazione con start-index per recuperare un sottoinsieme di elementi o utilizzarla da sola per limitare il numero di elementi restituiti, a partire dal primo.
Se max-results non viene fornito, la query restituisce
il massimo predefinito di 1000 righe.
L'API di reporting delle canalizzazioni multicanale restituisce un massimo di 10.000 righe per richiesta, indipendentemente da quante ne richiedi. Può anche restituire meno righe di quelle richieste, se il numero di segmenti di dimensione non è quello previsto. Ad esempio, sono disponibili meno di 300
valori possibili per mcf:medium, pertanto quando segmenti solo
in base al mezzo, non puoi ottenere più di 300 righe, anche se
imposti un valore più alto di max-results.
Risposta
Se l'esito è positivo, questa richiesta restituisce un corpo della risposta con la struttura JSON definita di seguito.
Nota: il termine "risultati" si riferisce all'intero insieme di righe che corrispondono alla query, mentre "risposta" si riferisce all'insieme di righe restituite nella pagina dei risultati corrente. Possono essere diversi se il numero totale di risultati è superiore alle dimensioni di pagina della risposta corrente, come spiegato in itemsPerPage.
Formato della risposta
{
"kind": "analytics#mcfData",
"id": string,
"query": {
"start-date": string,
"end-date": string,
"ids": string,
"dimensions": [
string
],
"metrics": [
string
],
"sort": [
string
],
"filters": string,
"samplingLevel": string,
"start-index": integer,
"max-results": integer
},
"itemsPerPage": integer,
"totalResults": integer,
"selfLink": string,
"previousLink": string,
"nextLink": string,
"profileInfo": {
"profileId": string,
"accountId": string,
"webPropertyId": string,
"internalWebPropertyId": string,
"profileName": string,
"tableId": string
},
"containsSampledData": boolean,
"sampleSize": string,
"sampleSpace": string,
"columnHeaders": [
{
"name": string,
"columnType": string,
"dataType": string
}
],
"totalsForAllResults": [
{
metricName: string,
...
}
]
"rows": [
[
McfData.Rows
]
],
}
Campi risposta
Le proprietà della struttura del corpo della risposta sono definite come segue:
| Nome proprietà | Valore | Descrizione |
|---|---|---|
kind |
string |
Tipo di risorsa. Il valore è "analytics#mcfData". |
id |
string |
Un ID per questa risposta dati. |
query |
object |
Questo oggetto contiene tutti i valori passati come parametri alla query. Il significato di ogni campo è spiegato nella descrizione del parametro di query corrispondente. |
query.start-date |
string |
Data di inizio. |
query.end-date |
string |
Data di fine. |
query.ids |
string |
ID tabella univoco. |
query.dimensions[] |
list |
Elenco delle dimensioni di analisi. |
query.metrics[] |
list |
Elenco delle metriche di analisi. |
query.sort[] |
list |
Elenco di metriche o dimensioni in base alle quali sono ordinati i dati. |
query.filters |
string |
Elenco separato da virgole di filtri di metriche o dimensioni. |
query.samplingLevel |
string |
Requested sampling level. |
query.start-index |
integer |
L'indice iniziale di righe. Il valore predefinito è 1. |
query.max-results |
integer |
Numero massimo di risultati per pagina. |
startIndex |
integer |
L'indice iniziale delle righe specificate dal
parametro di query start-index. Il valore predefinito è 1. |
itemsPerPage |
integer |
Il numero massimo di righe che la risposta può contenere, indipendentemente dal numero effettivo di righe restituite. Se
viene specificato il parametro di query max-results,
il valore di itemsPerPage è il minore tra max-results
o 10.000. Il valore predefinito di itemsPerPage è 1000.
|
totalResults |
integer |
Il numero totale di righe nel risultato della query, indipendentemente dal numero di righe restituite nella risposta. Per le query che
generano un numero elevato di righe,
il valore totalResults può essere maggiore di
itemsPerPage.
Per ulteriori spiegazioni su totalResults e itemsPerPage per le query di grandi dimensioni, consulta la sezione Paging.
|
selfLink |
string |
Link a questa pagina di risultati per questa query sui dati. |
previousLink |
string |
Link alla pagina precedente dei risultati per questa query sui dati. |
nextLink |
string |
Link alla pagina successiva dei risultati per questa query sui dati. |
profileInfo |
object |
Informazioni sulla vista (profilo) per cui sono stati richiesti i dati. I dati delle visualizzazioni (profilo) sono disponibili tramite l'API di gestione di Google Analytics. |
profileInfo.profileId |
string |
Visualizza l'ID (profilo), ad esempio 1174. |
profileInfo.accountId |
string |
ID account a cui appartiene questa vista (profilo),
ad esempio 30481. |
profileInfo.webPropertyId |
string |
ID proprietà web a cui appartiene questa vista (profilo), ad esempio UA-30481-1. |
profileInfo.internalWebPropertyId |
string |
L'ID interno della proprietà web a cui appartiene questa vista (profilo),
ad esempio UA-30481-1. |
profileInfo.profileName |
string |
Nome della vista (profilo). |
profileInfo.tableId |
string |
ID tabella della vista (profilo), composto da "ga:" seguito dall'ID vista (profilo). |
containsSampledData |
boolean |
True se la risposta contiene dati campionati. |
sampleSize |
string |
Il numero di campioni utilizzati per calcolare i dati campionati. |
sampleSpace |
string |
La dimensione totale dello spazio di campionamento. Indica la dimensione totale dello spazio di esempio disponibile da cui sono stati selezionati gli esempi. |
columnHeaders[] |
list |
Intestazioni di colonna che elencano i nomi delle dimensioni seguiti dai nomi delle metriche. L'ordine di dimensioni e metriche è lo stesso specificato nella richiesta tramite i parametri metrics e dimensions. Il numero di intestazioni corrisponde al numero di dimensioni e al numero di metriche. |
columnHeaders[].name |
string |
Nome della dimensione o metrica. |
columnHeaders[].columnType |
string |
Tipo di colonna. Può essere "DIMENSION" o "METRIC". |
columnHeaders[].dataType |
string |
Tipo di dati. Le intestazioni di colonna delle dimensioni hanno solo
"STRING" o "MCF_SEQUENCE" come tipo di dati.
Le intestazioni di colonna delle metriche contengono tipi di dati per i valori delle metriche come
"INTEGER", "DOUBLE", "CURRENCY"
e così via. |
totalsForAllResults |
object |
Valori totali delle metriche richieste come coppie chiave-valore di nomi e valori delle metriche. L'ordine dei totali delle metriche corrisponde a quello delle metriche specificato nella richiesta. |
rows[] |
list |
Righe di dati del report, in cui ogni riga contiene un elenco di Un oggetto Un elemento
{
"primitiveValue": "2183"
}
Un
{
"conversionPathValue": [
{
"interactionType" : "CLICK",
"nodeValue" : "google"
},
{
"interactionType" : "CLICK",
"nodeValue" : "google"
}
]
}
|
Codici di errore
L'API di reporting Canalizzazioni multicanale restituisce un codice di stato HTTP 200
se una richiesta ha esito positivo. Se si verifica un errore durante l'elaborazione di una query, l'API restituisce un codice di errore e una descrizione.
Ogni applicazione che utilizza l'API Analytics deve implementare una logica di gestione degli errori adeguata. Per maggiori dettagli sui codici di errore e su come gestirli, leggi la
guida di riferimento alle risposte di errore.
Prova.
Utilizza Explorer API di seguito per chiamare questo metodo sui dati in tempo reale e visualizzare la risposta.
Campionamento
Google Analytics calcola in tempo reale determinate combinazioni di dimensioni e metriche. Per restituire i dati in un tempo ragionevole, Google Analytics può elaborare solo un campione dei dati.
Puoi specificare il livello di campionamento da utilizzare per una richiesta impostando il parametro samplingLevel.
Se una risposta dell'API MCF Reporting contiene dati campionati, il campo di risposta containsSampledData sarà true.
Inoltre, due proprietà forniranno informazioni sul livello di campionamento per la query: sampleSize e sampleSpace.
Con questi due valori puoi calcolare la percentuale di sessioni utilizzate
per la query. Ad esempio, se sampleSize è 201,000
e sampleSpace è 220,000,il report si basa su (201.000 / 220.000) * 100 = 91,36% delle sessioni.
Per una descrizione generale del campionamento e del suo utilizzo in Google Analytics, consulta Campionamento.
Gestione dei risultati di dati di grandi dimensioni
Se prevedi che la query restituisca un set di risultati di grandi dimensioni, utilizza le linee guida riportate di seguito per ottimizzare la query API, evitare errori e ridurre al minimo il superamento della quota. Tieni presente che impostiamo una base di prestazioni per consentire un massimo di 7 dimensioni e 10 metriche in qualsiasi richiesta API. Sebbene l'elaborazione di alcune query che specificano un numero elevato di metriche e dimensioni possa richiedere più tempo di altre, limitare il numero di metriche richieste potrebbe non essere sufficiente per migliorare le prestazioni delle query. Puoi, invece, utilizzare le seguenti tecniche per ottenere i migliori risultati in termini di prestazioni.
Riduzione delle dimensioni per query
L'API consente di specificare fino a sette dimensioni in ogni richiesta. Molte volte Google Analytics deve calcolare all'istante i risultati di queste query complesse. Ciò può richiedere molto tempo, soprattutto se il numero di righe risultanti è elevato. Ad esempio, l'esecuzione di query per parole chiave per città e ora può corrispondere a milioni di righe di dati. Puoi migliorare le prestazioni riducendo il numero di righe che Google Analytics deve elaborare limitando il numero di dimensioni nella query.
Suddivisione della query per intervallo di date
Invece di sfogliare i risultati in base alla data di un lungo intervallo di date, valuta la possibilità di creare query separate per una settimana o anche un giorno alla volta. Ovviamente, per un set di dati di grandi dimensioni, anche una
richiesta di dati relativi a un solo giorno potrebbe restituire più di
max-results, nel qual caso non è possibile evitare il paging. In ogni caso, tuttavia, se il numero di righe corrispondenti per la query è maggiore di max-results, la suddivisione dell'intervallo di date potrebbe ridurre il tempo totale per recuperare i risultati. Questo approccio può migliorare le prestazioni sia per le query a thread singolo che per le query parallele.
Paging
La visualizzazione delle pagine dei risultati può essere un modo utile per suddividere grandi insiemi di risultati in blocchi gestibili. Il campo totalResults indica il numero di righe corrispondenti esistenti, mentre itemsPerPage fornisce il numero massimo di righe che possono essere restituite nel risultato.
Se è presente un rapporto elevato tra totalResults
e itemsPerPage, le singole query potrebbero
richiedere più tempo del necessario. Se hai bisogno solo di un numero limitato di righe, ad esempio a scopo di visualizzazione, potrebbe essere utile impostare un limite esplicito per le dimensioni delle risposte tramite il parametro max-results. Tuttavia, se l'applicazione deve elaborare un grande insieme di risultati nella sua interezza, richiedere il numero massimo di righe consentite può essere più efficiente.
Utilizzo di gzip
Un modo semplice e pratico per ridurre la larghezza di banda necessaria per ogni richiesta è abilitare la compressione gzip. Sebbene ciò richieda tempo di CPU aggiuntivo per decomprimere i risultati, il compromesso con i costi di rete di solito ne vale la pena. Per ricevere una risposta con codifica gzip devi fare due cose: impostare un'intestazione Accept-Encoding e modificare il tuo user agent in modo che contenga la stringa gzip.
Ecco un esempio di intestazioni HTTP formattate correttamente per abilitare la compressione gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)