Princípios 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 de relatório gerado com essa 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, é necessário fazer uma solicitação ao método reportTasks.create 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 de relatórios

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 é necessário manipular o caminho do URL da solicitação manualmente. 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 exemplos de 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 objeto ReportTask em uma solicitação. Os seguintes parâmetros são necessários:

• O campo reportDefinition descreve a definição de um relatório personalizado. A estrutura desse parâmetro é semelhante à definição de relatório usada pelos métodos do Core Reporting.

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

Receber o estado de prontidão da tarefa de relatório

A geração de um relatório pode levar vários minutos após a chamada reportTasks.create. Para saber 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 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
  }
}

Para conferir o estado de todas as tarefas de relatório, chame o método reportTasks.list.

Recuperar o relatório gerado

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