Com a API Data v1 do Google Analytics, você pode gerar tabelas dinâmicas. As tabelas dinâmicas são uma ferramenta de resumo que visualiza os dados reorganizando as informações na tabela por meio da rotação (rota) dos dados em uma ou várias dimensões.
Por exemplo, considere a seguinte tabela de dados brutos:
Usando esses dados, é possível criar uma tabela dinâmica, detalhando os dados das sessões por navegador, com dimensões de país e idioma selecionadas como tabelas dinâmicas adicionais.
Recursos compartilhados com os relatórios principais
As solicitações de relatórios dinâmicos têm a mesma semântica das solicitações de relatórios principais para muitos recursos compartilhados. Por exemplo, paginação, filtros de dimensão e propriedades do usuário se comportam da mesma forma nos relatórios dinâmicos que nos relatórios principais. Este guia se concentra nos recursos de relatórios dinâmicos. Para se familiarizar com a funcionalidade de relatórios principais da API Data v1, leia o guia de noções básicas de relatórios e o de casos de uso avançados.
Métodos de relatórios dinâmicos
A API Data v1 é compatível com a funcionalidade de tabela dinâmica nos seguintes métodos de geração de relatórios:
runPivotReport: retorna um relatório dinâmico personalizado dos dados de eventos do Google Analytics. Cada tabela dinâmica descreve as colunas e linhas de dimensão visíveis na resposta do relatório.
batchRunPivotReports: é uma versão em lote do método
runPivotReportque permite gerar vários relatórios usando uma única chamada de API.
Como selecionar uma entidade denunciante
Todos os métodos da API Data v1 exigem que o identificador da propriedade do Google Analytics 4 seja especificado em um caminho de solicitação de URL no formato properties/GA4_PROPERTY_ID, como:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
O relatório será gerado com base nos dados de eventos do Google Analytics coletados na propriedade especificada do GA4.
Se você estiver usando uma das bibliotecas de cliente da API Data, não será necessário manipular manualmente o caminho do URL da solicitação. A maioria dos clientes de API fornece um parâmetro property que deve ser preenchido com uma string no formato properties/GA4_PROPERTY_ID. Consulte o guia de início rápido para exemplos de como usar as bibliotecas de cliente.
Solicitação de relatório dinâmico
Para criar uma solicitação com uma tabela dinâmica, use o método runPivotReport ou batchRunPivotReports.
Para solicitar dados dinâmicos, crie um objeto RunPivotReportRequest. Recomendamos começar com estes parâmetros de solicitação:
- Uma entrada válida no campo dateRanges.
- Pelo menos uma entrada válida no campo dimensions.
- pelo menos uma entrada válida no campo metrics.
- Pelo menos duas entradas dinâmicas válidas no campo pivots.
Veja a seguir um exemplo de solicitação com os campos recomendados:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
"dimensions": [
{ "name": "browser" },
{ "name": "country" },
{ "name": "language" }
],
"metrics": [{ "name": "sessions" }],
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5
},
{
"fieldNames": [
"country"
],
"limit": 250
},
{
"fieldNames": [
"language"
],
"limit": 15
}
]
}
Tabelas dinâmicas
Use objetos pivot no campo pivot do corpo da solicitação
para definir as tabelas dinâmicas do relatório. Cada Pivot descreve as colunas e linhas de dimensão visíveis na resposta do relatório.
A API Data v1 é compatível com várias tabelas dinâmicas,desde que o produto do parâmetro limit para cada tabela dinâmica não exceda 100.000.
Confira abaixo um snippet que demonstra o uso de pivots para criar um relatório de
contagens de sessões por país, dinamizado pela dimensão browser. Observe como a consulta usa o campo orderBys para classificação e os campos de limit e offset para implementar a paginação.
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
...
Dimensões
As dimensões descrevem e agrupam dados de eventos do seu site ou app. A dimensão city, por exemplo, indica a cidade ("Paris" ou "Nova York") de origem de cada evento. Em uma solicitação de relatório, você pode
especificar zero ou mais dimensões.
As dimensões precisam ser definidas dentro do campo dimensions do corpo de uma solicitação. Para ficarem visíveis em um relatório, essas dimensões também precisam ser listadas no campo fieldNames de um objeto Pivot.
Uma dimensão não será visível em um relatório se não for usada em nenhuma tabela dinâmica de uma consulta dinâmica. Nem todas as dimensões precisam estar presentes no fieldNames de uma tabela dinâmica. As dimensões podem ser usadas exclusivamente em filtros e não no fieldNames de qualquer tabela dinâmica.
Confira abaixo um snippet que demonstra o uso dos campos dimension e fieldNames para uma tabela com tabelas dinâmicas browser, country e language:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
},
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"language"
],
"limit": 10
}
],
Métricas
As métricas são avaliações quantitativas de dados de eventos do seu site ou app. Em uma solicitação de relatório, você pode especificar uma ou mais métricas. Consulte as métricas da API para ver uma lista completa dos nomes que podem ser especificados nas solicitações.
Nas solicitações de relatórios dinâmicos, as métricas são definidas usando o campo metrics do corpo da solicitação, que é semelhante aos métodos de relatórios principais.
Um exemplo abaixo especifica a contagem de sessões a ser usada como um valor de métrica em um relatório:
"metrics": [
{
"name": "sessions"
}
],
Agregações de métricas
Use o campo metricAggregations de um objeto pivot para calcular valores de métrica agregados para cada tabela dinâmica.
As agregações só serão calculadas se o campo metricAggregations for especificado em uma solicitação.
Veja abaixo o snippet de uma consulta que solicita os totais para a
dimensão dinâmica browser:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
As métricas calculadas são retornadas no campo de agregações do objeto RunPivotReportResponse. Para linhas de métricas agregadas, o campo dimensionValues contém um valor especial de RESERVED_TOTAL, RESERVED_MAX ou RESERVED_MIN.
"aggregates": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6"
}
]
},
....
}
Paginação
Semelhante aos métodos de relatórios principais, as solicitações de tabela dinâmica permitem especificar os campos de limite e deslocamento no objeto pivot para implementar a paginação.
As configurações de paginação são aplicadas a cada tabela dinâmica individualmente.
O campo limit é obrigatório para cada objeto Pivot para limitar a cardinalidade do relatório.
A API Data v1 é compatível com várias tabelas dinâmicas, desde que o produto do parâmetro limit para cada tabela não exceda 100.000.
Confira abaixo um snippet que demonstra o uso dos campos offset e limit para
recuperar as próximas cinco dimensões de language com um deslocamento de 10:
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
Filtragem
Assim como na funcionalidade de relatórios principais, é necessário usar um filtro de dimensão no escopo da solicitação para filtrar dimensões em uma solicitação de relatório dinâmico.
Classificação
O comportamento de ordenação das consultas do relatório dinâmico pode ser controlado para cada tabela dinâmica individualmente usando o campo orderBys de um objeto pivot, que contém uma lista de objetos OrderBy.
Cada OrderBy pode conter uma das seguintes opções:
- DimensionOrderBy, classifica os resultados pelos valores de uma dimensão.
- MetricOrderBy, classifica os resultados pelos valores de uma métrica.
- PivotOrderBy, usado em consultas dinâmicas e classifica os resultados pelos valores de uma métrica em um grupo de colunas dinâmicas.
Este exemplo mostra um snippet para uma definição dinâmica que dinamiza o relatório na
dimensão browser, ordenando os resultados pela métrica sessions em
ordem decrescente.
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Denunciar resposta
A Resposta de relatório dinâmico de uma solicitação de API de relatório dinâmico é basicamente um cabeçalho e linhas.
Cabeçalhos de resposta
O cabeçalho do relatório dinâmico consiste em PivotHeaders, DimensionHeaders e MetricHeaders que listam as colunas no relatório dinâmico.
Por exemplo, um relatório com as dimensões dinâmicas browser, country e language e a métrica sessions produzirá cabeçalhos como este:
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Chrome"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "United States"
}
]
},
{
"dimensionValues": [
{
"value": "Canada"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "English"
}
]
},
{
"dimensionValues": [
{
"value": "French"
}
]
},
...
],
...
}
],
"dimensionHeaders": [
{
"name": "browser"
},
{
"name": "country"
},
{
"name": "language"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
...
}
O gráfico abaixo ilustra a função de cada componente da resposta de relatório dinâmico na renderização do relatório dinâmico:
Linhas de resposta
A resposta do relatório dinâmico dos métodos runPivotReport e batchRunPivotReports é diferente da resposta dos métodos dos relatórios principais, como runReport e batchRunReports, porque cada linha de resposta do relatório dinâmico representa uma única célula da tabela. Em um relatório normal, uma única linha de resposta representa uma linha de tabela completa.
Veja abaixo um fragmento de resposta de relatório dinâmico para uma
consulta com as dimensões dinâmicas browser, country e language e a
métrica sessions. Cada célula do relatório dinâmico é retornada individualmente:
"rows": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "United States"
},
{
"value": "English"
}
],
"metricValues": [
{
"value": "1"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "Canada"
},
{
"value": "French"
}
],
"metricValues": [
{
"value": "3"
}
]
},
...
]
Esses dados correspondem às duas células destacadas na tabela abaixo:
Bibliotecas de cliente
Consulte o Guia de início rápido para uma explicação sobre como instalar e configurar bibliotecas de cliente.
Confira abaixo um exemplo que usa a biblioteca de cliente Python que executa uma consulta dinâmica para criar um relatório de contagens de sessões por país, dinamizado pela dimensão do navegador.
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import (
DateRange,
Dimension,
Metric,
OrderBy,
Pivot,
RunPivotReportRequest,
)
def run_sample():
"""Runs the sample."""
# TODO(developer): Replace this variable with your Google Analytics 4
# property ID before running the sample.
property_id = "YOUR-GA4-PROPERTY-ID"
run_pivot_report(property_id)
def run_pivot_report(property_id="YOUR-GA4-PROPERTY-ID"):
"""Runs a pivot query to build a report of session counts by country,
pivoted by the browser dimension."""
client = BetaAnalyticsDataClient()
request = RunPivotReportRequest(
property=f"properties/{property_id}",
date_ranges=[DateRange(start_date="2021-01-01", end_date="2021-01-30")],
pivots=[
Pivot(
field_names=["country"],
limit=250,
order_bys=[
OrderBy(
dimension=OrderBy.DimensionOrderBy(dimension_name="country")
)
],
),
Pivot(
field_names=["browser"],
offset=3,
limit=3,
order_bys=[
OrderBy(
metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True
)
],
),
],
metrics=[Metric(name="sessions")],
dimensions=[Dimension(name="country"), Dimension(name="browser")],
)
response = client.run_pivot_report(request)
print_run_pivot_report_response(response)
def print_run_pivot_report_response(response):
"""Prints results of a runPivotReport call."""
print("Report result:")
for row in response.rows:
for dimension_value in row.dimension_values:
print(dimension_value.value)
for metric_value in row.metric_values:
print(metric_value.value)
Aplicativo de demonstração
Consulte o aplicativo de demonstração de relatórios dinâmicos da API Google Analytics v1 para ver um exemplo de como criar e exibir um relatório dinâmico usando o JavaScript.