Com a API Data v1 do Google Analytics, você pode gerar tabelas dinâmicas. Tabela dinâmica são uma ferramenta de resumo de dados que visualiza os dados reorganizando informações da tabela dinamizando (girando) os dados em uma ou várias dimensões.
Por exemplo, considere a seguinte tabela de dados brutos:
Com esses dados, é possível construir uma tabela dinâmica, dividindo o dados de sessões por navegador, com as dimensões de país e idioma selecionadas como outras tabelas dinâmicas.
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 usuário Propriedades funcionam da mesma forma nos relatórios dinâmicos que os relatórios principais. Isso foca nos recursos de relatórios dinâmicos. Para se familiarizar com o Core Recursos de relatórios da API Data v1. Leia o guia de noções básicas sobre geração de relatórios. , bem como o guia de casos de uso avançados.
Métodos de geração de relatórios dinâmicos
A API Data v1 oferece suporte à funcionalidade de tabela dinâmica nos seguintes métodos de geração de relatórios:
runPivotReport. Esse método retorna um relatório dinâmico personalizado dos seus dados de eventos do Google Analytics. Cada pivot descreve as colunas e linhas de dimensões 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.
Selecionar uma entidade denunciante
Todos os métodos da API Data v1 exigem o identificador de propriedade do Google Analytics.
seja especificado dentro de um caminho de solicitação de URL na forma de
properties/GA_PROPERTY_ID, como:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport
O relatório resultante será gerado com base nos dados de eventos do Google Analytics. coletados na propriedade especificada do Google Analytics.
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/GA_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 runPivotReport ou o batchRunPivotReports .
Para solicitar dados dinamizados, construa um objeto RunPivotReportRequest objeto. 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 um exemplo de solicitação com os campos recomendados:
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_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
Usar objetos Pivot no campo pivot da solicitação
para definir tabelas dinâmicas. Cada Pivot descreve a dimensão visível
colunas e linhas na resposta do relatório.
A API Data v1 oferece suporte a várias tabelas dinâmicas, desde que o produto do limite para cada tabela dinâmica não excede 100.000.
Veja abaixo um snippet que demonstra o uso de pivots para criar um relatório de
contagens de sessões por país, dinamizadas pela dimensão browser. Observe como o
consulta usa o campo orderBys para
classificação, e o limite e
Campos offset para implementar 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
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, é possível
especificar zero ou mais dimensões.
As dimensões devem ser definidas dentro do
dimensões
do corpo de uma solicitação. Para serem exibidas em um relatório, essas dimensões também precisam
ser listado no campo fieldNames
campo de um objeto Pivot.
Uma dimensão não ficará visível em um relatório se não for usada em nenhum
tabela dinâmica de uma consulta dinâmica. Nem toda dimensão deve estar presente
fieldNames: As dimensões podem ser usadas exclusivamente nos filtros,
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
Métricas são medidas quantitativas de dados de eventos para seu site ou app. Em uma solicitação de relatório, você pode especificar uma ou mais métricas. Consulte a lista completa de nomes de métricas da API em Métricas da API disponíveis para serem especificados nas solicitações.
Nas solicitações de relatórios dinâmicos, as métricas são definidas usando o campo metrics da
corpo da solicitação, que é semelhante aos principais métodos de relatórios.
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
Usar as metricAggregations campo de um objeto Pivot para calcular a métrica agregada valores para cada tabela dinâmica.
As agregações só serão calculadas se o campo metricAggregations for especificado em uma solicitação.
Abaixo está um snippet de uma consulta que solicita os totais para
browser dimensão dinâmica:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
As métricas calculadas são retornadas nas agregações.
do campo RunPivotReportResponse
objeto. 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, com as solicitações dinâmicas, você
para especificar o limite
e offset 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 a fim de limitar o
cardinalidade de 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.
Abaixo está um snippet que demonstra o uso dos campos offset e limit para
recupere as próximas cinco dimensões de language com um deslocamento de 10:
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
Filtragem
Semelhante à funcionalidade principal de relatórios, um filtro de dimensão no escopo da solicitação precisará ser usado se a filtragem de dimensões for desejada em um relatório dinâmico solicitação.
Classificação
O comportamento de ordenação das consultas do relatório dinâmico pode ser controlado para cada tabela dinâmica individualmente usando orderBys campo de um objeto Pivot, que contém uma lista de OrderBy.
Cada OrderBy pode conter um dos itens a seguir:
- DimensionOrderBy, classifica os resultados pelos valores de uma dimensão.
- MetricOrderBy, classifica resultados pelos valores de uma métrica.
- PivotOrderBy, usado na dinâmica as consultas e classifica os resultados pelos valores de uma métrica. dentro de um grupo de colunas dinâmicas.
Este exemplo mostra um snippet de uma definição de tabela dinâmica que dinamiza o relatório
a dimensão browser, ordenando os resultados pela métrica sessions na
em ordem decrescente.
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Denunciar resposta
A Resposta do relatório dinâmico de uma tabela dinâmica. da API de relatórios é principalmente 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 na 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ão cabeçalhos como estes:
{
"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 do Relatório dinâmico Resposta na renderização do relatório dinâmico:
Linhas de resposta
A resposta do relatório dinâmico de runPivotReport e batchRunPivotReports diferente de uma resposta para os métodos de relatórios principais como runReport e batchRunReports porque cada linha de resposta do relatório dinâmico representa uma única célula do tabela. Já em um relatório regular, uma única linha de resposta representa uma consulta linha da tabela.
Veja abaixo um fragmento de uma resposta de relatório dinâmico para um
com as dimensões dinâmicas browser, country e language e a
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 ver uma explicação sobre como instalar e configurar bibliotecas de cliente.
Os exemplos a seguir usam a biblioteca de cliente para executar uma consulta dinâmica e criar uma relatório de contagens de sessões por país, dinamizado pela dimensão do navegador.
PHP
use Google\Analytics\Data\V1beta\Client\BetaAnalyticsDataClient; use Google\Analytics\Data\V1beta\DateRange; use Google\Analytics\Data\V1beta\Dimension; use Google\Analytics\Data\V1beta\Metric; use Google\Analytics\Data\V1beta\OrderBy; use Google\Analytics\Data\V1beta\OrderBy\DimensionOrderBy; use Google\Analytics\Data\V1beta\OrderBy\MetricOrderBy; use Google\Analytics\Data\V1beta\Pivot; use Google\Analytics\Data\V1beta\RunPivotReportRequest; use Google\Analytics\Data\V1beta\RunPivotReportResponse; /** * Runs a pivot query to build a report of session counts by country, * pivoted by the browser dimension. * @param string $propertyId Your GA-4 Property ID */ function run_pivot_report(string $propertyId) { // Create an instance of the Google Analytics Data API client library. $client = new BetaAnalyticsDataClient(); // Make an API call. $request = (new RunPivotReportRequest()) ->setProperty('properties/' . $propertyId) ->setDateRanges([new DateRange([ 'start_date' => '2021-01-01', 'end_date' => '2021-01-30', ]), ]) ->setPivots([ new Pivot([ 'field_names' => ['country'], 'limit' => 250, 'order_bys' => [new OrderBy([ 'dimension' => new DimensionOrderBy([ 'dimension_name' => 'country', ]), ])], ]), new Pivot([ 'field_names' => ['browser'], 'offset' => 3, 'limit' => 3, 'order_bys' => [new OrderBy([ 'metric' => new MetricOrderBy([ 'metric_name' => 'sessions', ]), 'desc' => true, ])], ]), ]) ->setMetrics([new Metric(['name' => 'sessions'])]) ->setDimensions([ new Dimension(['name' => 'country']), new Dimension(['name' => 'browser']), ]); $response = $client->runPivotReport($request); printPivotReportResponse($response); } /** * Print results of a runPivotReport call. * @param RunPivotReportResponse $response */ function printPivotReportResponse(RunPivotReportResponse $response) { print 'Report result: ' . PHP_EOL; foreach ($response->getRows() as $row) { printf( '%s %s' . PHP_EOL, $row->getDimensionValues()[0]->getValue(), $row->getMetricValues()[0]->getValue() ); } }
Python
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)
Node.js
// TODO(developer): Uncomment this variable and replace with your // Google Analytics 4 property ID before running the sample. // propertyId = Y'OUR-GA4-PROPERTY-ID;' // Imports the Google Analytics Data API client library. const {BetaAnalyticsDataClient} = require(@'google-analytics/data)'; // Initialize client that will be used to send requests. This client only // needs to be created once, and can be reused for multiple requests. const analyticsDataClient = new BetaAnalyticsDataClient(); // Runs a pivot query to build a report of session counts by country, pivoted by the browser dimension. async function runPivotReport() { const [response] = await analyticsDataClient.runPivotReport({ property: `properties/${propertyId}`, dateRanges: [ { startDate: 2'021-01-01,' endDate: 2'021-01-30,' }, ], pivots: [ { fieldNames: [c'ountry]', limit: 250, orderBys: [ { dimension: { dimensionName: c'ountry,' }, }, ], }, { fieldNames: [b'rowser]', offset: 3, limit: 3, orderBys: [ { metric: { metricName: s'essions,' }, desc: true, }, ], }, ], metrics: [ { name: s'essions,' }, ], dimensions: [ { name: c'ountry,' }, { name: b'rowser,' }, ], }); printPivotReportResponse(response); } runPivotReport(); // Prints results of a runReport call. function printPivotReportResponse(response) { console.log(R'eport result:)'; response.rows.forEach(row = >{ row.dimensionValues.forEach(dimensionValue = >{ console.log(dimensionValue.value); }); row.metricValues.forEach(metricValue = >{ console.log(metricValue.value); }); }); }r
Aplicativo de demonstração
Consulte a Demonstração de relatório dinâmico da API Google Analytics v1 aplicativo para um exemplo de como criar e exibir um relatório dinâmico usando JavaScript.