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 com base nessa solicitação pode ser usado para acessar relatórios personalizados de todos os usuários com acesso de leitura à sua propriedade do Google Analytics.
Um relatório personalizado estará disponível por 72 horas após ser concluído. Após esse período, o recurso da tarefa de relatório correspondente e o conteúdo dele 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 para o 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 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.
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/v1alpha/properties/GA4_PROPERTY_ID/reportTasks
O relatório é gerado com base nos dados de eventos do Google Analytics coletados na propriedade especificada do GA4.
Se 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 de properties/GA4_PROPERTY_ID.
Consulte o Guia de início rápido para 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:
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 principais.
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
do relatório no campo name (como
properties/1234567/reportTasks/123), que pode ser usado em
consultas subsequentes para conferir o status de uma tarefa de relatório e recuperar 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"
}
}
}
Acessar o estado de prontidão da tarefa de relatório
Após a chamada reportTasks.create, pode levar alguns minutos para gerar um relatório. É possível saber o estado de prontidão de uma tarefa de relatório chamando 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 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.
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 saber o estado de todas as tarefas de relatórios chamando o
método
reportTasks.list.
Recuperar o relatório gerado
Depois que a tarefa de relatório criada com o método
reportTasks.create
for gerada, chame o método
reportTasks.query
e especifique o nome da tarefa de relatório,
como 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"
}
}