С помощью задач отчетов можно запустить длительный асинхронный запрос на создание специального отчета о данных событий 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"
}
}
Дальнейшие действия
- Попробуйте интерактивный блокнот Colab для асинхронных задач по созданию отчетов, чтобы создавать, отслеживать и запрашивать асинхронные задачи по созданию отчетов с помощью клиентской библиотеки Python.
- Ознакомьтесь с документацией по
properties.reportTasksREST API. - Подробнее о квотах и ограничениях Data API…