Guida alla migrazione

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 o DESCENDING) tramite il campo sortOrder.

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 report

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.\" }"
   }
  ]
 }
}