Guia de migração

Este guia contém diretrizes para a migração da Core Reporting API v3 para a Reporting API v4 do Google Analytics.

Introdução

Para aproveitar os novos recursos introduzidos na Reporting API v4 do Google Analytics, migre seu código para usar a API. Este guia mostra solicitações na Core Reporting API v3 e solicitações equivalentes na Reporting API v4 do Google Analytics para facilitar a migração.

Migração de Python

Se você é desenvolvedor de Python, use a biblioteca auxiliar GAV4 no GitHub para converter solicitações da Core Reporting API v3 do Google Analytics em solicitações da Reporting API v4 do Google Analytics

Pontos de extremidade

A Core Reporting API v3 e a Reporting API v4 do Google Analytics têm pontos de extremidade e métodos HTTP diferentes:

Ponto de extremidade da v3

GET https://www.googleapis.com/analytics/v3/data/ga

Ponto de extremidade da v4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet

Os exemplos a seguir comparam uma solicitação na v3 e a solicitação equivalente na v4:

v3

Documentação de referência da 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&dimensions=ga:pagePath

v4

Documentação de referência da 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"
    }],
    "dimensions": [
    {
      "name":"ga:pagePath"
    }]
  }]
}

Bibliotecas cliente e serviço de descoberta

Se você usar Python, JavaScript ou outra biblioteca cliente que dependa do serviço de descoberta do Google, será necessário fornecer o local do documento de descoberta para a Reporting API 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(...)

As bibliotecas cliente Java e PHP são criadas previamente, mas é possível usar o serviço de descoberta e o gerador de APIs do Google para criá-las.

Solicitações

A referência da API v4 descreve em detalhes a estrutura do corpo da solicitação. As seções a seguir descrevem a migração dos parâmetros de solicitação da v3 para os parâmetros de solicitação da v4.

IDs da vista

Na v3, um parâmetro ids, que aceita um "ID da tabela", está no formato ga:XXXX. XXXX representa o ID da vista (perfil). Na v4, o ID da vista (perfil) é especificado no campo viewId, no corpo da solicitação.

Os exemplos a seguir comparam o parâmetro ids em uma solicitação da v3 e o campo viewId em uma solicitação da 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",
    ...
  }]
}

Períodos

Com a Reporting API v4 do Google Analytics, é possível especificar vários períodos em uma única solicitação. O campo dateRanges utiliza uma lista de objetos DateRange. Na v3, os parâmetros start-date e end-date são usados para especificar um período em uma solicitação.

Os exemplos a seguir comparam os parâmetros start-date e end-date em uma solicitação da v3 e o campo dateRanges em uma solicitação da 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"
    }],
    ....
  }]
}

Métricas

O parâmetro metrics da v3 corresponde ao campo metrics da v4 que utiliza uma lista de objetos Metric.

Os exemplos a seguir comparam os parâmetros metrics em uma solicitação da v3 e o campo metrics em uma solicitação da 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"
    }],
    ...
  }]
}

Dimensões

O parâmetro dimensions da v3 corresponde ao campo dimensions da v4 que utiliza uma lista de objetos Dimension.

Os exemplos a seguir comparam os parâmetros dimensions em uma solicitação da v3 e o campo dimensions em uma solicitação da 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"
    }],
    ...
  }]
}

Classificação

O parâmetro sort da v3 é equivalente ao campo orderBys da v4 que utiliza uma lista de objetos OrderBy.

Na v4, para classificar os resultados pelo valor de uma dimensão ou métrica:

  • Forneça o nome ou o alias dela no campo fieldName.
  • Especifique a ordem de classificação (ASCENDING ou DESCENDING) no campo sortOrder.

Os exemplos a seguir comparam o parâmetro sort em uma solicitação da v3 e o campo orderBy em uma solicitação da v4. Ambos classificam os usuários em ordem decrescente e as origens em ordem alfabética:

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"
    }],
  }]
}

Nível de amostragem

O parâmetro samplingLevel da v3 corresponde ao campo samplingLevel da v4. Na v3, os valores de samplingLevel aceitos são FASTER, HIGHER_PRECISION e DEFAULT. Já na v4, os valores de samplingLevel aceitos são SMALL, LARGE e DEFAULT. FASTER na v3 mudou para SMALL na v4, e HIGHER_PRECISION mudou para LARGE.

Os exemplos a seguir comparam o parâmetro samplingLevel em uma solicitação da v3 e o campo samplingLevel em uma solicitação da 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"
  }]
}

Segmentos

O parâmetro segment corresponde ao campo segments da v4 que utiliza uma lista de objetos Segment.

IDs de segmentos

Para solicitar um segmento por ID na v4, crie um objeto Segment e forneça o ID dele no campo segmentId.

Os exemplos a seguir comparam o parâmetro segment em uma solicitação da v3 e o campo segments em uma solicitação da 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"
    }]
  }]
}

Segmentos dinâmicos

Para expressar definições de segmentos mais complicadas na v4, use o campo segments que inclui um objeto DynamicSegment.

Os exemplos a seguir comparam o parâmetro segment em uma solicitação da v3 e o campo segments que contém um objeto DynamicSegment em uma solicitação da 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" ]
                  }
                }]
              }]
            }
          }]
        }
      }
    }]
  }]
}

É possível combinar condições e sequências em um 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"]
                    }
                  }]
                }]
              }]
            }
          }]
        }
      }
    }]
  }]

Sintaxe de segmentos da v3 na v4

O campo segmentId na API v4 é compatível com a sintaxe de segmentos na API v3.

Os exemplos a seguir mostram como o parâmetro segment em uma solicitação da v3 é compatível com o campo segmentId na solicitação equivalente na 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"
    }]
  }]
}

Filtros

A v4 usa dimensionFilterClauses para filtrar dimensões e metricFilterClauses para filtrar métricas. dimensionFilterClauses contém uma lista de objetos DimensionFilter, enquanto metricFilterClauses contém uma lista de objetos MetricFilter.

Os exemplos a seguir comparam o parâmetro filters em uma solicitação da v3 e o campo dimensionFilterClauses em uma solicitação da 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"]
            }]
      }]
  }]

Sintaxe de filtros da v3 na v4

Embora o campo filtersExpression na v4 seja compatível com a sintaxe filters na v3, use dimensionFilterClauses e metricFilterClauses para filtrar dimensões e métricas.

Os exemplos a seguir mostram como o parâmetro filters em uma solicitação da v3 é compatível com o campo filtersExpression na solicitação equivalente na 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"
  }]
}

Linhas vazias

O parâmetro include-empty-rows da v3 corresponde ao campo includeEmptyRows na v4. O padrão do parâmetro da v3 é true, e o padrão do campo da v4 é false. Se você não definiu o valor na v3, precisará defini-lo como true na v4.

Os exemplos a seguir comparam o parâmetro include-empty-rows em uma solicitação da v3 com o campo includeEmptyRows em uma solicitação da 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",
  }]
}

Paginação

A v4 usa os campos pageToken e pageSize para paginar um grande número de resultados. O campo pageToken é adquirido da propriedade nextPageToken de um objeto de resposta.

Os exemplos a seguir comparam os parâmetros start-index e max-results em uma solicitação da v3 com os campos pageToken e pageSize em uma solicitação da 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",
  }]
}

Parâmetros padrão

A Reporting API v4 do Google Analytics é compatível com a maioria dos parâmetros de consulta padrão na API v3, com exceção dos parâmetros userIp e callback.

Os exemplos a seguir comparam o parâmetro quotaUser em uma solicitação da v3 ao mesmo parâmetro em uma solicitação da v4:

Ponto de extremidade da v3

GET https://www.googleapis.com/analytics/v3/data/ga?quotaUser=1X3F2F2

Ponto de extremidade da v4

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet?quotaUser=1X3F2F2

Respostas

Como a v4 permite enviar vários objetos ReportRequest em uma única solicitação HTTP, você recebe um conjunto de objetos de relatórios na resposta. Para cada ReportRequest enviado, você recebe um relatório correspondente na resposta.

Relatórios

Um relatório da v4 tem três campos de nível superior: columnHeader, data e nextPageToken.

O corpo de resposta da v4 não inclui respostas a todos os parâmetros de consulta, como ocorre na resposta da v3. Portanto, para receber uma resposta a um parâmetro de consulta específico, o aplicativo cliente precisa adicionar tal parâmetro ao ReportRequest.

Já abordamos nextPageToken na seção Paginação. Então, veremos o objeto columnHeader primeiro.

Cabeçalho da coluna

O cabeçalho da coluna contém uma lista de dimensões nomeadas e um objeto MetricHeader, que contém uma lista de objetos MetricHeaderEntry. Cada objeto MetricHeaderEntry especifica o name e o type da métrica (moeda, porcentagem etc.) que ajuda você a formatar a saída.

Os exemplos a seguir comparam o campo columnHeaders em uma resposta da v3 com o campo columnHeader em uma resposta da 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"
            }
        ]
    }
},

Linhas do relatório

A Core Reporting API v3 retorna os dados do relatório no conjunto de linhas, que contém as dimensões e métricas solicitadas.

A Reporting API v4 do Google Analytics retorna os dados do relatório em um objeto ReportRow, que contém uma matriz de dimensões e outra de objetos DateRangeValues. Cada um possui um ou dois períodos, conforme mostra o diagrama a seguir:

Linhas do relatório

Linhas

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"
                ]
            }
        ]
    }
],

Dados de amostra

Se os resultados forem de amostra, a Core Reporting API v3 retornará o campo booleano containsSampledData, definido como true.

A Reporting API v4 do Google Analytics não retornará um valor booleano se os dados forem de amostra. Ela retornará os campos samplesReadCounts e samplingSpaceSizes. Se os resultados não forem de amostra, esses campos não serão definidos. O exemplo de Python a seguir mostra como fazer o cálculo quando um relatório contiver dados de amostra:

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

Veja a seguir um exemplo de resposta que contém dados de amostra de uma solicitação com dois períodos. Os resultados foram calculados a partir de quase 500 mil amostras do tamanho de um espaço de amostragem de aproximadamente 15 milhões de sessões:

{
  "reports":
  [
    {
      "columnHeader": {
        ...
      },
      "data": {
        ...
        "samplesReadCounts": [ "499630","499630"],
        "samplingSpaceSizes": ["15328013","15328013"],
      }
    }
  ]
}

Análise da resposta da v4

O código de amostra a seguir analisa e imprime a resposta da Reporting API v4 do Google Analytics:

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));
        }
      }
    }
  }
}

Como lidar com erros

O formato Resposta de erro se diferencia da v4 para a v3. Por isso, atualize seu código para lidar com as respostas de erro da v4.

Os exemplos a seguir comparam uma resposta de erro na v3 e a resposta de erro equivalente na 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.\" }"
   }
  ]
 }
}