Com as tarefas de relatório, você pode iniciar uma solicitação assíncrona de longa duração para criar um relatório personalizado dos dados de eventos do Google Analytics.
O recurso Tarefa de relatório gerado a partir desta solicitação pode ser usado para acessar relatórios personalizados por todos os usuários com acesso de leitura às suas contas do .
Um relatório personalizado vai ficar disponível por 72 horas depois de concluído. Depois disso o recurso de tarefa de relatório correspondente e seu conteúdo serão excluídos automaticamente.
Criar uma tarefa de relatório
A API Data v1 do Google Analytics usa uma abordagem assíncrona para
criar tarefas de relatório. Primeiro, uma solicitação
reportTasks.create
é necessário para criar uma Tarefa de relatório. Depois,
reportTasks.query
é usado para recuperar o relatório personalizado gerado.
Além disso, você pode usar
reportTasks.get
para recuperar metadados de configuração sobre uma tarefa de relatório específica e
reportTasks.list
para listar todas as tarefas de relatório de uma propriedade.
Selecione uma entidade de relatórios
Todos os métodos da API Data v1 exigem a
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/v1alpha/properties/GA_PROPERTY_ID/reportTasks
O relatório é gerado com base no evento do Google Analytics dados coletados na propriedade especificada do Google Analytics.
Se você estiver usando uma das bibliotecas de cliente da API Data:
não é necessário manipular manualmente o caminho do URL da solicitação.
A maioria dos clientes de API fornece um parâmetro property que espera uma
string na forma de properties/GA_PROPERTY_ID.
Confira exemplos no Guia de início rápido.
do uso das bibliotecas de cliente.
Solicitar a criação da tarefa de relatório
Para criar uma tarefa de relatório, chame o método
reportTasks.create
usando o método
ReportTask
em uma solicitação. Os seguintes parâmetros são necessários:
reportDefinitionque descreve a definição de um relatório personalizado. O valor desse parâmetro é semelhante à definição de relatório usada pelos métodos de relatórios principais.
Exemplo de solicitação de criação de tarefa de relatório:
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks
{
"reportDefinition": {
"dateRanges": [{ "startDate": "2024-05-01" ", "endDate": "2024-05-15 " }],
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }]
}
}
Uma resposta do método reportTasks.create contém o relatório
Nome da tarefa no campo name (como
properties/1234567/reportTasks/123), que podem ser usadas em
consultas subsequentes para obter o status de uma tarefa de relatório e recuperar os
o relatório resultante.
{
"response": {
"@type": "type.googleapis.com/google.analytics.data.v1alpha.ReportTask",
"name": "properties/1234567/reportTasks/123",
"reportDefinition": {
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
]
},
"reportMetadata": {
"state": "CREATING",
"beginCreatingTime": "2024-05-16T00:00:01.133612336Z"
}
}
}
Ver o estado de prontidão da tarefa de relatório
Pode levar alguns minutos para gerar um relatório depois que o evento
reportTasks.create
a chamada. Você pode obter o estado de prontidão para uma tarefa de relatório chamando o
reportTasks.get
.
Use o nome da Tarefa de relatório (como properties/1234567/reportTasks/123)
que você recebeu de uma resposta reportTasks.create para especificar
Tarefa de relatório.
Exemplo:
GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123
O status de prontidão de uma Tarefa de relatório é retornado no
state
de uma resposta. Quando a geração do relatório for concluída,
o estado de uma Tarefa de relatório muda de CREATING para ACTIVE.
O reportMetadata
contém as informações de alto nível sobre o relatório gerado, como
a contagem de linhas e a quantidade de tokens de cota cobrados.
{
"reportDefinition": {
"dimensions": [
{
"name": "country"
}
],
"metrics": [
{
"name": "activeUsers"
}
],
"dateRanges": [
{
"startDate": "2024-05-01",
"endDate": "2024-05-15"
}
]
},
"reportMetadata": {
"state": "ACTIVE",
"beginCreatingTime": "2024-05-16T00:00:01.133612336Z",
"creationQuotaTokensCharged": 6,
"taskRowCount": 167,
"errorMessage": "",
"totalRowCount": 167
}
}
Você pode obter o estado de todas as tarefas de relatório chamando o
reportTasks.list
.
Recuperar o relatório gerado
Depois que a tarefa de relatório for criada usando o
reportTasks.create
é gerado, chame o método
reportTasks.query
e especifique o nome da Tarefa de relatório
(como properties/1234567/reportTasks/123).
POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query
Se a Tarefa de relatório estiver pronta, uma resposta contendo o relatório gerado será retornada:
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
...
],
"rowCount": 167,
"metadata": {
"currencyCode": "USD",
"timeZone": "America/Los_Angeles"
}
}