Основные сведения о задачах в отчетах

С помощью задач отчетов можно запустить длительный асинхронный запрос на создание специального отчета с данными о событиях Google Аналитики.

Ресурс задачи отчета, созданный на основе этого запроса, может использоваться для доступа к специальным отчетам всеми пользователями с правом на чтение данных вашего ресурса Google Аналитики.

Специальный отчет будет доступен в течение 72 часов после создания. По истечении этого срока ресурс задачи отчета и его содержимое будут автоматически удалены.

Как создать задачу для отчета

В Google Analytics Data API версии 1 для создания задач отчетов используется асинхронный подход. Сначала необходимо отправить запрос к методу reportTasks.create, чтобы создать задачу отчета. Затем с помощью метода reportTasks.query можно получить созданный специальный отчет.

Кроме того, вы можете использовать reportTasks.get, чтобы получить метаданные конфигурации для определенной задачи создания отчета, и reportTasks.list, чтобы получить список всех задач создания отчетов для ресурса.

Как выбрать отчетную организацию

Для всех методов Data API версии 1 требуется, чтобы идентификатор ресурса Google Аналитики был указан в пути запроса URL в формате properties/GA_PROPERTY_ID, например:

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

Отчет создается на основе данных о событиях Google Аналитики, собранных в указанном ресурсе Google Аналитики.

Если вы используете одну из клиентских библиотек Data API, вам не нужно вручную изменять путь URL запроса. Большинство клиентов API предоставляют параметр property, который ожидает строку в форме properties/GA_PROPERTY_ID. Примеры использования клиентских библиотек приведены в руководстве по началу работы.

Запросить создание задачи для отчета

Чтобы создать задачу отчета, вызовите метод reportTasks.create, используя объект ReportTask в запросе. Обязательные параметры:

Пример запроса на создание задачи для отчета:

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

Ответ метода reportTasks.create содержит название задачи создания отчета в поле name (например, properties/1234567/reportTasks/123), которое можно использовать в последующих запросах, чтобы получить статус задачи создания отчета и извлечь полученный отчет.

Ответ 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"
    }
  }
}

Как получить статус готовности задачи создания отчета

После вызова функции reportTasks.create создание отчета может занять несколько минут. Чтобы узнать статус готовности задачи отчета, вызовите метод reportTasks.get.

Используйте название задачи отчета (например, properties/1234567/reportTasks/123), полученное в ответе reportTasks.create, чтобы указать задачу отчета.

Пример:

HTTP-запрос.

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

Статус готовности задачи отчета возвращается в поле ответа state. После того как отчет будет создан, статус задачи изменится с CREATING на ACTIVE.

Поле reportMetadata содержит общую информацию о созданном отчете, например количество строк и количество использованных токенов квоты.

Ответ 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
  }
}

Чтобы получить информацию о состоянии всех задач, связанных с отчетами, вызовите метод reportTasks.list.

Как получить сгенерированный отчет

Когда задача создания отчета, созданная с помощью метода reportTasks.create, будет выполнена, вызовите метод reportTasks.query и укажите название задачи создания отчета (например, properties/1234567/reportTasks/123).

HTTP-запрос.

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

Если задача по созданию отчета готова, возвращается ответ, содержащий сгенерированный отчет:

Ответ HTTP

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

...

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