API данных Google Analytics v1 позволяет создавать сводные таблицы. Сводные таблицы — это инструмент суммирования данных, который визуализирует данные путем изменения порядка информации в таблице путем поворота (поворота) ваших данных по одному или нескольким измерениям.
В качестве примера рассмотрим следующую таблицу необработанных данных:
Используя эти данные, можно построить сводную таблицу, разбивая данные сеансов по браузерам, с параметрами страны и языка, выбранными в качестве дополнительных сводных данных.
Общие функции с основными отчетами
Запросы сводных отчетов имеют ту же семантику, что и запросы основных отчетов для многих общих функций. Например, нумерация страниц, фильтры измерений и свойства пользователя в сводных отчетах ведут себя так же, как и в основных отчетах. В этом руководстве основное внимание уделяется функциям сводных отчетов. Чтобы ознакомиться с основными функциями отчетности Data API v1, прочтите руководство по основам отчетности , а также руководство по расширенным вариантам использования .
Методы сводных отчетов
Data API v1 поддерживает функции сводной таблицы в следующих методах отчетности:
runPivotReport Этот метод возвращает настроенный сводный отчет с данными о событиях Google Analytics. Каждая сводная таблица описывает видимые столбцы и строки измерений в ответе отчета.
BatchRunPivotReports. Это пакетная версия метода
runPivotReport, которая позволяет создавать несколько отчетов с помощью одного вызова API.
Выбор отчитывающейся организации
Все методы API данных версии 1 требуют указания идентификатора свойства Google Analytics внутри пути запроса URL-адреса в форме properties/GA_PROPERTY_ID , например:
POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runPivotReport
Результирующий отчет будет создан на основе данных о событиях Google Analytics, собранных в указанном ресурсе Google Analytics.
Если вы используете одну из клиентских библиотек Data API , нет необходимости вручную манипулировать URL-путем запроса. Большинство клиентов API предоставляют параметр property , который ожидает строку в виде properties/GA_PROPERTY_ID . См. Краткое руководство для примеров использования клиентских библиотек.
Запрос сводного отчета
Чтобы создать запрос со сводной таблицей, используйте метод runPivotReport или метод patchRunPivotReports .
Чтобы запросить сводные данные, вы можете создать объект RunPivotReportRequest . Мы рекомендуем начать со следующих параметров запроса:
- Допустимая запись в поле dateRanges .
- По крайней мере одна действительная запись в поле размеров .
- По крайней мере одна действительная запись в поле метрики .
- По крайней мере две действительные записи сводных данных в поле сводных данных .
Вот пример запроса с рекомендуемыми полями:
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 описывает видимые столбцы и строки измерений в ответе отчета.
API данных версии 1 поддерживает несколько сводных данных, если произведение предельного параметра для каждого сводного значения не превышает 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 указывает город («Париж» или «Нью-Йорк»), в котором произошло каждое событие. В запросе отчета вы можете указать ноль или более измерений.
Размеры должны быть определены внутри поля размеров тела запроса. Чтобы эти измерения были видны в отчете, они также должны быть указаны в поле «Имена полей» объекта 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",
]
},
...
Рассчитанные метрики возвращаются в поле агрегатов объекта 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"
}
]
},
....
}
Пагинация
Подобно основным методам отчетности , сводные запросы позволяют указать поля предела и смещения в объекте Pivot для реализации разбиения на страницы. Настройки пагинации применяются к каждому сводному элементу индивидуально. Поле limit необходимо для каждого объекта Pivot , чтобы ограничить количество элементов отчета.
Data API v1 поддерживает несколько сводных данных, если произведение параметра 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 и patchRunPivotReports отличается от ответа для основных методов отчетности, таких как runReport и patchRunReports , тем, что каждая строка ответа сводного отчета представляет одну ячейку таблицы , тогда как в обычном отчете одна строка ответа представляет полную строку таблицы.
Ниже приведен фрагмент ответа сводного отчета на запрос с параметрами сводной информации о 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() ); } }
Питон
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); }); }); }
Демо-приложение
См. демонстрационное приложение сводного отчета Google Analytics API v1, где приведен пример создания и отображения сводного отчета с использованием JavaScript.