Conceitos básicos das tarefas de relatório

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 a partir desta solicitação pode ser usado para acessar relatórios personalizados por todos os usuários com acesso de leitura às suas contas do .

Um relatório personalizado vai ficar disponível por 72 horas depois de concluído. Depois disso o recurso de tarefa de relatório correspondente e seu conteúdo 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 reportTasks.create é necessário para criar uma Tarefa de relatório. Depois, 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.

Selecione uma entidade de relatórios

Todos os métodos da API Data v1 exigem a Identificador de propriedade do Google Analytics seja especificado dentro de um caminho de solicitação de URL na forma de properties/GA_PROPERTY_ID, como:

  POST  https://analyticsdata.googleapis.com/v1alpha/properties/GA_PROPERTY_ID/reportTasks

O relatório é gerado com base no evento do Google Analytics dados coletados na propriedade especificada do Google Analytics.

Se você estiver usando uma das bibliotecas de cliente da API Data: não é 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 na forma de properties/GA_PROPERTY_ID. Confira exemplos no Guia de início rápido. do 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 método ReportTask em uma solicitação. Os seguintes parâmetros são necessários:

• reportDefinition que descreve a definição de um relatório personalizado. O valor 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:

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 relatório Nome da tarefa no campo name (como properties/1234567/reportTasks/123), que podem ser usadas em consultas subsequentes para obter o status de uma tarefa de relatório e recuperar os o relatório resultante.

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

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

Pode levar alguns minutos para gerar um relatório depois que o evento reportTasks.create a chamada. Você pode obter o estado de prontidão para uma tarefa de relatório chamando o 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 Tarefa de relatório.

Exemplo:

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123

O status de prontidão de uma Tarefa de relatório é retornado no state de uma resposta. Quando a geração do relatório for concluída, o estado de uma Tarefa de relatório muda de CREATING para ACTIVE.

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

{
  "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 obter o estado de todas as tarefas de relatório chamando o reportTasks.list .

Recuperar o relatório gerado

Depois que a tarefa de relatório for criada usando o reportTasks.create é gerado, chame o método reportTasks.query e especifique o nome da Tarefa de relatório (como properties/1234567/reportTasks/123).

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:

{
  "dimensionHeaders": [
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [

...

  ],
  "rowCount": 167,
  "metadata": {
    "currencyCode": "USD",
    "timeZone": "America/Los_Angeles"
  }
}