Conceitos básicos das tarefas de relatório

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.

Observação: as tarefas de relatório estão disponíveis na versão v1alpha da API Data.

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"
  }
}