Conceitos básicos das tarefas de relatório

Usando 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 de tarefa de relatório gerado por 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 conclusã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 de dados do Google Analytics v1 usa uma abordagem assíncrona para criar tarefas de relatório. Primeiro, é necessário fazer uma solicitação ao reportTasks.create método para criar uma tarefa de relatório. Em seguida, o reportTasks.query método é 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.

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 URL de solicitação 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 do Google Analytics 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 da 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 como usar as bibliotecas de cliente.

Solicitar a criação da tarefa de relatório

Para criar uma tarefa de relatório, chame o reportTasks.create método usando o ReportTask objeto em uma solicitação. Os seguintes parâmetros são necessários:

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

Pode levar vários minutos para gerar um relatório após a reportTasks.create chamada. Você pode receber o estado de prontidão de uma tarefa de relatório chamando o reportTasks.get método.

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 state campo 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 reportMetadata campo 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
  }
}

Você pode receber o estado de todas as tarefas de relatório chamando o reportTasks.list método.

Recuperar o relatório gerado

Depois que a tarefa de relatório criada usando o reportTasks.create for gerada, chame o 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"
  }
}