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 "ReportTask" 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 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.

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

• 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 de relatório no campo name (como properties/1234567/reportTasks/123), que pode ser usado em consultas subsequentes para obter 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 saber o estado de todas as tarefas de relatório, chame o método reportTasks.list.

Recuperar 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 (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 com 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"
  }
}