API Core Reporting - Guida di riferimento

Quando utilizzi dimensions in una richiesta di dati, tieni presente 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.
• È possibile eseguire query solo su determinate dimensioni nella stessa query. Utilizza lo strumento di combinazione valido nella pagina Riferimento dimensioni e metriche per scoprire quali dimensioni possono essere utilizzate insieme.

• 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.
• È possibile utilizzare insieme la maggior parte delle combinazioni di metriche di più categorie, a condizione che non vengano specificate dimensioni.
• Una metrica può essere utilizzata in combinazione con altre dimensioni o metriche, ma solo nei casi in cui per la metrica si applicano combinazioni valide. Per maggiori dettagli, consulta la pagina Riferimento per dimensioni e metriche.

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 i miei paesi principali e quali browser utilizzano maggiormente?" puoi creare una query con il seguente parametro. Ordina prima per ga:country e poi per ga:browser, entrambi in ordine crescente:

sort=ga:country,ga:browser

sort=ga:browser,ga:country

Quando utilizzi il parametro sort, tieni presente quanto segue:

• Ordina solo per dimensioni o valori delle metriche utilizzati nei parametri dimensions o metrics. 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.

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 ga:pageviews e ga:browser per la vista (profilo) 12134, dove la dimensione ga:browser inizia con la stringa Firefox:

https://www.googleapis.com/analytics/v3/data/ga
?ids=ga:12134
&dimensions=ga:browser
&metrics=ga:pageviews
&filters=ga:browser%3D~%5EFirefox
&start-date=2007-01-01
&end-date=2007-12-31

Le query filtrate limitano le righe che vengono o non vengono incluse nel risultato. Ogni riga nel risultato viene verificata in base al filtro: se il filtro corrisponde, la riga viene mantenuta e, in caso contrario, viene eliminata.

• Codifica URL: le librerie client dell'API di Google codificano automaticamente gli operatori di filtro.
• Filtro dimensioni: l'applicazione dei filtri avviene prima dell'aggregazione delle dimensioni, in modo che le metriche restituite rappresentino il totale solo per le dimensioni pertinenti. Nell'esempio riportato sopra, il numero di visualizzazioni di pagina corrisponde solo alle visualizzazioni di pagina in cui Firefox è il browser.
• Filtro delle metriche: l'applicazione di filtri in base alle metriche viene eseguita dopo l'aggregazione delle metriche.
• Combinazioni valide: puoi filtrare in base a una dimensione o una metrica che non fa parte della query, a condizione che tutte le dimensioni/metriche nella richiesta e il filtro siano combinazioni valide. Ad esempio, potresti voler eseguire una query per un elenco con date di visualizzazioni di pagina, filtrando in base a un browser specifico. Per ulteriori informazioni, consulta la documentazione di riferimento su dimensioni e metriche.

Sintassi dei filtri

Un singolo filtro utilizza il modulo:

ga:name operator expression

Con questa sintassi:

• name: il nome della dimensione o metrica in base a cui applicare il filtro. Ad esempio, ga:pageviews filtri per la metrica delle visualizzazioni di pagina.
• operator: definisce il tipo di corrispondenza del filtro da utilizzare. Gli operatori sono specifici per dimensioni o metriche.
• expression: indica i valori da includere o escludere dai risultati. Le espressioni utilizzano la sintassi delle espressioni regolari.

Filtra operatori

Esistono sei operatori di filtro per le dimensioni e sei per le metriche. Gli operatori devono essere codificati nell'URL per essere inclusi nelle stringhe di query dell'URL.

Suggerimento: utilizza Query Explorer nei feed di dati per progettare filtri che necessitano della codifica degli URL, poiché Query Explorer codifica automaticamente gli URL contenenti stringhe e spazi.

Filtra espressioni

Esistono un paio di regole importanti per le espressioni di filtro:

• Caratteri riservati agli URL: i caratteri come & devono essere codificati nell'URL normalmente.
• Caratteri riservati: il punto e virgola e la virgola devono essere preceduti da una barra rovesciata quando vengono visualizzati in un'espressione:
  • punto e virgola \;
  • virgola \,
• Espressioni regolari: puoi utilizzare anche espressioni regolari nelle espressioni di filtro utilizzando gli operatori =~ e !~. La loro sintassi è simile alle espressioni regolari Perl e prevedono queste regole aggiuntive:
  • Lunghezza massima di 128 caratteri: le espressioni regolari che superano i 128 caratteri generano un codice di stato 400 Bad Request restituito dal server.
  • Sensibilità alle maiuscole: la corrispondenza delle espressioni regolari non fa distinzione tra maiuscole e minuscole.

Combinazione di filtri

I filtri possono essere combinati utilizzando la logica booleana OR e AND. Ciò consente di estendere in modo efficace il limite di 128 caratteri di un'espressione di filtro.

OR

L'operatore OR viene definito utilizzando una virgola (,). Ha la precedenza sull'operatore AND e NON può essere utilizzato per combinare dimensioni e metriche nella stessa espressione.

E

L'operatore AND viene definito utilizzando un punto e virgola (;). È preceduto dall'operatore OR e può essere utilizzato per combinare dimensioni e metriche nella stessa espressione.

Per dettagli completi su come richiedere un segmento nell'API di reporting principale, consulta la Guida per lo sviluppo di segmenti.

Per una panoramica concettuale dei segmenti, consulta la documentazione relativa al riferimento sulle funzionalità dei segmenti e ai segmenti nel Centro assistenza.

Dimensioni e metriche consentite nei segmenti.
Non tutte le dimensioni e metriche possono essere utilizzate nei segmenti. Per esaminare le dimensioni e le metriche consentite nei segmenti, visita lo strumento di esplorazione di dimensioni e metriche.

• 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.

• json: restituisce la proprietà rows predefinita nella risposta, contenente un oggetto JSON.
• dataTable: restituisce una proprietà dataTable nella risposta, contenente un oggetto Tabella dati. Questo oggetto Data Table può essere utilizzato direttamente con le visualizzazioni dei grafici Google.

Specifica quali campi restituire in una risposta parziale. Se utilizzi solo un sottoinsieme dei campi nella risposta dell'API, puoi utilizzare il parametro fields per specificare quali campi includere.

Il formato del valore del parametro di richiesta dei campi si basa sulla sintassi XPath. La sintassi supportata è riassunta di seguito.

• Utilizza un elenco separato da virgole per selezionare più campi.
• Utilizza a/b per selezionare un campo b nidificato all'interno del campo a; utilizza a/b/c per selezionare un campo c nidificato all'interno di b.
• Utilizza un sottoselettore per richiedere un insieme di sottocampi specifici di array o oggetti inserendo espressioni tra parentesi "( )".
  Ad esempio: fields=columnHeaders(name,dataType) restituisce solo i campi name e dataType nell'array columnHeaders. Puoi anche specificare un singolo sottocampo, dove fields=columnHeader(name) equivale a fields=columnHeader/name.

Restituisce la risposta in un formato leggibile se true. Valore predefinito: false.

Consente di applicare le quote per utente da un'applicazione lato server anche quando l'indirizzo IP dell'utente è sconosciuto. Questo può accadere, ad esempio, con le applicazioni che eseguono cron job su App Engine per conto di un utente. Puoi scegliere qualsiasi stringa arbitraria che identifichi in modo univoco un utente, ma è limitata a 40 caratteri.

Questo sostituisce userIp se vengono forniti entrambi.