La versione 1 dell'API di dati di Google Analytics consente di generare tabelle pivot. Pivot sono uno strumento di riepilogo dei dati che visualizzano i dati riorganizzando informazioni nella tabella ruotando i dati su uno o più dimensioni.
Considera ad esempio la seguente tabella di dati non elaborati:
Usando questi dati è possibile creare una tabella pivot, suddividendo dati sulle sessioni per browser, con le dimensioni Paese e Lingua selezionate pivot aggiuntivi.
Funzionalità condivise con i report principali
Le richieste di report pivot hanno la stessa semantica delle richieste di report principali per molte funzionalità condivise. Ad esempio, impaginazione, filtri delle dimensioni e Le proprietà funzionano allo stesso modo dei report principali nei report pivot. Questo è incentrata sulle funzionalità di reporting pivot. Per acquisire familiarità con il Core Funzionalità di generazione di report dell'API di dati v1, leggi la guida alle nozioni di base sui report, nonché una guida ai casi d'uso avanzati.
Metodi di reporting pivot
L'API di dati v1 supporta la funzionalità pivot nei seguenti metodi di generazione dei report:
runPivotReport Questo metodo restituisce un report pivot personalizzato dei dati sugli eventi di Google Analytics. Ciascuna la funzione pivot descrive le colonne e le righe delle dimensioni visibili nella risposta del report.
batchRunPivotReports Questo è una versione batch del metodo
runPivotReportche consente di generare più report con una singola chiamata API.
Selezione di un'entità segnalante
Tutti i metodi dell'API di dati v1 richiedono l'identificatore proprietà Google Analytics
all'interno di un percorso di 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 di dati, è possibile
non occorre manipolare manualmente il percorso dell'URL della richiesta. La maggior parte dei client API
fornisci un parametro property che prevede una stringa sotto forma di
properties/GA_PROPERTY_ID. Consulta la Guida rapida
per esempi di utilizzo delle librerie client.
Richiesta report pivot
Per creare una richiesta con una tabella pivot, utilizza il metodo runPivotReport o il batchRunPivotReports .
Per richiedere dati sottoposti a pivot, puoi creare una richiesta 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 pivots.
Ecco un esempio di richiesta 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 della richiesta
per definire i pivot del report. Ogni Pivot descrive la dimensione visibile
e righe e colonne nella risposta del report.
L'API di dati v1 supporta più pivot a condizione che il prodotto dell'attributo limit per ogni pivot non sia maggiore di 100.000.
Di seguito è riportato uno snippet che mostra l'utilizzo di pivots per creare un report di
numero di sessioni per paese, in base alla dimensione browser. Nota come
utilizza il campo orderBys per
ordinamento, il limite e
Campi 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
Dimensioni che descrivono e raggruppano i dati sugli eventi per
sito web o 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:
non devono specificare più
dimensioni.
Le dimensioni devono essere definite all'interno del
dimensioni
del corpo di una richiesta. Per essere visibili in un report, queste dimensioni devono anche
essere elencato nel campo fieldNames
di un oggetto Pivot.
Una dimensione non sarà visibile in un report se non viene utilizzata in un
pivot di una query pivot. Non tutte le dimensioni devono essere presenti in un
fieldNames. Le dimensioni possono essere utilizzate esclusivamente nei filtri e non nei
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 sul tuo sito web o sulla tua 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. che possono essere specificate nelle richieste.
Nelle richieste di report pivot, le metriche vengono definite utilizzando il campo metrics dell'
corpo della richiesta, che è simile ai metodi di reporting principali.
Un esempio riportato di seguito specifica il conteggio delle sessioni da utilizzare come valore della metrica in una report:
"metrics": [
{
"name": "sessions"
}
],
Aggregazioni di metriche
Utilizzare metricAggregations campo di un oggetto Pivot per calcolare la metrica aggregata per ogni pivot.
Le aggregazioni verranno calcolate solo se la metrica metricAggregations viene specificato in una richiesta.
Di seguito è riportato uno snippet di una query che richiede i totali per
browser dimensione pivot:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
Le metriche calcolate vengono restituite nei aggregati.
nel campo 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 principali per la generazione di report, le richieste pivot consentono
per specificare il limite
e offset nel
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 le
segnala la cardinalità.
L'API di dati v1 supporta più pivot a condizione che il prodotto limit
per ogni pivot non deve superare 100.000.
Di seguito è riportato uno snippet che mostra l'utilizzo dei campi offset e limit per
recupera le successive cinque dimensioni language con un offset pari a 10:
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
Filtri
In modo simile alla funzionalità di reporting principale, una filtro dimensione con ambito a livello di richiesta deve essere utilizzato se si desidera applicare il filtro delle dimensioni in un report pivot richiesta.
Ordinamento
Il comportamento di ordinamento delle query dei report pivot può essere controllato per ogni pivot singolarmente utilizzando il comando orderBys campo di un oggetto Pivot, che contiene un elenco di 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 in pivot query e ordina i risultati in base ai valori di una metrica in un gruppo di colonne pivot.
Questo esempio mostra uno snippet per una definizione pivot che esegue il pivot del report su
la 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 al report pivot di un pivot è principalmente un'intestazione e delle righe.
Intestazioni della risposta
L'intestazione del report pivot è composta da PivotHeaders, DimensionHeaders e MetricHeaders che elencano le colonne in un report pivot.
Ad esempio, un report con dimensioni pivot browser, country e language
e la metrica sessions restituirà intestazioni come queste:
{
"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 del report pivot. Risposta nel rendering del report pivot:
Righe di risposta
La risposta del report pivot di runPivotReport e batchRunPivotReports è diverso dalla risposta dei metodi principali di reporting come runReport e batchRunReports in quanto ogni riga di risposta del report pivot rappresenta una singola cella , mentre in un normale report una singola riga di risposta rappresenta una risposta dalla riga della tabella.
Di seguito è riportato un frammento di una risposta a un report pivot relativo a
query con le dimensioni pivot browser, country e language e
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 delle come installare e configurare le librerie client.
I seguenti esempi utilizzano la libreria client per eseguire una query pivot al fine di creare un report sul conteggio delle sessioni per paese, 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
Vedi la demo del report pivot v1 dell'API Google Analytics applicazione per un esempio di come creare e visualizzare un report pivot utilizzando JavaScript.