Questa guida fornisce linee guida per eseguire la migrazione dell'API Core Reporting v3 all'API Analytics Reporting v4.
Introduzione
Per sfruttare le nuove funzionalità introdotte nell'API Analytics Reporting v4, esegui la migrazione del codice per utilizzare l'API. Questa guida mostra le richieste nell'API Core Reporting v3 e le richieste equivalenti nell'API Analytics Reporting v4 per semplificare la migrazione.
Migrazione Python
Se sei uno sviluppatore Python, utilizza la libreria helper GAV4 su GitHub per convertire le richieste dell'API Core Reporting v3 di Google Analytics in richieste dell'API Analytics Reporting v4
Endpoint
L'API Core Reporting v3 e l'API Analytics Reporting v4 hanno endpoint e metodi HTTP diversi:
Endpoint v3
GET https://www.googleapis.com/analytics/v3/data/ga
Endpoint v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
I seguenti esempi confrontano una richiesta nella versione 3 e la richiesta equivalente nella versione 4:
v3
Documentazione di riferimento versione 3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
&metrics=ga:users&dimensions=ga:pagePath
v4
Documentazione di riferimento della versione 4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
"metrics":[
{
"expression":"ga:users"
}],
"dimensions": [
{
"name":"ga:pagePath"
}]
}]
}
Librerie client e servizio di individuazione
Se utilizzi Python, JavaScript o un'altra libreria client che si basa su Google Discovery Service, devi fornire il percorso del documento di rilevamento per l'API di reporting v4.
Python
from apiclient import discovery
...
# Build the Analytics Reporting API v4 authorized service object.
analyticsReporting = discovery.build(
'analyticsreporting',
'v4',
http=http,
discoveryServiceUrl='https://analyticsreporting.googleapis.com/$discovery/rest')
JavaScript
gapi.client.load(
'https://analyticsreporting.googleapis.com/$discovery/rest',
'v4'
).then(...)
Le librerie client Java e PHP sono predefinite, ma puoi generarle utilizzando il servizio di rilevamento e il generatore di API di Google.
Richieste
Il riferimento API v4 descrive nel dettaglio la struttura del corpo della richiesta. Le seguenti sezioni descrivono la migrazione dei parametri di richiesta v3 ai parametri di richiesta v4.
Visualizza ID
Nella versione 3, un parametro ids
, che accetta un "ID tabella", è nel formato ga:XXXX
, dove XXXX
è l'ID vista (profilo). Nella versione 4, un ID vista (profilo) viene specificato nel campo viewId
del corpo della richiesta.
I seguenti esempi confrontano il parametro ids
in una richiesta v3 con il campo viewId
in una richiesta v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
...
}]
}
Intervalli di date
La versione 4 dell'API Analytics Reporting consente di specificare più intervalli di date in una singola richiesta. Il campo dateRanges
richiede un elenco di oggetti DateRange.
Nella versione 3, utilizzi i parametri start-date
e end-date
per specificare un intervallo di date in una richiesta.
I seguenti esempi confrontano i parametri start-date
e end-date
in una richiesta v3
e il campo dateRanges
in una richiesta v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
...
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
....
}]
}
Metriche
Il parametro metrics
v3 corrisponde al campo metrics
v4 che richiede un elenco di oggetti Metrica.
I seguenti esempi confrontano i parametri metrics
in una richiesta v3
e il campo metrics
in una richiesta v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-11-01&end-date=2015-11-06 \
&metrics=ga:users,ga:sessions \
...
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
"viewId":"XXXX",
"dateRanges":[
{
"startDate":"2015-11-01",
"endDate":"2015-11-06"
}],
"metrics":[
{
"expression":"ga:users"
},{
"expression":"ga:sessions"
}],
...
}]
}
Dimensioni
Il parametro dimensions
v3 corrisponde al campo dimensions
v4 che richiede un elenco di oggetti Dimensione.
I seguenti esempi confrontano i parametri dimensions
in una richiesta v3
e il campo dimensions
in una richiesta v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&dimensions=ga:country,ga:browser&... \
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"dimensions": [
{
"name":"ga:country"
},{
"name":"ga:browser"
}],
...
}]
}
Ordinamento
Il parametro sort
v3 è equivalente al campo v4
orderBys
che richiede un elenco di oggetti OrderBy.
Nella versione 4, per ordinare i risultati in base a un valore di dimensione o metrica:
- Fornisci il nome o l'alias tramite il campo
fieldName
. - Specifica l'ordinamento (
ASCENDING
oDESCENDING
) tramite il camposortOrder
.
I seguenti esempi confrontano il parametro sort
in una richiesta v3
e il campo orderBy
in una richiesta v4. Entrambi ordinano gli utenti
in ordine decrescente e le origini in ordine alfabetico:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&sort=-ga:users,ga:source
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"orderBys": [
{
"fieldName": "ga:users",
"sortOrder": "DESCENDING"
},{
"fieldName": "ga:source"
}],
}]
}
Livello di campionamento
Il parametro samplingLevel
v3 corrisponde al campo v4
samplingLevel
. Nella versione 3, i valori samplingLevel
accettati sono FASTER
, HIGHER_PRECISION
e DEFAULT
, mentre nella versione v4 i valori samplingLevel
accettati sono SMALL
, LARGE
e DEFAULT
.
Tieni presente che il valore FASTER
nella v3 è cambiato in SMALL
nella v4 e in HIGHER_PRECISION
in LARGE
.
I seguenti esempi confrontano il parametro samplingLevel
in una richiesta v3
e il campo samplingLevel
in una richiesta v4:
v3
https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX ...\
samplingLevel=HIGHER_PRECISION
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"samplingLevel": "LARGE"
}]
}
Segmenti
Il parametro segment
v3 corrisponde al campo v4
segments
che richiede un elenco di oggetti Segmento.
ID segmento
Nella versione v4, per richiedere un segmento in base all'ID segmento, crea un oggetto Segmento e fornisci il relativo ID tramite il campo segmentId.
I seguenti esempi confrontano il parametro segment
in una richiesta v3
e il campo segments
in una richiesta v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=gaid::-11
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"viewId": "XXXX",
"segments": [{
"segmentId": "gaid::-11"
}]
}]
}
Segmenti dinamici
Nella versione v4, per definire definizioni di segmenti più complesse, utilizza il campo segments
che include un oggetto DynamicSegment.
I seguenti esempi confrontano il parametro segment
in una richiesta v3 e il campo segments
contenente un oggetto DynamicSegment
in una richiesta v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"segments": [{
"dynamicSegment": {
"name": "segment_name",
"sessionSegment": {
"segmentFilters": [{
"simpleSegment": {
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:medium",
"operator": "EXACT",
"expressions": [ "referral" ]
}
}]
}]
}
}]
}
}
}]
}]
}
Puoi combinare condizioni e sequenze in un segmento:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=users::condition::ga:revenue>10;sequence::ga:deviceCategory==desktop->>ga:deviceCategory==mobile
v4
"reportRequests": [{
"dateRanges": [
{ "endDate": "2014-11-30", "startDate": "2014-11-01" }
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"viewId": "XXXX",
"dimensions":[{"name":"ga:medium"}, {"name":"ga:segment"}],
"segments": [{
"dynamicSegment": {
"name": "segment_name",
"userSegment": {
"segmentFilters": [{
"simpleSegment": {
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"metricFilter": {
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "10"
}
}]
}]
}
},
{
"sequenceSegment": {
"segmentSequenceSteps": [{
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:deviceCategory",
"operator": "EXACT",
"expressions": ["desktop"]
}
}]
}],
"matchType": "PRECEDES"
},{
"orFiltersForSegment": [{
"segmentFilterClauses": [{
"dimensionFilter": {
"dimensionName": "ga:deviceCategory",
"operator": "EXACT",
"expressions": ["mobile"]
}
}]
}]
}]
}
}]
}
}
}]
}]
Sintassi dei segmenti v3 in v4
Il campo segmentId nell'API v4 supporta la sintassi del segmento nell'API v3.
I seguenti esempi mostrano come il parametro segment
in una richiesta v3 sia supportato dal campo segmentId
nella richiesta equivalente nella versione v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&segment=sessions::condition::ga:medium==referral
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"viewId": "XXXX",
"segments": [{
"segmentId": "sessions::condition::ga:medium==referral"
}]
}]
}
Filtri
La versione 4 utilizza dimensionFilterClauses
per
filtrare le dimensioni e metricFilterClauses
per filtrare le metriche. Un elemento dimensionFilterClauses
contiene un elenco di oggetti DimensionFilter, mentre un elemento metricFilterClauses
contiene un elenco di oggetti MetricFilter.
I seguenti esempi confrontano il parametro filters
in una richiesta v3
e il campo dimensionFilterClauses
in una richiesta v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga:XXXX \
&start-date=2015-06-01&end-date=2015-07-31&metrics=ga:users& \
dimensions=ga:browser&filters=ga:browser==Firefox
v4
"reportRequests": [{
"dateRanges": [
{ "endDate": "2014-11-30", "startDate": "2014-11-01" }
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"viewId": "XXXX",
"dimensions":[{"name":"ga:browser"}, {"name":"ga:country"}],
"dimensionFilterClauses": [{
"filters": [{
"dimension_name": "ga:browser",
"operator": "EXACT",
"expressions": ["Firefox"]
}]
}]
}]
Sintassi dei filtri v3 nella v4
Anche se il campo filtersExpression nella versione 4 supporta la sintassi filters
nella versione 3, utilizza dimensionFilterClauses
e metricFilterClauses
per filtrare dimensioni e metriche.
I seguenti esempi mostrano come il parametro filters
in una richiesta v3 sia supportato dal campo filtersExpression
nella richiesta equivalente nella versione v4:
v3
GET https://www.googleapis.com/analytics/v3/data/ga?ids=ga%XXXX \
&filters=ga:browser==Firefox
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [{
...
"filtersExpression": "ga:browser==Firefox"
}]
}
Righe vuote
Il parametro v3 include-empty-rows
corrisponde al campo includeEmptyRows
nella versione 4. Per impostazione predefinita, il parametro v3 è true, mentre nella versione v4 il campo è impostato su false. Se non hai impostato il valore nella v3, dovrai impostare
il valore su true nella v4.
I seguenti esempi confrontano il parametro include-empty-rows
in una richiesta v3 con il campo includeEmptyRows
in una richiesta v4:
v3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&include-empty-rows=true
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
"includeEmptyRows": "true",
}]
}
Impaginazione
La versione 4 utilizza i campi pageToken
e pageSize
per l'impaginazione in base a un numero elevato di risultati. Il valore pageToken
viene ottenuto dalla
proprietà nextPageToken
di un oggetto risposta.
I seguenti esempi confrontano i parametri start-index
e max-results
in una richiesta v3 con i campi pageToken
e pageSize
in una richiesta v4:
v3
https://www.googleapis.com/analytics/v3/data/ga? ...\
&start-index=10001&max-results=10000
v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
Parametri standard
L'API Analytics Reporting v4 supporta la maggior parte dei
parametri di query standard
nell'API v3, ad eccezione dei parametri userIp
e callback
.
I seguenti esempi confrontano il parametro quotaUser
in una richiesta v3 con quello in una richiesta v4:
Endpoint v3
GET https://www.googleapis.com/analytics/v3/data/ga?quotaUser=1X3F2F2
Endpoint v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet?quotaUser=1X3F2F2
Risposte
Poiché la versione 4 consente di inviare più oggetti ReportRequest in una singola richiesta HTTP, nella risposta viene visualizzato un array di oggetti report. Per ogni ReportRequest inviato, ricevi un Report corrispondente nella risposta.
Report
Un report v4
ha tre campi di primo livello: columnHeader
, data
e nextPageToken
.
Poiché il corpo della risposta v4 non include risposte a tutti i parametri di query come la risposta v3, per ottenere una risposta a uno specifico parametro di query, l'applicazione client deve aggiungere questo parametro a ReportRequest.
Abbiamo già affrontato il problema di nextPageToken
nella sezione Pagination, quindi diamo prima un'occhiata all'oggetto columnHeader.
Intestazione di colonna
L'intestazione di colonna contiene un elenco di dimensioni denominate e un oggetto MetricHeader, che contiene un elenco di oggetti MetricHeaderEntry. Ogni oggetto MetricHeaderEntry
specifica la metrica name
e il relativo type
(valuta, percentuale e così via)
, che ti aiuta a formattare l'output.
I seguenti esempi confrontano il campo columnHeaders
in una risposta v3 con il campo columnHeader
in una risposta v4:
v3
"columnHeaders": [
{
"name":"ga:source",
"columnType":"DIMENSION",
"dataType":"STRING"
},{
"name":"ga:city",
"columnType":"DIMENSION",
"dataType":"STRING"
},{
"name":"ga:sessions",
"columnType":"METRIC",
"dataType":"INTEGER"
},{
"name":"ga:pageviews",
"columnType":
"METRIC",
"dataType":"INTEGER"
}
]
v4
"columnHeader": {
"dimensions": [
"ga:source",
"ga:city"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:pageviews",
"type": "INTEGER"
},
{
"name": "ga:sessions",
"type": "INTEGER"
}
]
}
},
Righe report
L'API Core Reporting v3 restituisce i dati del report nell'array righe, che contiene le dimensioni e le metriche richieste.
L'API Analytics Reporting v4 restituisce i dati del report in un oggetto ReportRow, che contiene un array di dimensioni e un array di oggetti DateRangeValues, ognuno dei quali contiene uno o due intervalli di date, come illustrato nel seguente diagramma:
Righe
v3
"rows": [
[
"google",
"Philadelphia",
"60",
"5"
],
[
"google",
"Johnstown",
"21",
"1"
],
[
"google",
"Progress",
"7",
"1"
]
],
v4
"rows": [
{
"dimensions": [
"google",
"Philadelphia"
],
"metrics": [
{
"values": [
"60",
"5"
]
}
]
},
{
"dimensions": [
"google",
"Johnstown"
],
"metrics": [
{
"values": [
"21",
"1"
]
}
]
},
{
"dimensions": [
"google",
"Progress"
],
"metrics": [
{
"values": [
"7",
"1"
]
}
]
}
],
Dati campionati
Se i risultati sono campionati, l'API Core Reporting v3 restituisce il campo booleano containsSampledData
, impostato su true
.
L'API Analytics Reporting v4 non restituisce un valore booleano se i dati sono campionati, ma restituisce i campi samplesReadCounts
e samplingSpaceSizes
.
Se i risultati non vengono campionati, questi campi non verranno definiti.
Il seguente esempio Python mostra come calcolare se un report contiene dati campionati:
def ContainsSampledData(report):
"""Determines if the report contains sampled data.
Args:
report (Report): An Analytics Reporting API v4 response report.
Returns:
bool: True if the report contains sampled data.
"""
report_data = report.get('data', {})
sample_sizes = report_data.get('samplesReadCounts', [])
sample_spaces = report_data.get('samplingSpaceSizes', [])
if sample_sizes and sample_spaces:
return True
else:
return False
Di seguito è riportato un esempio di risposta contenente dati campionati di una richiesta con due intervalli di date. I risultati sono stati calcolati su quasi 500.000 campioni di una dimensione dello spazio di campionamento di circa 15 milioni di sessioni:
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
Analisi della risposta v4
Il seguente codice di esempio analizza e stampa la risposta della versione 4 dell'API Analytics Reporting:
Python
def printResponse(self, response):
"""Parses and prints the Analytics Reporting API v4 response"""
for report in response.get('reports', []):
columnHeader = report.get('columnHeader', {})
dimensionHeaders = columnHeader.get('dimensions', [])
metricHeaders = columnHeader.get('metricHeader', {}).get('metricHeaderEntries', [])
rows = report.get('data', {}).get('rows', [])
for row in rows:
dimensions = row.get('dimensions', [])
dateRangeValues = row.get('metrics', [])
for header, dimension in zip(dimensionHeaders, dimensions):
print header + ': ' + dimension
for i, values in enumerate(dateRangeValues):
print 'Date range (' + str(i) + ')'
for metricHeader, value in zip(metricHeaders, values.get('values')):
print metricHeader.get('name') + ': ' + value
Java
public static void printResponse(GetReportsResponse response) {
for (Report report: response.getReports()) {
ColumnHeader header = report.getColumnHeader();
List<String> dimensionHeaders = header.getDimensions();
List<MetricHeaderEntry> metricHeaders = header.getMetricHeader().getMetricHeaderEntries();
List<ReportRow> rows = report.getData().getRows();
for (ReportRow row: rows) {
List<String> dimensions = row.getDimensions();
List<DateRangeValues> metrics = row.getMetrics();
for (int i = 0; i < dimensionHeaders.size() && i < dimensions.size(); i++) {
System.out.println(dimensionHeaders.get(i) + ": " + dimensions.get(i));
}
for (int j = 0; j < metrics.size(); j++) {
System.out.print("Date Range (" + j + "): ");
DateRangeValues values = metrics.get(j);
for (int k = 0; k < values.size() && k < metricHeaders.size(); k++) {
System.out.println(metricHeaders.get(k).getName() + ": " + values.get(k));
}
}
}
}
}
Gestione degli errori
Poiché il formato della risposta di errore nella versione 4 è diverso da quello nella versione v3, aggiorna il codice in modo da gestire le risposte di errore della versione v4.
I seguenti esempi confrontano una risposta di errore nella versione 3 e la risposta di errore equivalente nella versione v4:
v3
{
"error": {
"errors": [
{
"domain": "global",
"reason": "insufficientPermissions",
"message": "User does not have sufficient permissions for this profile.",
}
],
"code": 403,
"message": "User does not have sufficient permissions for this profile."
}
}
v4
{
"error": {
"code": 403,
"message": "User does not have sufficient permissions for this profile.",
"status": "PERMISSION_DENIED",
"details": [
{
"@type": "type.googleapis.com/google.rpc.DebugInfo",
"detail": "[ORIGINAL ERROR] generic::permission_denied: User does not have sufficient permissions for this profile. [google.rpc.error_details_ext] { message: \"User does not have sufficient permissions for this profile.\" }"
}
]
}
}