L'API di dati 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 ruotando i dati in 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, 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à utente si comportano allo stesso modo nei report pivot e in quelli principali. Questa guida si concentra sulle funzionalità di reportistica pivot. Per acquisire familiarità con la funzionalità di reporting di base dell'API Data v1, leggi la guida alle nozioni di base del reporting e la guida ai casi d'uso avanzati.
Metodi di report in pivot
L'API Data v1 supporta la funzionalità di pivot nei seguenti metodi di generazione dei report:
runPivotReport Questo metodo restituisce un report pivot personalizzato contenente i dati sugli eventi di Google Analytics. Ogni pivot descrive le colonne e le righe delle dimensioni visibili nella risposta del report.
batchRunPivotReports. Questa è una versione batch del metodo
runPivotReportche consente di generare più report utilizzando una singola chiamata API.
Selezionare un'entità che genera report
Tutti i metodi dell'API di dati v1 richiedono che l'identificatore della proprietà Google Analytics
venga specificato all'interno di un percorso di richiesta URL nel formato
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 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 batchRunPivotReports.
Per richiedere i dati pivot, puoi creare un oggetto RunPivotReportRequest. Ti consigliamo di iniziare con questi parametri della richiesta:
- Una voce valida nel campo dateRanges.
- Almeno una voce valida nel campo dimensioni.
- 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 le tabelle pivot dei report. Ogni Pivot descrive le colonne e le righe delle dimensioni visibili nella risposta del report.
L'API Data v1 supporta più pivot a condizione che il prodotto del parametro limit per ogni pivot non superi 100.000.
Di seguito è riportato un snippet che mostra l'utilizzo di pivots per creare un report
dei conteggi delle sessioni per paese, con pivot in base alla dimensione browser. Nota come 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 evento 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 alcun
pivot di una query pivot. Non tutte le dimensioni devono essere presenti in fieldNames di una tabella pivot. Le dimensioni possono essere utilizzate esclusivamente nei filtri e non nel
fieldNames di qualsiasi tabella 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 che possono 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 Core Reporting.
L'esempio seguente specifica il conteggio delle sessioni da utilizzare come valore di una 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 è specificato in una richiesta.
Di seguito è riportato un 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 reportistica di base, le richieste pivot ti consentono di specificare i campi limite e offset nell'oggetto Pivot per implementare la paginazione.
Le impostazioni di paginazione vengono applicate a ogni tabella pivot singolarmente.
Il campo limit è obbligatorio per ogni oggetto Pivot per limitare la
cardinalità del report.
L'API Data v1 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 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à di reportistica di base, un filtro delle dimensioni ambito richiesta deve essere utilizzato se si desidera filtrare le dimensioni in una richiesta di report pivot.
Ordinamento
Il comportamento di ordinamento delle query dei report pivot può essere controllato per ogni pivot singolarmente 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 pivot che ruota il 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
}
]
}
Segnala risposta
La risposta del report pivot di una richiesta API di report pivot è costituita principalmente da un'intestazione e da righe.
Intestazioni della risposta
L'intestazione del report pivot è composta da PivotHeaders, DimensionHeaders e MetricHeaders, che elencano le colonne del report pivot.
Ad esempio, un report con le dimensioni pivot browser, country e language
e la metrica sessions genererà 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 ogni componente della risposta del report pivot nel rendering del report pivot:
Righe di risposta
La risposta del report pivot dei metodi runPivotReport e batchRunPivotReports differisce da una risposta per i metodi Core Reporting 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 di una 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 di come installare e configurare le librerie client.
Gli esempi seguenti utilizzano la libreria client per eseguire una query pivot per creare un report dei conteggi delle sessioni per paese, con pivot in base alla dimensione 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 demo del report pivot dell'API Google Analytics v1 per un esempio di come creare e visualizzare un report pivot utilizzando JavaScript.