L'API di dati di Google Analytics v1 consente di generare tabelle pivot. Le tabelle pivot sono uno strumento di riepilogo dei dati che visualizza i dati riorganizzando le informazioni nella tabella facendo ruotare i dati su una o più dimensioni.
Ad esempio, considera la seguente tabella di dati non elaborati:
Utilizzando questi dati è possibile creare una tabella pivot, suddividendo i dati delle sessioni per browser e selezionando le dimensioni per paese e lingua come pivot aggiuntivi.
Funzionalità condivise con i report principali
Le richieste di report pivot hanno la stessa semantica rispetto alle richieste dei report principali per molte caratteristiche condivise. Ad esempio, l'impaginazione, i filtri delle dimensioni e le proprietà utente, si comportano allo stesso modo nei report pivot e nei report principali. Questa guida si concentra sulle funzionalità dei report pivot. Per acquisire familiarità con la funzionalità di generazione di report di base dell'API di dati v1, leggi la guida di base sui report e la guida sui casi d'uso avanzati.
Metodi di reporting pivot
L'API di dati v1 supporta la funzionalità pivot nei seguenti metodi di generazione di report:
runPivotReport Questo metodo restituisce un report pivot personalizzato dei dati sugli eventi di Google Analytics. Ogni pivot descrive le colonne e le righe delle dimensioni visibili nella risposta del report.
batchRunPivotReports Si tratta di una versione batch del metodo
runPivotReportche consente di generare più report utilizzando una singola chiamata API.
Selezione di un'entità di reporting
Tutti i metodi dell'API di dati v1 richiedono che l'identificatore della proprietà Google Analytics 4 venga specificato all'interno di un percorso di richiesta URL nel formato properties/GA4_PROPERTY_ID, ad esempio:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
Il report risultante verrà generato in base ai dati sugli eventi di Google Analytics raccolti nella proprietà Google Analytics 4 specificata.
Se utilizzi una delle librerie client dell'API di dati, non è necessario modificare manualmente il percorso dell'URL della richiesta. La maggior parte dei client API fornisce un parametro property che prevede una stringa nella forma di properties/GA4_PROPERTY_ID. Consulta la guida rapida per alcuni esempi sull'utilizzo delle librerie client.
Richiesta report pivot
Per creare una richiesta con una tabella pivot, utilizza il metodo runPivotReport o il metodo batchRunPivotReports.
Per richiedere i dati sottoposti a pivot, puoi creare un oggetto RunPivotReportRequest. Ti consigliamo di iniziare con questi parametri di richiesta:
- Una voce valida nel campo dateRanges.
- Almeno una voce valida nel campo dimensioni.
- Almeno una voce valida nel campo metrics.
- Almeno due voci pivot valide nel campo pivot.
Ecco una richiesta di esempio con i campi consigliati:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
"dimensions": [
{ "name": "browser" },
{ "name": "country" },
{ "name": "language" }
],
"metrics": [{ "name": "sessions" }],
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5
},
{
"fieldNames": [
"country"
],
"limit": 250
},
{
"fieldNames": [
"language"
],
"limit": 15
}
]
}
Pivot
Utilizza gli oggetti Pivot nel campo pivot del corpo della richiesta per definire i pivot del report. Ogni Pivot descrive le colonne e le righe delle dimensioni visibili nella risposta del report.
L'API di dati v1 supporta più pivot purché il prodotto del parametro limit per ogni pivot non superi 100.000.
Di seguito è riportato uno snippet che mostra l'utilizzo di pivots per creare un report sul conteggio delle sessioni per paese, basato sulla dimensione browser. Nota come la query utilizza il campo orderBys per l'ordinamento e i campi limit e offset per implementare l'impaginazione.
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
...
Dimensioni
Le dimensioni descrivono e raggruppano i dati sugli eventi relativi al tuo sito web o alla tua app. La dimensione city, ad esempio, indica la città ("Parigi" o "New York") da cui ha avuto origine ogni evento. In una richiesta di report, puoi
specificare zero o più dimensioni.
Le dimensioni devono essere definite all'interno del campo dimensioni del corpo di una richiesta. Per essere visibili in un report, queste dimensioni devono essere elencate anche nel campo fieldNames di un oggetto Pivot.
Una dimensione non è visibile in un report se non viene utilizzata in alcun pivot di una query pivot. Non tutte le dimensioni devono essere presenti nel valore fieldNames di un pivot. Le dimensioni possono essere utilizzate esclusivamente nei filtri e non nell'elemento
fieldNames di qualsiasi pivot.
Di seguito è riportato uno snippet che mostra l'utilizzo dei campi dimension e fieldNames
per una tabella con pivot browser, country e language:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
},
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"language"
],
"limit": 10
}
],
Metriche
Le metriche sono misurazioni quantitative dei dati sugli eventi per il sito web o l'app. In una richiesta di report, puoi specificare una o più metriche. Consulta la pagina Metriche API per un elenco completo dei nomi delle metriche API disponibili da specificare nelle richieste.
Nelle richieste di report pivot, le metriche vengono definite utilizzando il campo metrics del corpo della richiesta, che è simile ai metodi di reporting principali.
Nell'esempio seguente è specificato il conteggio delle sessioni da utilizzare come valore di metrica in un report:
"metrics": [
{
"name": "sessions"
}
],
Aggregazioni di metriche
Utilizza il campo metricAggregations di un oggetto Pivot per calcolare i valori aggregati delle metriche per ogni pivot.
Le aggregazioni verranno calcolate solo se il campo metricAggregations è specificato in una richiesta.
Di seguito è riportato uno snippet di una query che richiede i totali per la dimensione pivot browser:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
Le metriche calcolate vengono restituite nel campo aggregates
dell'oggetto RunPivotReportResponse. Per le righe delle metriche aggregate, il campo dimensionValues
contiene un valore speciale di RESERVED_TOTAL, RESERVED_MAX o RESERVED_MIN.
"aggregates": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6"
}
]
},
....
}
Impaginazione
Analogamente ai metodi di generazione di report principali, le richieste pivot consentono di specificare i campi limite e offset nell'oggetto Pivot per implementare l'impaginazione.
Le impostazioni di impaginazione vengono applicate singolarmente a ogni pivot.
Il campo limit è obbligatorio per ogni oggetto Pivot al fine di limitare la cardinalità del report.
L'API di dati v1 supporta più pivot,purché il prodotto del parametro limit per ogni pivot non superi 100.000.
Di seguito è riportato uno snippet che mostra l'utilizzo dei campi offset e limit per recuperare le successive cinque dimensioni language con un offset di 10:
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
Applicazione dei filtri
Analogamente alla funzionalità di generazione di report principali, è necessario utilizzare un filtro dimensioni con ambito a livello di richiesta se si desidera applicare il filtro delle dimensioni in una richiesta di report pivot.
Ordinamento
Il comportamento di ordinamento delle query dei report pivot può essere controllato per ogni pivot individualmente utilizzando il campo orderBys di un oggetto Pivot, che contiene un elenco di oggetti OrderBy.
Ogni OrderBy può contenere uno dei seguenti elementi:
- DimensionOrderBy, ordina i risultati in base ai valori di una dimensione.
- MetricOrderBy, ordina i risultati in base ai valori di una metrica.
- PivotOrderBy, utilizzato nelle query pivot, che ordina i risultati in base ai valori di una metrica all'interno di un gruppo di colonne pivot.
Questo esempio mostra uno snippet per una definizione pivot che esegue il pivot del report sulla dimensione browser, ordinando i risultati in base alla metrica sessions in ordine decrescente.
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Segnala risposta
La risposta del report pivot di una richiesta API di un report pivot è principalmente un'intestazione e delle righe.
Intestazioni della risposta
L'intestazione del report pivot è composta da PivotHeaders, DimensionHeaders e MetricHeaders che elenca le colonne nel report pivot.
Ad esempio, un report con dimensioni pivot browser, country e language e la metrica sessions restituirà intestazioni simili alla seguente:
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Chrome"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "United States"
}
]
},
{
"dimensionValues": [
{
"value": "Canada"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "English"
}
]
},
{
"dimensionValues": [
{
"value": "French"
}
]
},
...
],
...
}
],
"dimensionHeaders": [
{
"name": "browser"
},
{
"name": "country"
},
{
"name": "language"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
...
}
Il grafico seguente illustra il ruolo di ogni componente della risposta del report pivot nel rendering del report pivot:
Righe risposta
La risposta del report pivot dei metodi runPivotReport e batchRunPivotReports è diversa da quella dei metodi di reporting principali come runReport e batchRunReports in quanto ogni riga di risposta del report pivot rappresenta una singola cella della tabella, mentre in un report normale una singola riga di risposta rappresenta una riga di tabella completa.
Di seguito è riportato un frammento di risposta a un report pivot per una query con le dimensioni pivot browser, country e language e la metrica sessions. Ogni cella del report pivot viene restituita singolarmente:
"rows": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "United States"
},
{
"value": "English"
}
],
"metricValues": [
{
"value": "1"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "Canada"
},
{
"value": "French"
}
],
"metricValues": [
{
"value": "3"
}
]
},
...
]
Questi dati corrispondono alle due celle evidenziate nella tabella seguente:
Librerie client
Per una spiegazione su come installare e configurare le librerie client, consulta la guida rapida.
Di seguito è riportato un esempio in cui viene utilizzata la libreria client Python che esegue una query pivot per creare un report sul conteggio delle sessioni per paese, basato sulla dimensione del browser.
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
DateRange,
Dimension,
Metric,
OrderBy,
Pivot,
RunPivotReportRequest,
)
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
run_pivot_report(property_id)
def run_pivot_report(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a pivot query to build a report of session counts by country,
pivoted by the browser dimension."""
client = BetaAnalyticsDataClient()
request = RunPivotReportRequest(
property=f"properties/{property_id}",
date_ranges=[DateRange(start_date="2021-01-01", end_date="2021-01-30")],
pivots=[
Pivot(
field_names=["country"],
limit=250,
order_bys=[
OrderBy(
dimension=OrderBy.DimensionOrderBy(dimension_name="country")
)
],
),
Pivot(
field_names=["browser"],
offset=3,
limit=3,
order_bys=[
OrderBy(
metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True
)
],
),
],
metrics=[Metric(name="sessions")],
dimensions=[Dimension(name="country"), Dimension(name="browser")],
)
response = client.run_pivot_report(request)
print_run_pivot_report_response(response)
def print_run_pivot_report_response(response):
"""Prints results of a runPivotReport call."""
print("Report result:")
for row in response.rows:
for dimension_value in row.dimension_values:
print(dimension_value.value)
for metric_value in row.metric_values:
print(metric_value.value)
Applicazione demo
Consulta l'applicazione Demo report pivot v1 API Google Analytics per un esempio di come creare e visualizzare un report pivot utilizzando JavaScript.