Это руководство для разработчиков по Analytics Reporting API v4. Подробную информацию об API см. в справочнике по API .
Отчеты
API отчетов Analytics версии 4 предоставляет метод BatchGet для доступа к ресурсу Reports . В следующих разделах описывается структура тела запроса для batchGet
и структура тела ответа из batchGet
.
Тело запроса
Чтобы использовать API отчетов Google Analytics версии 4 для запроса данных, необходимо создать объект ReportRequest , который соответствует следующим минимальным требованиям:
- Действительный идентификатор представления для поля viewId .
- По крайней мере одна действительная запись в поле dateRanges .
- По крайней мере одна действительная запись в поле метрики .
Чтобы найти идентификатор представления , запросите метод сводки учетных записей или воспользуйтесь проводником учетных записей . Если диапазон дат не указан, диапазон дат по умолчанию: {"startDate": "7daysAgo", "endDate": "yesterday"}
.
Вот пример запроса с минимумом обязательных полей:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:users"}]
}
]
}
Метод batchGet
принимает максимум пять объектов ReportRequest . Все запросы должны иметь одинаковые dateRange
, viewId
, segments
, samplingLevel
и cohortGroup
.
Тело ответа
Тело ответа запроса API представляет собой массив объектов отчета . Структура отчета определяется в объекте ColumnHeader , который описывает измерения и метрики, а также их типы данных в отчете. Значения параметров и показателей указываются в поле данных .
Вот пример ответа на приведенный выше образец запроса:
{
"reports": [
{
"columnHeader": {
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:users",
"type": "INTEGER"
}
]
}
},
"data": {
"isDataGolden": true,
"maximums": [
{
"values": [
"98"
]
}
],
"minimums": [
{
"values": [
"98"
]
}
],
"rowCount": 1,
"rows": [
{
"metrics": [
{
"values": [
"98"
]
}
]
}
],
"totals": [
{
"values": [
"98"
]
}
]
}
}
]
}
Метрики
Метрики — это количественные измерения; для каждого запроса требуется хотя бы один объект Metric .
В следующем примере метрика Sessions
передается в метод batchGet
, чтобы получить общее количество сеансов в указанном диапазоне дат:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [{"startDate": "2014-11-01", "endDate": "2014-11-30"}],
"metrics": [{"expression": "ga:sessions"}]
}
]
}
Вы можете использовать проводник параметров и показателей или API метаданных, чтобы получить список доступных параметров и показателей.
Фильтрация
Отправляя запрос batchGet
, вы можете попросить его возвращать только метрики, соответствующие определенным критериям. Чтобы фильтровать метрики, в теле запроса укажите один или несколько MetricFilterClause и в каждом MetricFilterClause
определите один или несколько MetricFilters . В каждом MetricFilter
укажите следующие значения:
-
metricName
-
not
-
operator
-
comparisonValue
Пусть {metricName}
представляет метрику, {operator}
operator
, а {comparisonValue}
comparisonValue
. Тогда фильтр работает следующим образом:
if {metricName} {operator} {comparisonValue}
return the metric
Если вы укажете true
для not
, фильтр будет работать следующим образом:
if {metricName} {operator} {comparisonValue}
do not return the metric
В следующем примере batchGet
возвращает только просмотры страниц, значение которых больше 2:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"metricFilterClauses": [{
"filters": [{
"metricName": "ga:pageviews",
"operator": "GREATER_THAN",
"comparisonValue": "2"
}]
}]
}]
}
Выражения
Выражение показателя — это математическое выражение, которое вы определяете на основе существующих показателей; он работает как динамические вычисляемые показатели . Вы можете определить псевдоним для представления выражения метрики, например:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{
"expression": "ga:goal1completions/ga:users",
"alias": "completions per user"
}
]
}
]
}
Заказ
Чтобы отсортировать результаты по значению метрики:
- Укажите его имя или псевдоним в поле
fieldName
. - Укажите порядок сортировки (
ASCENDING
илиDESCENDING
) в полеsortOrder
.
В следующем примере batchGet
возвращает метрики, отсортированные сначала по сеансам, а затем по просмотрам страниц в порядке убывания:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics":
[
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"orderBys":
[
{"fieldName": "ga:sessions", "sortOrder": "DESCENDING"},
{"fieldName": "ga:pageviews", "sortOrder": "DESCENDING"}
]
}
]
}
Размеры
Размеры описывают характеристики ваших пользователей, их сеансы и действия. Например, параметр «Город» описывает характеристики сеансов и указывает город («Париж» или «Нью-Йорк»), из которого был создан каждый сеанс. В запросе batchGet
вы можете указать ноль или более объектов измерения , например:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges":
[
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics":
[
{"expression": "ga:users"}
],
"dimensions":
[
{"name": "ga:city"}
]
}
]
}
Фильтрация
Отправляя запрос batchGet
, вы можете попросить его возвращать только те измерения, которые соответствуют определенным критериям. Чтобы фильтровать измерения, в тексте запроса укажите один или несколько DimensionsFilterClauses и в каждом DimensionsFilterClause
определите один или несколько DimensionsFilters . В каждом DimensionsFilters
укажите следующие значения:
-
dimensionName
-
not
-
operator
-
expressions
-
caseSensitive
Пусть {dimensionName}
представляет измерение, {operator}
operator
, а {expressions}
expressions
. Тогда фильтр работает следующим образом:
if {dimensionName} {operator} {expressions}
return the dimension
Если вы укажете true
для not
, фильтр будет работать следующим образом:
if {dimensionName} {operator} {expressions}
do not return the dimension
В следующем примере batchGet
возвращает просмотры страниц и сеансы в браузере Chrome:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"endDate": "2014-11-30", "startDate": "2014-11-01"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:browser"}, {"name": "ga:country"}],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Chrome"]
}
]
}
]
}
]
}
Заказ
Чтобы отсортировать результаты по значению измерения:
- Укажите его имя в поле
fieldName
. - Укажите порядок сортировки (
ASCENDING
илиDESCENDING
) в полеsortOrder
.
Например, следующий batchGet
возвращает измерения, отсортированные по стране, а затем по браузеру:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [{"name": "ga:country"},{"name": "ga:browser"}],
"orderBys": [
{"fieldName": "ga:country"},
{"fieldName": "ga:browser"}
]
}
]
}
Сегменты гистограммы
Характеристики измерений с целочисленными значениями легче понять, разбив их значения на диапазоны. Используйте поле histogramBuckets
, чтобы определить диапазоны результирующих сегментов, и укажите HISTOGRAM_BUCKET
в качестве типа заказа, например:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"metrics": [{"expression": "ga:sessions"}],
"dimensions": [
{
"name": "ga:sessionCount",
"histogramBuckets": ["1","10","100","200","400"]
}
],
"orderBys": [
{
"fieldName": "ga:sessionCount",
"orderType": "HISTOGRAM_BUCKET"
}
]
}
]
}
Несколько диапазонов дат
API отчетов Google Analytics версии 4 позволяет получать данные за несколько диапазонов дат в одном запросе. Независимо от того, указывает ли ваш запрос один или два диапазона дат, данные возвращаются в объекте dateRangeValue , например:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}]
}
]
}
Дельта-заказ
При запросе значений метрики в двух диапазонах дат вы можете упорядочить результаты по разнице значений метрики в диапазонах дат, например:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dateRanges": [
{"startDate": "2014-11-01", "endDate": "2014-11-30"},
{"startDate": "2014-10-01", "endDate": "2014-10-30"}
],
"metrics": [
{"expression": "ga:pageviews"},
{"expression": "ga:sessions"}
],
"dimensions": [{"name": "ga:pageTitle"}],
"orderBys": [
{
"fieldName": "ga:sessions",
"orderType": "DELTA"
}
]
}
]
}
Поведение измерения даты
Если вы запрашиваете измерение, связанное с датой или временем , объект DateRangeValue будет содержать только значения для дат, попадающих в соответствующие диапазоны; все остальные значения, не входящие в указанные диапазоны дат, будут равны 0
.
Например, рассмотрим запрос измерения ga:date
и показателя ga:sessions
в двух диапазонах дат: январь и февраль. В ответе на запрошенные данные за январь значения за февраль будут равны 0
; а в ответе на запрошенные данные за февраль значения за январь будут равны 0
.
Январский отчет
{
"dimensions": [
"20140101" # `ga:date` dimension value for January 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"8"
]
},
{
"values": [ # February DateRangeValue.
"0"
]
}
]
},
...
Отчет за февраль
{
"dimensions": [
"20140201" # `ga:date` dimension value for February 1, 2014.
],
"metrics": [
{
"values": [ # January DateRangeValue.
"0"
]
},
{
"values": [ # February DateRangeValue.
"7"
]
}
]
},
...
Сегменты
Чтобы запросить подмножество данных Google Analytics, используйте сегменты . Например, вы можете определить пользователей из определенной страны или города в одном сегменте, а пользователей, посещающих определенную часть вашего сайта, — в другом. Фильтры возвращают только строки, удовлетворяющие условию, тогда как сегменты возвращают подмножество пользователей, сеансов или событий, соответствующих условиям, содержащим сегменты.
При выполнении запроса с сегментами убедитесь, что:
- Каждый ReportRequest в методе
batchGet
должен содержать идентичные определения сегментов. - Вы добавляете
ga:segment
в список измерений.
Например:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:segment"}, {"name": "ga:browser"}],
"metrics": [{"expression": "ga:sessions"}],
"segments": [
{
"dynamicSegment":
{
"name": "Sessions with Safari browser",
"userSegment":
{
"segmentFilters": [
{
"simpleSegment":
{
"orFiltersForSegment": [
{
"segmentFilterClauses": [
{
"dimensionFilter":
{
"dimensionName": "ga:browser",
"operator": "EXACT",
"expressions": ["Safari"]
}
}]
}]
}
}]
}
}
}]
}]
}
Дополнительные примеры запросов с сегментами см. в разделе «Примеры» .
Идентификатор сегмента
Используйте поле segmentId
для запроса сегментов. Вы не можете использовать одновременно segmentId
и dynamicSegment
для запроса сегментов.
Например:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}, {"name": "ga:segment"}],
"metrics": [{"expression": "ga:users"}],
"segments": [{"segmentId": "gaid::-3"}]
}
]
}
Выборка
Выборка может повлиять на результаты ваших данных и является распространенной причиной того, что значения, возвращаемые API, не соответствуют веб-интерфейсу. Используйте поле samplingLevel
чтобы установить желаемый размер выборки.
- Установите значение
SMALL
для быстрого ответа с меньшим размером выборки. - установите значение
LARGE
для более точного, но более медленного ответа. - установите значение
DEFAULT
для ответа, который сочетает в себе скорость и точность.
Например:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":
[
{
"viewId": "XXXX",
"dimensions": [{"name": "ga:medium"}],
"metrics": [{"expression": "ga:sessions"}],
"samplingLevel": "LARGE"
}
]
}
Если отчет содержит выборочные данные, Analytics Reporting API версии 4 возвращает поля samplesReadCounts
и samplingSpaceSizes
. Если результаты не выбраны, эти поля не будут определены.
Ниже приведен пример ответа, который содержит выборочные данные из запроса с двумя диапазонами дат. Результаты были рассчитаны на основе почти 500 тысяч выборок с размером пространства выборки примерно 15 миллионов сеансов :
{
"reports":
[
{
"columnHeader": {
...
},
"data": {
...
"samplesReadCounts": [ "499630","499630"],
"samplingSpaceSizes": ["15328013","15328013"],
}
}
]
}
Пагинация
API отчетов Analytics версии 4 использует поля pageToken
и pageSize
для разбивки по страницам результатов ответов, охватывающих несколько страниц. Вы получаете pageToken
из параметра nextPageToken
в ответе на запрос reports.batchGet
:
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests":[
{
...
# Taken from `nextPageToken` of a previous response.
"pageToken": "10000",
"pageSize": "10000",
}]
}
Следующий шаг
Теперь, когда вы изучили основы создания отчета, взгляните на расширенные функции API v4.