API данных Google Analytics v1 позволяет создавать сводные таблицы. Сводные таблицы — это инструмент суммирования данных, который визуализирует данные путем изменения порядка информации в таблице путем поворота (поворота) ваших данных по одному или нескольким измерениям.
В качестве примера рассмотрим следующую таблицу необработанных данных:
Используя эти данные, можно построить сводную таблицу, разбивая данные сеансов по браузерам, с параметрами страны и языка, выбранными в качестве дополнительных сводных данных.
Общие функции с основными отчетами
Запросы сводных отчетов имеют ту же семантику, что и запросы основных отчетов для многих общих функций. Например, нумерация страниц, фильтры измерений и свойства пользователя в сводных отчетах ведут себя так же, как и в основных отчетах. В этом руководстве основное внимание уделяется функциям сводных отчетов. Чтобы ознакомиться с основными функциями отчетов Data API v1, прочтите руководство по основам создания отчетов , а также руководство по расширенным вариантам использования .
Методы сводных отчетов
Data API v1 поддерживает функции сводной таблицы в следующих методах отчетности:
runPivotReport Этот метод возвращает настроенный сводный отчет с данными о событиях Google Analytics. Каждая сводная таблица описывает видимые столбцы и строки измерений в ответе отчета.
BatchRunPivotReports. Это пакетная версия метода
runPivotReport, которая позволяет создавать несколько отчетов с помощью одного вызова API.
Выбор отчитывающейся организации
Все методы Data API v1 требуют указания идентификатора свойства 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 , чтобы ограничить количество элементов отчета.
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()
);
}
}
Питон
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.