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

С помощью задач отчетов можно запустить длительный асинхронный запрос на создание специального отчета о данных событий 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. Обязательные параметры:

  • Поле reportDefinition, в котором описывается определение специального отчета. Структура этого параметра аналогична определению отчета, используемому методами Core Reporting.

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

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

Дальнейшие действия