La versione 1 dell'API di dati di Google Analytics ti consente di generare tabelle pivot. Le tabelle pivot sono uno strumento di riepilogo dei dati che consente di visualizzare i dati riorganizzando le informazioni nella tabella tramite il pivot (rotazione) dei 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 sulle sessioni in base al browser, con le dimensioni Paese e Lingua selezionate come pivot aggiuntivi.
Funzionalità condivise con i report principali
Le richieste di report pivot hanno la stessa semantica delle richieste di report di base per molte funzionalità condivise. Ad esempio, la paginazione, i filtri delle dimensioni e le proprietà dell'utente si comportano allo stesso modo nei report pivot come nei report principali. Questa guida si concentra sulle funzionalità di generazione di report pivot. Per familiarizzare con la funzionalità di reporting di base della versione 1 dell'API Data, consulta la guida alle nozioni di base sul reporting e la guida ai casi d'uso avanzati.
Metodi di generazione di report pivot
La versione 1 dell'API Data supporta la funzionalità di pivot nei seguenti metodi di generazione di report:
runPivotReport Questo metodo restituisce un report pivot personalizzato contenente i dati sugli eventi di Google Analytics. Ogni tabella pivot descrive le righe e le colonne 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à report
Tutti i metodi dell'API di dati v1 richiedono che l'identificatore della proprietà Google Analytics
venga specificato all'interno di un percorso della richiesta dell'URL sotto forma di
properties/GA_PROPERTY_ID, ad esempio:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport
Il report risultante verrà generato in base ai dati sugli eventi di Google Analytics raccolti nella proprietà Google Analytics specificata.
Se utilizzi una delle librerie client dell'API Data, non è necessario manipolare manualmente il percorso dell'URL della richiesta. La maggior parte dei client API fornisce un parametro property che prevede una stringa nel formato properties/GA_PROPERTY_ID. Consulta la guida rapida per esempi di utilizzo delle librerie client.
Richiesta di report pivot
Per creare una richiesta con una tabella pivot, utilizza il metodo runPivotReport o il metodo batchRunPivotReports.
Per richiedere dati 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 dimensions.
- Almeno una voce valida nel campo metriche.
- Almeno due voci pivot valide nel campo pivots.
Ecco una richiesta di esempio con i campi consigliati:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_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 dei report. Ogni Pivot descrive le righe e le colonne delle dimensioni visibili nella risposta del report.
La versione 1 dell'API Data supporta più pivot,a condizione che 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, con pivot sulla dimensione browser. Tieni presente che la query utilizza il campo orderBys per l'ordinamento e i campi limit e offset per implementare la paginazione.
"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 per il tuo sito web o la 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 dimensions
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 sarà visibile in un report se non viene utilizzata in nessun pivot di una query pivot. Non tutte le dimensioni devono essere presenti nel fieldNames di un pivot. Le dimensioni possono essere utilizzate esclusivamente nei filtri e non nel
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 tuo sito web o la tua app. In una richiesta di report, puoi specificare una o più metriche. Consulta la sezione Metriche API per un elenco completo dei nomi delle metriche API disponibili per essere specificati nelle richieste.
Nelle richieste di report pivot, le metriche vengono definite utilizzando il campo metrics del corpo della richiesta, che è simile ai metodi di generazione di report di base.
Un esempio riportato di seguito specifica il conteggio delle sessioni da utilizzare come valore della metrica in un report:
"metrics": [
{
"name": "sessions"
}
],
Aggregazioni di metriche
Utilizza il campo metricAggregations di un oggetto Pivot per calcolare i valori delle metriche aggregate per ogni pivot.
Le aggregazioni verranno calcolate solo se il campo metricAggregations viene 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 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 di base, le richieste pivot ti consentono di specificare i campi limit e offset nell'oggetto Pivot per implementare la paginazione.
Le impostazioni di paginazione vengono applicate a ogni pivot singolarmente.
Il campo limit è obbligatorio per ogni oggetto Pivot per limitare la cardinalità del report.
La versione 1 dell'API Data 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 cinque dimensioni language successive con un offset di 10:
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
Filtri
Analogamente alla funzionalità Report di base, è necessario utilizzare un filtro delle dimensioni basato sulla richiesta se si vuole applicare il filtro delle dimensioni in una richiesta di report pivot.
Ordinamento
Il comportamento di ordinamento delle query dei report pivot può essere controllato singolarmente per ogni pivot 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 e 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 di pivot che esegue il pivot del report in base alla dimensione browser, ordinando i risultati in base alla metrica sessions in ordine decrescente.
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Report Response
La risposta del report pivot di una richiesta dell'API del report pivot è costituita principalmente da intestazioni e righe.
Intestazioni della risposta
L'intestazione del report pivot è composta da PivotHeaders, DimensionHeaders e MetricHeaders, che elencano le colonne nel report pivot.
Ad esempio, un report con le dimensioni pivot browser, country e language
e la metrica sessions produrrà intestazioni come questa:
{
"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 ciascun componente della risposta del report pivot nel rendering del report pivot:
Righe di risposta
La risposta del report pivot dei metodi runPivotReport e batchRunPivotReports è diversa da una risposta per i metodi di generazione di report di base 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 completa della tabella.
Di seguito è riportato un frammento della risposta di 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
Consulta la guida rapida per una spiegazione su come installare e configurare le librerie client.
Gli esempi riportati di seguito utilizzano la libreria client per eseguire una query pivot al fine di creare un report sul conteggio delle sessioni per paese, con pivot per la dimensione del browser.
PHP
use Google\Analytics\Data\V1beta\Client\BetaAnalyticsDataClient; use Google\Analytics\Data\V1beta\DateRange; use Google\Analytics\Data\V1beta\Dimension; use Google\Analytics\Data\V1beta\Metric; use Google\Analytics\Data\V1beta\OrderBy; use Google\Analytics\Data\V1beta\OrderBy\DimensionOrderBy; use Google\Analytics\Data\V1beta\OrderBy\MetricOrderBy; use Google\Analytics\Data\V1beta\Pivot; use Google\Analytics\Data\V1beta\RunPivotReportRequest; use Google\Analytics\Data\V1beta\RunPivotReportResponse; /** * Runs a pivot query to build a report of session counts by country, * pivoted by the browser dimension. * @param string $propertyId Your GA-4 Property ID */ function run_pivot_report(string $propertyId) { // Create an instance of the Google Analytics Data API client library. $client = new BetaAnalyticsDataClient(); // Make an API call. $request = (new RunPivotReportRequest()) ->setProperty('properties/' . $propertyId) ->setDateRanges([new DateRange([ 'start_date' => '2021-01-01', 'end_date' => '2021-01-30', ]), ]) ->setPivots([ new Pivot([ 'field_names' => ['country'], 'limit' => 250, 'order_bys' => [new OrderBy([ 'dimension' => new DimensionOrderBy([ 'dimension_name' => 'country', ]), ])], ]), new Pivot([ 'field_names' => ['browser'], 'offset' => 3, 'limit' => 3, 'order_bys' => [new OrderBy([ 'metric' => new MetricOrderBy([ 'metric_name' => 'sessions', ]), 'desc' => true, ])], ]), ]) ->setMetrics([new Metric(['name' => 'sessions'])]) ->setDimensions([ new Dimension(['name' => 'country']), new Dimension(['name' => 'browser']), ]); $response = $client->runPivotReport($request); printPivotReportResponse($response); } /** * Print results of a runPivotReport call. * @param RunPivotReportResponse $response */ function printPivotReportResponse(RunPivotReportResponse $response) { print 'Report result: ' . PHP_EOL; foreach ($response->getRows() as $row) { printf( '%s %s' . PHP_EOL, $row->getDimensionValues()[0]->getValue(), $row->getMetricValues()[0]->getValue() ); } }
Python
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)
Node.js
// TODO(developer): Uncomment this variable and replace with your // Google Analytics 4 property ID before running the sample. // propertyId = 'YOUR-GA4-PROPERTY-ID'; // Imports the Google Analytics Data API client library. const {BetaAnalyticsDataClient} = require('@google-analytics/data'); // Initialize client that will be used to send requests. This client only // needs to be created once, and can be reused for multiple requests. const analyticsDataClient = new BetaAnalyticsDataClient(); // Runs a pivot query to build a report of session counts by country, pivoted by the browser dimension. async function runPivotReport() { const [response] = await analyticsDataClient.runPivotReport({ property: `properties/${propertyId}`, dateRanges: [ { startDate: '2021-01-01', endDate: '2021-01-30', }, ], pivots: [ { fieldNames: ['country'], limit: 250, orderBys: [ { dimension: { dimensionName: 'country', }, }, ], }, { fieldNames: ['browser'], offset: 3, limit: 3, orderBys: [ { metric: { metricName: 'sessions', }, desc: true, }, ], }, ], metrics: [ { name: 'sessions', }, ], dimensions: [ { name: 'country', }, { name: 'browser', }, ], }); printPivotReportResponse(response); } runPivotReport(); // Prints results of a runReport call. function printPivotReportResponse(response) { console.log('Report result:'); response.rows.forEach(row => { row.dimensionValues.forEach(dimensionValue => { console.log(dimensionValue.value); }); row.metricValues.forEach(metricValue => { console.log(metricValue.value); }); }); }
Applicazione demo
Consulta l'applicazione di demo del report pivot dell'API Google Analytics v1 per un esempio di come creare e visualizzare un report pivot utilizzando JavaScript.