Questo documento fornisce istruzioni su come eseguire la migrazione del codice esistente dall'API di reporting di Google Analytics v4 all'API di dati di Google Analytics v1 e fornisce una breve panoramica delle principali differenze tra le due API.
Perché devo eseguire la migrazione
Se la tua applicazione deve accedere ai dati di una proprietà Google Analytics 4, è necessario aggiornare il codice in modo che utilizzi l'API di dati v1, poiché l'API di reporting v4 può accedere solo alle proprietà create con Universal Analytics.
Prerequisiti
Acquisisci familiarità con le nozioni di base dell'API di dati v1 utilizzando la guida rapida.
Per iniziare
Per iniziare, prepara una proprietà Google Analytics 4, attivi l'API di dati v1 e poi configurerai una libreria client API adatta alla tua piattaforma.
Preparare una proprietà Google Analytics 4
Prima di iniziare a eseguire la migrazione del codice per supportare l'API di dati v1, devi eseguire la migrazione del sito web per utilizzare una proprietà Google Analytics 4. Non è possibile eseguire il backfill di una proprietà Google Analytics 4 con i dati storici di una proprietà Universal Analytics.
Abilita l'API
Fai clic su questo pulsante per abilitare automaticamente l'API di dati v1 nel progetto Google Cloud selezionato.
Attivare l'API di dati di Google Analytics v1Utilizzo di una libreria client
Installa una libreria client
Se utilizzi una libreria client, devi installare la libreria client dell'API di dati v1 per il tuo linguaggio di programmazione.
Java
Python
Node.js
.NET
PHP
Go
go get google.golang.org/genproto/googleapis/analytics/data/v1beta
Inizializzare una libreria client
Le librerie client dell'API di dati v1 sono state progettate per aiutarti a iniziare rapidamente. Per impostazione predefinita, le librerie client provano a trovare automaticamente le credenziali dell'account di servizio.
Un modo semplice per fornire le credenziali dell'account di servizio consiste nell'impostare la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS. Il client API utilizzerà il valore di questa variabile per trovare il file JSON della chiave dell'account di servizio.
Ad esempio, puoi impostare le credenziali dell'account di servizio eseguendo questo comando e utilizzando il percorso del file JSON dell'account di servizio:
export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
Di seguito sono riportati gli snippet di codice comunemente utilizzati per inizializzare le librerie client dell'API di dati v1.
Java
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
Python
# Using a default constructor instructs the client to use the credentials
# specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
client = BetaAnalyticsDataClient()
.NET
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
BetaAnalyticsDataClient client = BetaAnalyticsDataClient.Create();
PHP
// Using a default constructor instructs the client to use the credentials // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable. $client = new BetaAnalyticsDataClient();
Node.js
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
const analyticsDataClient = new BetaAnalyticsDataClient();
Anziché utilizzare una variabile di ambiente, è anche possibile passare le informazioni sulle credenziali a un'istanza del client API in modo esplicito durante l'inizializzazione. Di seguito sono riportati gli snippet utilizzati per inizializzare le librerie client dell'API di dati v1 inserendo le credenziali in modo esplicito nel codice.
Java
// Explicitly use service account credentials by specifying
// the private key file.
GoogleCredentials credentials =
GoogleCredentials.fromStream(new FileInputStream(credentialsJsonPath));
BetaAnalyticsDataSettings betaAnalyticsDataSettings =
BetaAnalyticsDataSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credentials))
.build();
try (BetaAnalyticsDataClient analyticsData =
BetaAnalyticsDataClient.create(betaAnalyticsDataSettings)) {
Python
# TODO(developer): Uncomment this variable and replace with a valid path to
# the credentials.json file for your service account downloaded from the
# Cloud Console.
# credentials_json_path = "/path/to/credentials.json"
# Explicitly use service account credentials by specifying
# the private key file.
client = BetaAnalyticsDataClient.from_service_account_json(credentials_json_path)
.NET
/**
* TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
* Otherwise, default service account credentials will be derived from
* the GOOGLE_APPLICATION_CREDENTIALS environment variable.
*/
// credentialsJsonPath = "/path/to/credentials.json";
// Explicitly use service account credentials by specifying
// the private key file.
BetaAnalyticsDataClient client = new BetaAnalyticsDataClientBuilder
{
CredentialsPath = credentialsJsonPath
}.Build();
PHP
/**
* @param string $credentialsJsonPath Valid path to the credentials.json file for your service
* account downloaded from the Cloud Console.
* Example: "/path/to/credentials.json"
*/
function client_from_json_credentials(string $credentialsJsonPath)
{
// Explicitly use service account credentials by specifying
// the private key file.
$client = new BetaAnalyticsDataClient([
'credentials' => $credentialsJsonPath
]);
return $client;
}
Node.js
/** TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
*/
// credentialsJsonPath = '/path/to/credentials.json';
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Explicitly use service account credentials by specifying
// the private key file.
const analyticsDataClient = new BetaAnalyticsDataClient({
keyFilename: credentialsJsonPath,
});
Mancato utilizzo di una libreria client
Se utilizzavi l'API di reporting v4 senza una libreria client e vuoi continuare a farlo con l'API di dati v1, puoi comunque utilizzare le tue credenziali.
Devi utilizzare il nuovo endpoint HTTP e il documento di rilevamento forniti dall'API di dati:
Se il tuo codice sfrutta un documento di rilevamento, devi aggiornarlo al documento di rilevamento fornito dall'API di dati v1:
Dopo aver aggiornato l'endpoint, dovrai acquisire familiarità con la nuova struttura e i nuovi concetti di richiesta dell'API di dati per aggiornare la query JSON.
Report principali
Metodi di reporting disponibili
L'API di reporting v4 offriva un singolo metodo batchGet per accedere alla sua funzionalità di reporting principale. L'API di dati v1 offre diversi metodi di reporting principali tra cui scegliere:
- runReport Questo metodo restituisce un report personalizzato dei dati sugli eventi di Google Analytics. Non supporta la funzionalità pivot ed è il metodo preferito per query dei report semplici.
- runPivotReport Questo metodo restituisce un report pivot personalizzato dei dati sugli eventi di Google Analytics. Analogamente ai pivot nell'API di reporting v4, ogni pivot descrive le colonne e le righe delle dimensioni visibili nella risposta del report.
- batchRunReports È una versione batch
del metodo
runReportche consente di generare più report utilizzando una singola chiamata API. - batchRunPivotReports È una versione batch del metodo
runPivotReportche consente di generare più report utilizzando una singola chiamata API.
Lo scopo di utilizzare diversi metodi di generazione di report è per lo più praticità, in quanto alcuni supportano funzionalità più complesse di altri (pivot, batch), ma condividono in altro modo una struttura di richiesta simile.
Modifiche allo schema API
Le funzionalità di generazione di report sia dell'API di reporting che dell'API di dati sono determinate principalmente dal loro schema, ovvero dimensioni e metriche supportate nelle query di reporting. Esistono differenze significative negli schemi delle API tra le due API, a causa delle differenze concettuali tra Universal Analytics e Google Analytics 4.
- Acquisisci familiarità con l'elenco attuale di dimensioni e metriche supportate dall'API di dati. Al momento, tutte le dimensioni e le metriche sono compatibili tra loro, pertanto non è necessario utilizzare lo strumento Esplorazione dimensioni e metriche per determinare le combinazioni compatibili. Questo comportamento cambierà in futuro.
- È possibile accedere alle dimensioni personalizzate in Google Analytics 4 utilizzando la sintassi delle dimensioni personalizzate dell'API di dati v1, che dovrebbe essere utilizzata al posto degli slot delle dimensioni ga:dimensionXX dell'API di reporting v4.
- Puoi accedere alle metriche personalizzate in Google Analytics 4 utilizzando la sintassi delle metriche personalizzate dell'API di dati v1, che dovrebbe essere utilizzata al posto degli slot delle metriche ga:metricXX dell'API di reporting v4.
- Alcune dimensioni e metriche presenti in Universal Analytics hanno un equivalente diretto in Google Analytics 4. Per saperne di più, consulta il grafico delle equivalenze dello schema delle API UA/GA4.
- I nomi di dimensioni e metriche non hanno più il prefisso
ga:in Google Analytics 4. - Alcune funzionalità presenti in Universal Analytics non sono ancora disponibili in GA4 (ad es. integrazione di Campaign Manager, DV360 e Search Ads 360). Una volta implementata questa funzionalità in Google Analytics 4, l'API di dati la supporterà, nuove dimensioni e metriche verranno aggiunte allo schema dell'API.
Entità
In Google Analytics 4 non viene introdotto il concetto di viste (profili) introdotto in Universal Analytics. Di conseguenza, non è presente alcun parametro viewId nelle richieste di report dell'API di dati v1. Devi invece specificare un ID proprietà numerico di Google Analytics 4
in un percorso dell'URL della richiesta quando chiami i metodi v1 dell'API di dati.
Questo comportamento è diverso dalla versione 4 dell'API di reporting, che si basa sugli ID vista (profilo) per identificare l'entità report.
API di dati v1
Nel caso dell'API di dati v1, nel percorso dell'URL deve essere specificato un ID proprietà numerico Google Analytics 4.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
API di reporting v4
L'API di reporting v4 richiede che nel corpo di una query di report venga specificato un ID vista (profilo) Universal Analytics.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
....
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.
Intervalli di date
Sia l'API di reporting v4 che l'API di dati v1 supportano più intervalli di date
specificati utilizzando il campo dateRanges in una richiesta di reporting. Entrambe le API condividono lo
stesso formato di input della data, accettando valori di data assoluti sotto forma di
YYYY-MM-DD o date relative come yesderday, today, 7daysAgo e così via.
Le richieste dell'API di dati v1 sono limitate a 4 intervalli di date, mentre l'API di reporting v4 consente 2 intervalli di date in una singola richiesta di report.
Ogni dateRange nell'API di dati v1 può avere un campo name facoltativo che
può essere utilizzato per fare riferimento all'intervallo di date corrispondente in una risposta.
Se non viene specificato name, il nome dell'intervallo di date viene generato automaticamente.
Se in una richiesta della versione 1 dell'API di dati vengono specificati più intervalli di date, a una risposta viene aggiunta automaticamente una nuova dimensione dateRange e il nome dell'intervallo di date viene utilizzato come valore di dimensione. Tieni presente che questo comportamento è diverso dalla versione 4 dell'API di reporting, che restituisce i dati per un intervallo di date come gruppo di valori delle metriche all'interno di ogni riga.
Richiesta API di dati v1
Per ogni valore dateRange in una richiesta viene utilizzato un campo name facoltativo.
Il nome di questo intervallo di date verrà utilizzato come valore della dimensione dateRange
nella risposta.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
"name": "year_ago"
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
"name": "current_year"
}
]
}
Risposta dell'API di dati v1
Nella risposta viene inclusa automaticamente una dimensione dateRange aggiuntiva.
Il valore della dimensione dateRange contiene il nome di un intervallo di date, che
proviene dal campo dateRange.name o viene generato automaticamente.
....
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "dateRange"
}
],
....
"rows": [
....
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "year_ago"
}
],
"metricValues": [
{
"value": "253286"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "current_year"
}
],
"metricValues": [
{
"value": "272582"
}
]
},
....
Richiesta API di reporting v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
]
}
]
}
Risposta dell'API di reporting v4
Nell'API di reporting v4, i valori per ogni intervallo di date sono raggruppati all'interno del
campo metrics:
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"253286"
]
},
{
"values": [
"272582"
]
}
]
},
Ordinamento
Il comportamento dell'ordine delle query dei report dell'API di dati v1 può essere controllato utilizzando il campo orderBys, simile al campo orderBys dell'API di reporting v4.
La specifica OrderBy è stata modificata nella versione 1 dell'API di dati.
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.
I tipi di ordinamento DELTA, SMART, HISTOGRAM_BUCKET supportati dall'API di reporting v4 non sono implementati nell'API di dati v1.
Il tipo di ordinamento OrderType.NUMERIC dell'API di dati v1 equivale al valore OrderType.DIMENSION_AS_INTEGER dell'API di reporting v4.
Richiesta API di dati v1
Questo esempio mostra una query di esempio che segnala il conteggio delle sessioni per paese, ordinando le righe in base alla metrica sessions in ordine decrescente.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Risposta dell'API di dati v1
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "United States"
}
],
"metricValues": [
{
"value": "510449"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "283430"
}
]
},
....
],
"totalSize": 212,
"metadata": {}
}
Richiesta API di reporting v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"orderBys": [
{
"fieldName": "ga:sessions",
"sortOrder": "DESCENDING"
}
]
}
]
}
Risposta dell'API di reporting v4
{
"reports": [
{
....
"data": {
"rows": [
{
"dimensions": [
"United States"
],
"metrics": [
{
"values": [
"510449"
]
}
]
},
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"283430"
]
}
]
},
....
}
]
}
Applicazione dei filtri
Le clausole dimensionFilter e metricFilter dell'API di dati v1 possono essere utilizzate per chiedere all'API di restituire solo dati per specifici valori di dimensione o metrica. È simile a dimensionFilterClauses e metricFilterClauses dell'API di reporting v4.
L'API di dati v1 non supporta le stringhe di espressione di filtro come la clausola
filtersExpression
dell'API di reporting v4. Queste espressioni devono essere riscritte utilizzando le clausole dimensionFilter e metricFilter.
Richiesta API di dati v1
Questa richiesta di esempio restituisce un elenco di conteggi delle sessioni per determinati percorsi di pagina visitati dagli utenti.
La clausola dimensionFilter viene utilizzata per restituire solo le righe con i valori delle dimensioni pagePath che iniziano con /webstore/ e contengono la stringa action=a12345.
La clausola metricFilter chiede al metodo runReport di restituire solo le righe con i valori della metrica sessions superiori a 1000.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "pagePath"
}
],
"dimensionFilter": {
"andGroup": {
"expressions": [
{
"filter": {
"stringFilter": {
"value": "/webstore/",
"matchType": "BEGINS_WITH"
},
"fieldName": "pagePath"
}
},
{
"filter": {
"stringFilter": {
"matchType": "CONTAINS",
"value": "action=a12345"
},
"fieldName": "pagePath"
}
}
]
}
},
"metricFilter": {
"filter": {
"numericFilter": {
"value": {
"int64Value": 1000
},
"operation": "GREATER_THAN"
},
"fieldName": "sessions"
}
},
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Richiesta API di reporting v4
Questa richiesta di esempio è simile all'esempio dell'API di dati v1. Restituisce un elenco del numero di sessioni per determinati percorsi di pagina visitati dagli utenti.
Il campo dimensionFilterClauses viene utilizzato per restituire solo le righe con i valori della dimensione pagePath che iniziano con /webstore/ e contengono la stringa action=a12345.
Il campo metricFilterClauses viene utilizzato per restituire solo le righe con valori della metrica ga:sessions superiori a 1000.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:pagePath"
}
],
"metricFilterClauses": [
{
"filters": [
{
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "1000"
}
]
}
],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:pagePath",
"operator": "BEGINS_WITH",
"expressions": [
"/webstore/"
]
},
{
"dimensionName": "ga:pagePath",
"operator": "PARTIAL",
"expressions": [
"action=a12345"
]
}
],
"operator": "AND"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
]
}
Impaginazione
L'API di dati v1 utilizza i campi limit e offset per eseguire l'impaginazione dei risultati di risposta su più pagine, mentre l'API di reporting v4 utilizza pageToken e pageSize.
Per le richieste pivot dell'API di dati v1, i campi limit e offset dell'oggetto Pivot devono essere utilizzati per implementare la paginazione per ogni pivot singolarmente. Ora il campo limit è obbligatorio per ogni oggetto Pivot.
Per impostazione predefinita, l'API di dati v1 restituisce al massimo le prime 10.000 righe di dati sugli eventi, mentre il valore predefinito per la versione 4 dell'API di reporting è 1000 righe.
Il numero totale di righe corrispondenti alla query viene restituito utilizzando il campo rowCount in una risposta dell'API di dati v1, simile alla versione 4 dell'API di reporting.
Richiesta API di dati v1
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"limit": 5,
"offset": 15
}
Risposta dell'API di dati v1
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"rowCount": 228,
}
Richiesta API di reporting v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"pageSize": 5,
"pageToken": "5"
}
]
}
Risposta dell'API di reporting v4
{
"reports": [
{
....
"data": {
"rows": [
....
],
....
"rowCount": 225,
},
"nextPageToken": "15"
}
]
}
Aggregazioni di metriche
L'API di dati v1 calcola i valori di aggregazione solo quando il campo metricAggregations è specificato in una richiesta. Al contrario, l'API di reporting v4 restituisce per impostazione predefinita i valori totali, minimi e massimi di ogni metrica, a meno che i campi hideTotals e hideValueRanges siano impostati su true.
Richiesta API di dati v1
Le aggregazioni verranno calcolate solo se il campo metricAggregations è specificato in una richiesta.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metricAggregations": [
"TOTAL",
"MAXIMUM",
"MINIMUM"
],
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Risposta dell'API di dati v1
Le righe delle metriche aggregate vengono restituite nei campi totals, minimum e maximum di una risposta. Per le righe delle metriche aggregate, il campo dimensionValues
contiene un valore speciale di RESERVED_TOTAL, RESERVED_MAX o RESERVED_MIN.
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"totals": [
{
"dimensionValues": [
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6026053"
}
]
}
],
"maximums": [
{
"dimensionValues": [
{
"value": "RESERVED_MAX"
},
{
"value": "RESERVED_MAX"
}
],
"metricValues": [
{
"value": "493655"
}
]
}
],
"minimums": [
{
"dimensionValues": [
{
"value": "RESERVED_MIN"
},
{
"value": "RESERVED_MIN"
}
],
"metricValues": [
{
"value": "1"
}
]
}
],
....
}
Richiesta API di reporting v4
Una richiesta di esempio per restituire il numero di sessioni per paese.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
}
]
}
Risposta dell'API di reporting v4
I campi totals, minimums e maximums sono presenti per impostazione predefinita in una risposta dell'API di reporting v4.
{
"reports": [
{
"columnHeader": {
....
},
"data": {
"rows": [
....
],
....
"totals": [
{
"values": [
"4493363"
]
}
],
"minimums": [
{
"values": [
"1"
]
}
],
"maximums": [
{
"values": [
"684005"
]
}
]
}
}
]
}
Pivot
L'API di dati v1 supporta la funzionalità pivot nei metodi di generazione di report runPivotReport e batchRunPivotReports.
L'API di reporting v4 consente di includere pivot nelle query di reporting utilizzando il metodo batchGet.
I pivot vengono implementati in modo diverso nell'API di dati v1 rispetto all'API di reporting v4 in modo che ogni riga di risposta rappresenti una singola cella della tabella, mentre nell'API di reporting v4 una singola riga di risposta rappresenta una riga completa.
API di dati v1
Di seguito è riportato un frammento di una risposta dell'API di dati v1 alla query runPivotReport. Ogni cella del report pivot viene restituita singolarmente:
"rows": [
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
API di reporting v4
Di seguito è riportato un frammento di una risposta dell'API di reporting v4 alla query batchGet. Una singola riga di risposta rappresenta una riga completa della tabella contenente tutti i valori delle metriche per il pivot in pivotValueRegions:
"data": {
"rows": [
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
Nell'API di dati v1, ogni dimensione della query runPivotReport o
batchRunPivotReports deve essere definita all'interno di un oggetto pivot. Una dimensione
non è visibile in un report se non viene utilizzata in nessun pivot di una query pivot.
Le colonne pivot dell'API di dati v1 vengono specificate utilizzando il campo fieldNames anziché il campo dimensions dell'API di reporting v4.
Se si desidera applicare un filtro delle dimensioni in una richiesta di report dell'API di dati v1, è necessario utilizzare un filtro dimensione con ambito di richiesta. È diversa dalla versione 4 dell'API di reporting, che accetta la specifica dimensionFilterClauses in un oggetto pivot.
Il campo offset dell'API di dati v1 è funzionalmente simile al campo startGroup dell'API di reporting v4.
Il campo limit dell'API di dati v1 è simile al valore maxGroupCount dell'API di reporting v4 e deve essere utilizzato per 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. L'API di reporting v4 supporta
una sola dimensione pivot.
Per impostazione predefinita, l'API di dati v1 ordina le dimensioni all'interno di un pivot in base alla prima metrica nel report. Questo comportamento è diverso dalla versione 4 dell'API di reporting, in cui l'ordinamento del pivot è determinato in ordine decrescente in base al "totale" delle metriche richieste. Per specificare l'ordinamento nella versione v1 dell'API di dati, utilizza il campo orderBys di una specifica di Pivot.
Richiesta API di dati v1
Questa query pivot dell'API di dati v1 crea un report sul conteggio delle sessioni per paese, basato sulla dimensione browser. Nota come la query utilizza i campi orderBys, limit e offset per riprodurre il comportamento di una query simile dell'API di reporting v4 al fine di preservare le impostazioni di ordinamento e paginazione.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"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"
}
]
}
Risposta dell'API di dati v1
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "(not set)"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
}
]
}
],
"rowCount": 234
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Safari"
}
]
},
{
"dimensionValues": [
{
"value": "Edge"
}
]
},
{
"dimensionValues": [
{
"value": "Opera"
}
]
}
],
"rowCount": 124
}
],
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "browser"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "237"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "44"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "22"
}
]
},
....
],
....
}
Richiesta API di reporting v4
Questa query pivot della versione 4 dell'API di reporting crea un report sul conteggio delle sessioni per paese, basato sulla dimensione ga:browser.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2021-01-01",
"endDate": "2021-01-30"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"pivots": [
{
"dimensions": [
{
"name": "ga:browser"
}
],
"startGroup": 3,
"maxGroupCount": 3,
"metrics": [
{
"expression": "ga:sessions"
}
]
}
]
}
]
}
Risposta dell'API di reporting v4
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:country"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:sessions",
"type": "INTEGER"
}
],
"pivotHeaders": [
{
"pivotHeaderEntries": [
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Edge"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Opera"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Samsung Internet"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
}
],
"totalPivotGroupsCount": 19
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"(not set)"
],
"metrics": [
{
"values": [
"781283"
],
"pivotValueRegions": [
{
"values": [
"6923",
"1385",
"66"
]
}
]
}
]
},
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
{
"dimensions": [
"Algeria"
],
"metrics": [
{
"values": [
"23208"
],
"pivotValueRegions": [
{
"values": [
"19252",
"66",
"1582"
]
}
]
}
]
},
....
],
....
}
}
]
}
Coorti
L'API di dati v1 utilizza la specifica CohortSpec per configurare i report di coorte. È simile alla specifica CohortGroup dell'API di reporting v4.
Tutte le metriche disponibili nell'API di dati v1 sono attualmente compatibili con le query di coorte, mentre l'API di reporting v4 consente di utilizzare solo un sottoinsieme di metriche speciali in una query di coorte.
In una richiesta di coorte API di dati v1, la metrica cohortActiveUsers è obbligatoria.
Sia l'API di dati v1 che l'API di reporting v4 consentono fino a 12 coorti in una singola richiesta.
Le metriche del lifetime value (LTV) non sono attualmente supportate nell'API di dati v1.
Equivalenza delle metriche di coorte
La maggior parte delle metriche di coorte definite nell'API di reporting v4 può essere sostituita con un'espressione per ottenere un risultato equivalente nell'API di dati v1, come illustrato nel grafico riportato di seguito.
| Nome metrica API di reporting v4 | Nome o espressione della metrica API di dati v1 |
|---|---|
| ga:cohortActiveUsers | cohortActiveUsers |
| ga:cohortTotalUsers | cohortTotalUsers |
| ga:cohortRetentionRate | "expression": "cohortActiveUsers/cohortTotalUsers" |
| ga:cohortRevenuePerUser | "expression": "totalRevenue/cohortActiveUsers" |
| ga:cohortVisitDurationPerUser | "expression": "userEngagementDuration/cohortActiveUsers" |
| ga:cohortAppviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortPageviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortSessionsPerUser | "expression": "sessions/cohortActiveUsers" |
| ga:cohortGoalCompletionsPerUser | "expression": "eventCount/cohortActiveUsers", oltre a un filtro delle dimensioni per eventName corrispondente all'evento di completamento obiettivo desiderato. |
Richiesta API di dati v1
Una query di esempio che configura una coorte di utenti la cui prima sessione si è verificata in una settimana del 3/01/2021. Il numero di utenti attivi e il tasso di fidelizzazione degli utenti vengono calcolati per la coorte nell'arco di 5 settimane, utilizzando la granularità WEEKLY.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"name": "cohort",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
],
"cohortsRange": {
"startOffset": 0,
"endOffset": 4,
"granularity": "WEEKLY"
}
},
"metrics": [
{
"name": "cohortActiveUsers"
},
{
"expression": "cohortActiveUsers/cohortTotalUsers",
"name": "cohortRetentionRate"
}
],
"dimensions": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
]
}
Risposta dell'API di dati v1
{
"dimensionHeaders": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
],
"metricHeaders": [
{
"name": "cohortActiveUsers",
"type": "TYPE_INTEGER"
},
{
"name": "cohortRetentionRate",
"type": "TYPE_FLOAT"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0000"
}
],
"metricValues": [
{
"value": "4268816"
},
{
"value": "0.999913800857494"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0001"
}
],
"metricValues": [
{
"value": "241580"
},
{
"value": "0.056586926213534013"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0002"
}
],
"metricValues": [
{
"value": "159390"
},
{
"value": "0.037335003597877253"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0003"
}
],
"metricValues": [
{
"value": "131512"
},
{
"value": "0.030804950079453122"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0004"
}
],
"metricValues": [
{
"value": "96793"
},
{
"value": "0.022672482610259947"
}
]
}
],
"totalSize": 5,
"metadata": {}
}
Richiesta API di reporting v4
Una query di esempio che configura una coorte di utenti la cui prima sessione
si è verificata in una settimana del 3/01/2021. Il numero di utenti attivi e il tasso di fidelizzazione degli utenti vengono calcolati per la coorte nell'arco di 5 settimane, utilizzando la granularità WEEKLY.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dimensions": [
{
"name": "ga:cohort"
},
{
"name": "ga:cohortNthWeek"
}
],
"metrics": [
{
"expression": "ga:cohortActiveUsers"
},
{
"expression": "ga:cohortRetentionRate"
}
],
"cohortGroup": {
"cohorts": [
{
"name": "cohort",
"type": "FIRST_VISIT_DATE",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
]
}
}
]
}
Risposta dell'API di reporting v4
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:cohort",
"ga:cohortNthWeek"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:cohortActiveUsers",
"type": "INTEGER"
},
{
"name": "ga:cohortRetentionRate",
"type": "PERCENT"
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"cohort",
"0000"
],
"metrics": [
{
"values": [
"40793",
"100.0"
]
}
]
},
{
"dimensions": [
"cohort",
"0001"
],
"metrics": [
{
"values": [
"3883",
"9.518789988478416"
]
}
]
},
{
"dimensions": [
"cohort",
"0002"
],
"metrics": [
{
"values": [
"2165",
"5.307283112298679"
]
}
]
},
{
"dimensions": [
"cohort",
"0003"
],
"metrics": [
{
"values": [
"1703",
"4.174735861544873"
]
}
]
},
{
"dimensions": [
"cohort",
"0004"
],
"metrics": [
{
"values": [
"1484",
"3.637879047875861"
]
}
]
},
{
"dimensions": [
"cohort",
"0005"
],
"metrics": [
{
"values": [
"1103",
"2.7038952761503197"
]
}
]
},
{
"dimensions": [
"cohort",
"0006"
],
"metrics": [
{
"values": [
"933",
"2.28715711028853"
]
}
]
},
{
"dimensions": [
"cohort",
"0007"
],
"metrics": [
{
"values": [
"336",
"0.8236707278209496"
]
}
]
}
],
"totals": [
{
"values": [
"52400",
"16.056676390557204"
]
}
],
"rowCount": 8,
"minimums": [
{
"values": [
"336",
"0.8236707278209496"
]
}
],
"maximums": [
{
"values": [
"40793",
"100.0"
]
}
],
"isDataGolden": true
}
}
]
}
Campionamento
L'API di dati v1 utilizza automaticamente il campionamento dei dati quando prevede che i limiti di cardinalità ridurranno la qualità dei dati. Se i risultati di un intervallo di date vengono campionati, il valore metadata di RunReportResponse conterrà un valore SamplingMetadata corrispondente, simile al campo samplingLevel presente nella versione 4 dell'API di reporting.
Aggiornamento dei dati
L'API di dati non fornisce un equivalente del campo isDataGolden dell'API di reporting v4, che è stato utilizzato per indicare se tutti gli hit di un report hanno terminato l'elaborazione. A causa di ulteriori elaborazioni, è ancora possibile che lo stesso report restituisca risultati diversi quando viene eseguita una query in una data successiva.
(Non supportato) Segmenti
I segmenti non sono attualmente supportati nella versione 1 dell'API di dati.
Report In tempo reale
Utilizza il metodo properties.runRealtimeReport dell'API di dati v1 per generare report in tempo reale per le proprietà Google Analytics 4. La funzionalità di generazione di report in tempo reale per le proprietà Universal Analytics è stata fornita dal metodo data.realtime.get dell'API Google Analytics v3.
Lo schema dei report in tempo reale dell'API di dati è diverso dallo schema dei report in tempo reale dell'API Analytics v3, a causa di differenze concettuali tra Universal Analytics e Google Analytics 4.
Richiesta API di dati v1
Nel seguente esempio, per mantenere il comportamento di ordinamento predefinito dell'API Google Analytics v3, è stato aggiunto un elemento orderBy facoltativo alla query v1 dell'API di dati di esempio.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }],
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
}
Risposta dell'API di dati v1
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": ""
}
],
"metricValues": [
{
"value": "199"
}
]
},
{
"dimensionValues": [
{
"value": "Afghanistan"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
],
"metricValues": [
{
"value": "136"
}
]
},
....
],
"rowCount": 172
}
Richiesta API Google Analytics v3
GET https://analytics.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&metrics=rt:activeUsers&dimensions=rt:country
Risposta dell'API Google Analytics v3
{
"kind": "analytics#realtimeData",
"id": "https://www.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&dimensions=rt:country&metrics=rt:activeUsers",
"query": {
"ids": "ga:UA_VIEW_ID",
"dimensions": "rt:country",
"metrics": [
"rt:activeUsers"
],
"max-results": 10
},
"totalResults": 178,
"profileInfo": {
"profileId": "XXXXXX",
"accountId": "XXXXXX",
"webPropertyId": "UA-XXXXXX",
"profileName": "View Name",
},
"columnHeaders": [
{
"name": "rt:country",
"columnType": "DIMENSION",
"dataType": "STRING"
},
{
"name": "rt:activeUsers",
"columnType": "METRIC",
"dataType": "INTEGER"
}
],
"totalsForAllResults": {
"rt:activeUsers": "80351"
},
"rows": [
[
"(not set)",
"97"
],
[
"Afghanistan",
"2"
],
[
"Albania",
"78"
],
....
]
}
(Non supportato) Report sull'attività utente
L'API di dati v1 attualmente non supporta la funzionalità di segnalazione delle attività dei singoli utenti simili al metodo userActivity.search dell'API di reporting v4.
Modifiche alla quota API
Categorie di quota principali e in tempo reale
Ai fini della quota, l'API di dati ha due categorie di richieste: Core e In tempo reale. Le richieste API ai metodi di reporting principali (runReport, getMetadata, runPivotReport, batchRunReports, batchRunPivotReports) addebitano le quote principali.
Le richieste API al metodo runRealtimeReport addebitano le quote in tempo reale.
Quote per i token
Oltre alle quote del progetto, ogni richiesta utilizza quote per i token di proprietà che vengono addebitate in base alla complessità della query. Per una descrizione dettagliata delle quote e dei limiti dell'API, consulta la documentazione relativa alle quote dell'API di dati v1.
È possibile ottenere lo stato attuale di tutte le quote per una proprietà Analytics
impostando returnPropertyQuota
su true in una richiesta di report principale o in tempo reale. Lo stato della quota verrà restituito in PropertyQuota.
(Non supportata) Quota basata sulle risorse
Poiché tutti i report principali in Google Analytics 4 si basano su dati non campionati, la quota basata sulle risorse introdotta nell'API di reporting v4 non è più applicabile e non esiste un equivalente del campo useResourceQuotas presente in una richiesta di report dell'API di dati v1.
(Non supportato) Quota di richieste per vista (profilo) al giorno
Poiché non esistono viste in Google Analytics 4, la quota requests per view (profile) per day
non è presente nell'API di dati v1 e viene sostituita da quote per token.