Com as tarefas de relatório, é possível 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 de tarefa do relatório gerado a partir dessa solicitação pode ser usado para acessar relatórios personalizados por todos os usuários com acesso de leitura à sua propriedade do Google Analytics.
Um relatório personalizado fica disponível por 72 horas após a criação. Após esse período, o recurso de tarefa de relatório correspondente e o conteúdo dele serão excluídos automaticamente.
Criar uma tarefa de relatório
A API Google Analytics Data v1 usa uma abordagem assíncrona para criar tarefas de relatório. Primeiro, uma solicitação ao método
reportTasks.create
é necessária para criar uma tarefa de relatório. Em seguida, o método
reportTasks.query
é usado para recuperar o relatório personalizado gerado.
Além disso, é possível usar
reportTasks.get
para extrair 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ório
Todos os métodos da API Data v1 exigem que o identificador da propriedade do Google Analytics seja especificado em um caminho de solicitação de URL no formato properties/GA_PROPERTY_ID
, como:
POST https://analyticsdata.googleapis.com/v1alpha/properties/GA_PROPERTY_ID/reportTasks
O relatório é gerado com base nos dados de eventos do Google Analytics coletados na propriedade especificada.
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 espera uma
string no formato properties/GA_PROPERTY_ID
.
Consulte o guia de início rápido para conferir exemplos
de como usar as 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 objeto
ReportTask
em uma solicitação. Os seguintes parâmetros são necessários:
- Campo
reportDefinition
, que descreve a definição de um relatório personalizado. A estrutura desse parâmetro é semelhante à definição de relatório usada pelos métodos de relatórios básicos.
Exemplo de solicitação de criação de tarefa de relatório:
Solicitação HTTP
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 nome da tarefa de relatório no campo name
(como properties/1234567/reportTasks/123
), que pode ser usado em consultas subsequentes para receber o status de uma tarefa de relatório e extrair o relatório resultante.
Resposta HTTP
{
"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"
}
}
}
Receber o estado de prontidão da tarefa de relatório
Pode levar vários minutos para gerar um relatório após a
chamada
reportTasks.create
. Para conferir o estado de prontidão de uma tarefa de relatório, chame o
método
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 a
tarefa de relatório.
Exemplo:
Solicitação HTTP
GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123
O status de prontidão de uma tarefa de relatório é retornado no campo
state
de uma resposta. Quando a geração do relatório é concluída,
o estado de uma tarefa de relatório muda de CREATING
para ACTIVE
.
O campo reportMetadata
contém informações gerais sobre o relatório gerado, como
a contagem de linhas e a quantidade de tokens de cota cobrados.
Resposta HTTP
{
"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
}
}
É possível conferir o estado de todas as tarefas de relatório chamando o
método
reportTasks.list
.
Extrair o relatório gerado
Depois que a tarefa de relatório criada usando o método
reportTasks.create
for gerada, chame o método
reportTasks.query
e especifique o nome da tarefa de relatório
(por exemplo, properties/1234567/reportTasks/123
).
Solicitação HTTP
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:
Resposta HTTP
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
...
],
"rowCount": 167,
"metadata": {
"currencyCode": "USD",
"timeZone": "America/Los_Angeles"
}
}