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 API Reporting v4 do Google Analytics, migre seu código para usar a API. Este guia mostra solicitações na API Core Reporting v3 e as solicitações equivalentes na API Reporting v4 do Google Analytics para facilitar a migração.
Migração de Python
Se você é um desenvolvedor de Python, use a biblioteca auxiliar GAV4 no GitHub para converter solicitações da API Core Reporting v3 do Google Analytics em solicitações da API Reporting 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 de cliente Java e PHP são pré-criadas, mas é possível usar o serviço de descoberta e o gerador de APIs do Google para gerá-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 de tabela", está no formato ga:XXXX
, em que XXXX
é o ID da vista (perfil). Na v4, um ID da vista da propriedade (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 API Reporting v4 do Google Analytics, é possível especificar vários períodos em uma única solicitação. O campo dateRanges
recebe 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 usa 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 usa 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 usa uma lista de objetos OrderBy.
Na v4, para classificar os resultados pelo valor de uma dimensão ou métrica, siga estas etapas:
- Forneça o nome ou o alias dela no
campo
fieldName
. - Especifique a ordem de classificação (
ASCENDING
ouDESCENDING
) no camposortOrder
.
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
. Na v4, os valores de samplingLevel
aceitos são SMALL
, LARGE
e DEFAULT
.
Observe que FASTER
na v3 mudou para SMALL
na v4, HIGHER_PRECISION
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
da v3 corresponde ao campo segments
da v4 que usa uma lista de objetos Segmento.
Códigos de segmentos
Na v4, para solicitar um segmento por ID, crie um objeto Segmento 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. Um dimensionFilterClauses
contém uma lista de objetos DimensionFilter, e um 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 da 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 pageToken
é obtido 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 API Reporting 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 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, vamos primeiro analisar o objeto
columnHeader.
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 a métrica name
e a type
(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 API Reporting 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 deles contém um ou dois períodos, como mostra o diagrama a seguir:
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 API Core Reporting v3 retornará o campo booleano containsSampledData
, que está definido como true
.
A API Reporting v4 do Google Analytics não retornará um booleano se os dados forem de amostra. Em vez disso, a API 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 calcular se um relatório contém 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 de resposta de erro da v4 é diferente daquele da 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.\" }"
}
]
}
}