API данных Google Аналитики версии 1 позволяет создавать сводные таблицы. Сводные таблицы – это инструмент для обобщения данных, который позволяет визуализировать данные, переставляя информацию в таблице путем поворота данных по одному или нескольким параметрам.
Например, рассмотрим следующую таблицу с необработанными данными:
На основе этих данных можно создать сводную таблицу, в которой данные о сеансах будут разбиты по браузерам, а в качестве дополнительных сводных параметров будут выбраны страна и язык.
Функции, общие с основными отчетами
Запросы отчетов со сводными таблицами имеют ту же семантику, что и запросы основных отчетов, для многих общих функций. Например, разбивка на страницы, фильтры параметров и свойства пользователей работают в сводных отчетах так же, как и в основных. В этом руководстве рассказывается о функциях отчетов со сводными таблицами. Чтобы ознакомиться с основными функциями отчетов Data API v1, прочитайте руководство по основам создания отчетов и руководство по расширенным вариантам использования.
Методы создания сводных отчетов
Data API версии 1 поддерживает функции сводной таблицы в следующих методах создания отчетов:
runPivotReport – метод, который возвращает специальный сводный отчет с данными о событиях Google Аналитики. Каждая сводка описывает видимые столбцы и строки параметров в ответе отчета.
batchRunPivotReports Это пакетная версия метода
runPivotReport, которая позволяет создавать несколько отчетов с помощью одного вызова API.
Как выбрать отчетную организацию
Для всех методов Data API v1 требуется указать идентификатор ресурса Google Аналитики в пути запроса URL в формате properties/GA_PROPERTY_ID, например:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport
Отчет будет создан на основе данных о событиях Google Аналитики, собранных в указанном ресурсе Google Аналитики.
Если вы используете одну из клиентских библиотек Data API, вам не нужно вручную изменять путь URL запроса. Большинство клиентов API предоставляют параметр property, который ожидает строку в форме properties/GA_PROPERTY_ID. Примеры использования клиентских библиотек приведены в кратком руководстве.
Запрос сводного отчета
Чтобы создать запрос со сводной таблицей, используйте метод runPivotReport или batchRunPivotReports.
Чтобы запросить данные, полученные с помощью сводной таблицы, создайте объект RunPivotReportRequest. Рекомендуем начать с следующих параметров запроса:
- Допустимое значение в поле dateRanges.
- Хотя бы одна действительная запись в поле dimensions.
- В поле metrics должно присутствовать хотя бы одно допустимое значение.
- В поле pivots должно быть не менее двух действительных записей о поворотах.
Ниже приведен пример запроса с рекомендуемыми полями.
HTTP
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport
{
"dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
"dimensions": [
{ "name": "browser" },
{ "name": "country" },
{ "name": "language" }
],
"metrics": [{ "name": "sessions" }],
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5
},
{
"fieldNames": [
"country"
],
"limit": 250
},
{
"fieldNames": [
"language"
],
"limit": 15
}
]
}
Сводки
Используйте объекты Pivot в поле pivot тела запроса, чтобы определить сводки отчетов. Каждый элемент Pivot описывает видимые столбцы и строки параметров в ответе на запрос отчета.
Data API версии 1 поддерживает несколько сводок,если произведение параметра limit для каждой из них не превышает 100 000.
В приведенном ниже фрагменте кода показано, как использовать метод pivots для создания отчета о количестве сеансов по странам с разбивкой по параметру browser. Обратите внимание, что в запросе используется поле orderBys для сортировки, а поля limit и offset – для разбивки на страницы.
"pivots": [
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"browser"
],
"offset": 3,
"limit": 3,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
],
...
Размеры
Параметры описывают и группируют данные о событиях на вашем сайте или в приложении. Например, параметр city указывает город ("Париж" или "Нью-Йорк"), из которого поступило каждое событие. В запросе отчета можно указать ноль или более параметров.
Параметры должны быть определены в поле dimensions тела запроса. Чтобы параметры были видны в отчете, они также должны быть указаны в поле fieldNames объекта Pivot.
Параметр не будет виден в отчете, если он не используется ни в одном из сводных запросов. Не все параметры должны присутствовать в элементе fieldNames сводки. Параметры можно использовать только в фильтрах, но не в fieldNames сводной таблицы.
Во фрагменте кода ниже показано, как использовать поля dimension и fieldNames для таблицы со сводками browser, country и language:
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
},
{
"fieldNames": [
"country"
],
"limit": 250,
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
},
{
"fieldNames": [
"language"
],
"limit": 10
}
],
Показатели
Показатели – это количественные данные о событиях на вашем сайте или в приложении. В запросе отчета можно указать один или несколько показателей. Полный список названий показателей API, которые можно указать в запросах, приведен в разделе Показатели API.
В запросах отчетов со сводными таблицами показатели определяются с помощью поля metrics в теле запроса, как и в основных методах создания отчетов.
В следующем примере показано, как указать количество сеансов в качестве значения показателя в отчете:
"metrics": [
{
"name": "sessions"
}
],
Агрегирование показателей
Используйте поле metricAggregations объекта Pivot, чтобы рассчитать агрегированные значения показателей для каждой сводки.
Агрегированные показатели рассчитываются, только если в запросе задано поле metricAggregations.
В приведенном ниже примере показан фрагмент запроса, в котором запрашиваются итоговые значения для параметра сводки browser.
"pivots": [
{
"fieldNames": [
"browser"
],
"limit": 10,
"metricAggregations": [
"TOTAL",
]
},
...
Рассчитанные показатели возвращаются в поле aggregates объекта RunPivotReportResponse. Для строк агрегированных показателей в поле dimensionValues содержится специальное значение: RESERVED_TOTAL, RESERVED_MAX или RESERVED_MIN.
"aggregates": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6"
}
]
},
....
}
Разбивка на страницы
Как и в случае с основными методами создания отчетов, в запросах сводки можно указать поля limit и offset в объекте Pivot, чтобы реализовать разбиение на страницы.
Настройки разбивки на страницы применяются к каждой сводке отдельно.
Поле limit обязательно для каждого объекта Pivot, чтобы ограничить количество уникальных значений в отчете.
В Data API версии 1 поддерживается создание нескольких сводок, а результат параметра limit для каждой сводки не превышает 100 000.
В следующем фрагменте кода показано, как использовать поля offset и limit, чтобы получить следующие пять параметров language со смещением 10:
{
"fieldNames": [
"language"
],
"offset": 10,
"limit": 5
}
Фильтрация
Как и в случае с основными отчетами, если вы хотите отфильтровать параметры в запросе отчета с точкой отсчета, необходимо использовать фильтр параметров на уровне запроса.
Сортировка
Порядок сортировки запросов сводных отчетов можно задать для каждой сводки отдельно, используя поле orderBys объекта Pivot, которое содержит список объектов OrderBy.
Каждый объект OrderBy может содержать один из следующих элементов:
- DimensionOrderBy – сортирует результаты по значениям параметра.
- MetricOrderBy сортирует результаты по значениям показателя.
- PivotOrderBy используется в запросах с поворотом и сортирует результаты по значениям показателя в группе столбцов с поворотом.
В этом примере показан фрагмент кода для определения сводки, в которой отчет сводится по параметру browser, а результаты упорядочиваются по показателю sessions в порядке убывания.
{
"fieldNames": [
"browser"
],
"limit": 5,
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Как пожаловаться на ответ
Ответ на запрос к API для сводного отчета состоит в основном из заголовка и строк.
Заголовки ответа
Заголовок сводного отчета состоит из PivotHeaders, DimensionHeaders и MetricHeaders, в которых перечислены столбцы сводного отчета.
Например, если в отчете есть сводные параметры browser, country и language и показатель sessions, то заголовки будут выглядеть так:
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Chrome"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "United States"
}
]
},
{
"dimensionValues": [
{
"value": "Canada"
}
]
},
...
],
...
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "English"
}
]
},
{
"dimensionValues": [
{
"value": "French"
}
]
},
...
],
...
}
],
"dimensionHeaders": [
{
"name": "browser"
},
{
"name": "country"
},
{
"name": "language"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
...
}
На диаграмме ниже показана роль каждого компонента ответа на запрос сводного отчета при создании этого отчета:
Строки в ответе
Ответ на запрос к методам runPivotReport и batchRunPivotReports отличается от ответа на запрос к методам основного отчета, таким как runReport и batchRunReports, тем, что каждая строка ответа на запрос к сводному отчету представляет собой отдельную ячейку таблицы, тогда как в обычном отчете одна строка ответа представляет собой полную строку таблицы.
В следующем примере показан фрагмент ответа на запрос с параметрами browser, country и language и показателем sessions. Каждая ячейка сводного отчета возвращается отдельно:
"rows": [
{
"dimensionValues": [
{
"value": "Chrome"
},
{
"value": "United States"
},
{
"value": "English"
}
],
"metricValues": [
{
"value": "1"
}
]
},
{
"dimensionValues": [
{
"value": "Firefox"
},
{
"value": "Canada"
},
{
"value": "French"
}
],
"metricValues": [
{
"value": "3"
}
]
},
...
]
Эти данные соответствуют двум ячейкам, выделенным в таблице ниже:
Клиентские библиотеки
Инструкции по установке и настройке клиентских библиотек приведены в кратком руководстве.
В приведенных ниже примерах клиентская библиотека используется для выполнения запроса с поворотом, чтобы создать отчет о количестве сеансов по странам с поворотом по параметру "Браузер".
PHP
use Google\Analytics\Data\V1beta\Client\BetaAnalyticsDataClient; use Google\Analytics\Data\V1beta\DateRange; use Google\Analytics\Data\V1beta\Dimension; use Google\Analytics\Data\V1beta\Metric; use Google\Analytics\Data\V1beta\OrderBy; use Google\Analytics\Data\V1beta\OrderBy\DimensionOrderBy; use Google\Analytics\Data\V1beta\OrderBy\MetricOrderBy; use Google\Analytics\Data\V1beta\Pivot; use Google\Analytics\Data\V1beta\RunPivotReportRequest; use Google\Analytics\Data\V1beta\RunPivotReportResponse; /** * Runs a pivot query to build a report of session counts by country, * pivoted by the browser dimension. * @param string $propertyId Your GA-4 Property ID */ function run_pivot_report(string $propertyId) { // Create an instance of the Google Analytics Data API client library. $client = new BetaAnalyticsDataClient(); // Make an API call. $request = (new RunPivotReportRequest()) ->setProperty('properties/' . $propertyId) ->setDateRanges([new DateRange([ 'start_date' => '2021-01-01', 'end_date' => '2021-01-30', ]), ]) ->setPivots([ new Pivot([ 'field_names' => ['country'], 'limit' => 250, 'order_bys' => [new OrderBy([ 'dimension' => new DimensionOrderBy([ 'dimension_name' => 'country', ]), ])], ]), new Pivot([ 'field_names' => ['browser'], 'offset' => 3, 'limit' => 3, 'order_bys' => [new OrderBy([ 'metric' => new MetricOrderBy([ 'metric_name' => 'sessions', ]), 'desc' => true, ])], ]), ]) ->setMetrics([new Metric(['name' => 'sessions'])]) ->setDimensions([ new Dimension(['name' => 'country']), new Dimension(['name' => 'browser']), ]); $response = $client->runPivotReport($request); printPivotReportResponse($response); } /** * Print results of a runPivotReport call. * @param RunPivotReportResponse $response */ function printPivotReportResponse(RunPivotReportResponse $response) { print 'Report result: ' . PHP_EOL; foreach ($response->getRows() as $row) { printf( '%s %s' . PHP_EOL, $row->getDimensionValues()[0]->getValue(), $row->getMetricValues()[0]->getValue() ); } }
Python
from google.analytics.data_v1beta import BetaAnalyticsDataClient from google.analytics.data_v1beta.types import ( DateRange, Dimension, Metric, OrderBy, Pivot, RunPivotReportRequest, ) def run_sample(): """Runs the sample.""" # TODO(developer): Replace this variable with your Google Analytics 4 # property ID before running the sample. property_id = "YOUR-GA4-PROPERTY-ID" run_pivot_report(property_id) def run_pivot_report(property_id="YOUR-GA4-PROPERTY-ID"): """Runs a pivot query to build a report of session counts by country, pivoted by the browser dimension.""" client = BetaAnalyticsDataClient() request = RunPivotReportRequest( property=f"properties/{property_id}", date_ranges=[DateRange(start_date="2021-01-01", end_date="2021-01-30")], pivots=[ Pivot( field_names=["country"], limit=250, order_bys=[ OrderBy( dimension=OrderBy.DimensionOrderBy(dimension_name="country") ) ], ), Pivot( field_names=["browser"], offset=3, limit=3, order_bys=[ OrderBy( metric=OrderBy.MetricOrderBy(metric_name="sessions"), desc=True ) ], ), ], metrics=[Metric(name="sessions")], dimensions=[Dimension(name="country"), Dimension(name="browser")], ) response = client.run_pivot_report(request) print_run_pivot_report_response(response) def print_run_pivot_report_response(response): """Prints results of a runPivotReport call.""" print("Report result:") for row in response.rows: for dimension_value in row.dimension_values: print(dimension_value.value) for metric_value in row.metric_values: print(metric_value.value)
Node.js
// TODO(developer): Uncomment this variable and replace with your // Google Analytics 4 property ID before running the sample. // propertyId = 'YOUR-GA4-PROPERTY-ID'; // Imports the Google Analytics Data API client library. const {BetaAnalyticsDataClient} = require('@google-analytics/data'); // Initialize client that will be used to send requests. This client only // needs to be created once, and can be reused for multiple requests. const analyticsDataClient = new BetaAnalyticsDataClient(); // Runs a pivot query to build a report of session counts by country, pivoted // by the browser dimension. async function runPivotReport() { const [response] = await analyticsDataClient.runPivotReport({ property: `properties/${propertyId}`, dateRanges: [ { startDate: '2021-01-01', endDate: '2021-01-30', }, ], pivots: [ { fieldNames: ['country'], limit: 250, orderBys: [ { dimension: { dimensionName: 'country', }, }, ], }, { fieldNames: ['browser'], offset: 3, limit: 3, orderBys: [ { metric: { metricName: 'sessions', }, desc: true, }, ], }, ], metrics: [ { name: 'sessions', }, ], dimensions: [ { name: 'country', }, { name: 'browser', }, ], }); printPivotReportResponse(response); } runPivotReport(); // Prints results of a runReport call. function printPivotReportResponse(response) { console.log('Report result:'); response.rows.forEach((row) => { row.dimensionValues.forEach((dimensionValue) => { console.log(dimensionValue.value); }); row.metricValues.forEach((metricValue) => { console.log(metricValue.value); }); }); }
Демонстрационное приложение
Пример того, как создать и показать сводный отчет с помощью JavaScript, можно найти в демонстрационном приложении для сводных отчетов API Google Аналитики (вер. 1).