В этом документе представлены инструкции по переносу существующего кода из Google Analytics Reporting API v4 в Google Analytics Data API v1 , а также дается краткий обзор ключевых различий между двумя API.
Почему мне нужно мигрировать
Если вашему приложению требуется доступ к данным в ресурсе Google Analytics 4, необходимо обновить код для использования Data API v1, поскольку Reporting API v4 может получать доступ только к ресурсам, созданным с помощью Universal Analytics.
Предварительные условия
Пожалуйста, ознакомьтесь с основами работы Data API v1 с помощью краткого руководства .
Начиная
Для начала вы подготовите ресурс Google Analytics 4, включите Data API v1, а затем настроите клиентскую библиотеку API, подходящую для вашей платформы.
Подготовьте ресурс Google Аналитики 4.
Прежде чем приступить к переносу кода для поддержки Data API v1, вам необходимо перенести свой веб-сайт на использование ресурса Google Analytics 4 . Невозможно заполнить ресурс Google Analytics 4 историческими данными из ресурса Universal Analytics.
Включить API
Нажмите эту кнопку, чтобы автоматически включить Data API v1 в выбранном вами проекте Google Cloud.
Включите API данных Google Analytics v1.Использование клиентской библиотеки
Установить клиентскую библиотеку
Если вы используете клиентскую библиотеку, вам необходимо установить клиентскую библиотеку Data API v1 для вашего языка программирования.
Джава
Питон
Node.js
.СЕТЬ
PHP
Идти
go get google.golang.org/genproto/googleapis/analytics/data/v1beta
Инициализировать клиентскую библиотеку
Клиентские библиотеки Data API v1 были разработаны для быстрого начала работы. По умолчанию клиентские библиотеки пытаются автоматически найти учетные данные вашей сервисной учетной записи .
Простой способ предоставить учетные данные учетной записи службы — установить переменную среды GOOGLE_APPLICATION_CREDENTIALS . Клиент API будет использовать значение этой переменной для поиска JSON-файла ключа учетной записи службы.
Например, вы можете установить учетные данные учетной записи службы, выполнив следующую команду и указав путь к файлу JSON учетной записи службы:
export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"
Ниже приведены фрагменты кода, которые обычно используются для инициализации клиентских библиотек Data API v1.
Джава
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
try (BetaAnalyticsDataClient analyticsData = BetaAnalyticsDataClient.create()) {
Питон
# Using a default constructor instructs the client to use the credentials
# specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
client = BetaAnalyticsDataClient()
.СЕТЬ
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
BetaAnalyticsDataClient client = BetaAnalyticsDataClient.Create();
PHP
// Using a default constructor instructs the client to use the credentials // specified in GOOGLE_APPLICATION_CREDENTIALS environment variable. $client = new BetaAnalyticsDataClient();
Node.js
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Using a default constructor instructs the client to use the credentials
// specified in GOOGLE_APPLICATION_CREDENTIALS environment variable.
const analyticsDataClient = new BetaAnalyticsDataClient();
Вместо использования переменной среды также можно явно передать информацию об учетных данных экземпляру клиента API во время инициализации. Ниже приведены фрагменты, используемые для инициализации клиентских библиотек Data API v1 путем явной передачи учетных данных в коде.
Джава
// Explicitly use service account credentials by specifying
// the private key file.
GoogleCredentials credentials =
GoogleCredentials.fromStream(new FileInputStream(credentialsJsonPath));
BetaAnalyticsDataSettings betaAnalyticsDataSettings =
BetaAnalyticsDataSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credentials))
.build();
try (BetaAnalyticsDataClient analyticsData =
BetaAnalyticsDataClient.create(betaAnalyticsDataSettings)) {
Питон
# TODO(developer): Uncomment this variable and replace with a valid path to
# the credentials.json file for your service account downloaded from the
# Cloud Console.
# credentials_json_path = "/path/to/credentials.json"
# Explicitly use service account credentials by specifying
# the private key file.
client = BetaAnalyticsDataClient.from_service_account_json(credentials_json_path)
.СЕТЬ
/**
* TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
* Otherwise, default service account credentials will be derived from
* the GOOGLE_APPLICATION_CREDENTIALS environment variable.
*/
// credentialsJsonPath = "/path/to/credentials.json";
// Explicitly use service account credentials by specifying
// the private key file.
BetaAnalyticsDataClient client = new BetaAnalyticsDataClientBuilder
{
CredentialsPath = credentialsJsonPath
}.Build();
PHP
/**
* @param string $credentialsJsonPath Valid path to the credentials.json file for your service
* account downloaded from the Cloud Console.
* Example: "/path/to/credentials.json"
*/
function client_from_json_credentials(string $credentialsJsonPath)
{
// Explicitly use service account credentials by specifying
// the private key file.
$client = new BetaAnalyticsDataClient([
'credentials' => $credentialsJsonPath
]);
return $client;
}
Node.js
/** TODO(developer): Uncomment this variable and replace with a valid path to
* the credentials.json file for your service account downloaded from the
* Cloud Console.
*/
// credentialsJsonPath = '/path/to/credentials.json';
// Imports the Google Analytics Data API client library.
const {BetaAnalyticsDataClient} = require('@google-analytics/data');
// Explicitly use service account credentials by specifying
// the private key file.
const analyticsDataClient = new BetaAnalyticsDataClient({
keyFilename: credentialsJsonPath,
});
Не использовать клиентскую библиотеку
Если вы использовали API отчетов версии 4 без клиентской библиотеки и хотите продолжать использовать API данных версии 1, вы все равно можете использовать свои учетные данные.
Вам необходимо использовать новую конечную точку HTTP и документ обнаружения, предоставленный Data API:
Если ваш код использует документ обнаружения , вам необходимо обновить его до документа обнаружения, предоставленного Data API v1:
После обновления конечной точки вам необходимо будет ознакомиться с новой структурой запроса и концепциями API данных, чтобы обновить запрос JSON.
Основная отчетность
Доступные методы отчетности
Reporting API v4 предлагал один метод пакетного получения доступа к своим основным функциям отчетности. Data API v1 предоставляет на выбор несколько основных методов отчетности:
- runReport Этот метод возвращает настроенный отчет о данных событий Google Analytics. Он не поддерживает функцию сводной таблицы и является предпочтительным методом для простых запросов отчетов.
- runPivotReport Этот метод возвращает настроенный сводный отчет с данными о событиях Google Analytics. Подобно сводным таблицам в Reporting API версии 4, каждая сводная таблица описывает видимые столбцы и строки измерений в ответе отчета.
- BatchRunReports. Это пакетная версия метода
runReport, которая позволяет создавать несколько отчетов с помощью одного вызова API. - BatchRunPivotReports. Это пакетная версия метода
runPivotReport, которая позволяет создавать несколько отчетов с помощью одного вызова API.
Целью использования нескольких методов отчетности в основном является удобство: некоторые методы поддерживают более сложные функции, чем другие (повороты, пакетная обработка), но в остальном имеют схожую структуру запроса.
Изменения схемы API
Возможности отчетов как Reporting API, так и Data API в первую очередь определяются их схемой, т. е. измерениями и метриками, поддерживаемыми в запросах отчетов. В схемах API между двумя API существуют существенные различия из-за концептуальных различий между Universal Analytics и Google Analytics 4.
- Ознакомьтесь с текущим списком параметров и показателей, поддерживаемых Data API. В настоящее время все параметры и показатели совместимы друг с другом, поэтому нет необходимости использовать Обозреватель измерений и показателей для определения совместимых комбинаций. Такое поведение изменится в будущем.
- Доступ к специальным параметрам в Google Analytics 4 можно получить с помощью синтаксиса специальных параметров Data API версии 1, который следует использовать вместо слотов измерений ga:dimensionXX в Reporting API версии 4.
- Доступ к специальным метрикам в Google Analytics 4 можно получить с помощью синтаксиса пользовательских метрик Data API v1, который следует использовать вместо слотов метрик ga:metricXX в Reporting API v4.
- Некоторые параметры и показатели, найденные в Universal Analytics, имеют прямой эквивалент в Google Analytics 4. Дополнительную информацию см. в таблице эквивалентности схемы API UA/GA4 .
- Названия параметров и показателей больше не имеют префикса
ga:в Google Analytics 4. - Некоторые функции Universal Analytics пока недоступны в GA4 (например, Менеджер кампаний, DV360, интеграция Search Ads 360). Как только эта функция будет реализована в Google Analytics 4, API данных будет поддерживать ее, а в схему API будут добавлены новые измерения и показатели.
Сущности
В Google Analytics 4 нет концепции представлений (профилей), представленной в Universal Analytics. В результате в запросах отчетов Data API v1 отсутствует параметр viewId . Вместо этого в URL-пути запроса при вызове методов Data API v1 следует указать числовой идентификатор ресурса Google Analytics 4 . Это поведение отличается от API отчетов версии 4, который использует идентификаторы представления (профиля) для идентификации объекта отчетности.
API данных v1
В случае Data API v1 в URL-пути необходимо указать числовой идентификатор ресурса Google Analytics 4.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
API отчетности v4
Reporting API v4 требует, чтобы идентификатор представления (профиля) Universal Analytics был указан в тексте запроса отчета.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
....
Если вы используете одну из клиентских библиотек Data API , нет необходимости вручную манипулировать URL-путем запроса. Большинство клиентов API предоставляют параметр property , который ожидает строку в виде properties/GA4_PROPERTY_ID . См. Краткое руководство для примеров использования клиентских библиотек.
Диапазоны дат
И Reporting API v4, и Data API v1 поддерживают несколько диапазонов дат, заданных с помощью поля dateRanges в запросе отчета. Оба API используют один и тот же формат ввода даты, принимая абсолютные значения даты в форме YYYY-MM-DD или относительные даты, такие как yesderday , today , 7daysAgo и т. д.
Запросы API данных версии 1 ограничены четырьмя диапазонами дат, тогда как API отчетов версии 4 допускает использование двух диапазонов дат в одном запросе отчета.
Каждый dateRange в Data API v1 может иметь необязательное поле name , которое можно использовать для ссылки на соответствующий диапазон дат в ответе. Если name не указано, имя диапазона дат генерируется автоматически.
Если в запросе Data API v1 указано несколько диапазонов дат , к ответу автоматически добавляется новое измерение dateRange , а имя диапазона дат используется в качестве значения измерения. Обратите внимание, что это поведение отличается от API отчетов версии 4, который возвращает данные за диапазон дат в виде группы значений показателей в каждой строке.
Запрос API данных v1
Необязательное поле name используется для каждого значения dateRange в запросе. Это имя диапазона дат будет использоваться в качестве значения измерения dateRange в ответе.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
"name": "year_ago"
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
"name": "current_year"
}
]
}
Ответ API данных v1
В ответ автоматически включается дополнительное измерение dateRange . Значение измерения dateRange содержит имя диапазона дат, которое либо берется из поля dateRange.name , либо создается автоматически.
....
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "dateRange"
}
],
....
"rows": [
....
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "year_ago"
}
],
"metricValues": [
{
"value": "253286"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
},
{
"value": "current_year"
}
],
"metricValues": [
{
"value": "272582"
}
]
},
....
Запрос API отчетности v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2020-01-01",
"endDate": "2020-01-31",
},
{
"startDate": "2021-01-01",
"endDate": "2021-01-31",
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
]
}
]
}
Ответ API для отчетов v4
В Reporting API v4 значения для каждого диапазона дат сгруппированы внутри поля metrics :
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"253286"
]
},
{
"values": [
"272582"
]
}
]
},
Сортировка
Поведением порядка запросов отчетов Data API v1 можно управлять с помощью поля orderBys , аналогичного полю orderBys Reporting API v4 .
Спецификация OrderBy изменилась в Data API v1. Каждый OrderBy может содержать одно из следующего:
- DimensionOrderBy сортирует результаты по значениям измерения.
- MetricOrderBy сортирует результаты по значениям метрики.
- PivotOrderBy используется в сводных запросах и сортирует результаты по значениям метрики в группе сводных столбцов.
Типы заказа DELTA , SMART , HISTOGRAM_BUCKET, поддерживаемые Reporting API v4, не реализованы в Data API v1.
Тип заказа OrderType.NUMERIC Data API v1 эквивалентен значению OrderType.DIMENSION_AS_INTEGER Reporting API v4.
Запрос API данных v1
В этом примере показан пример запроса, который сообщает о количестве сеансов по стране, упорядочивая строки по показателю sessions в порядке убывания.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"orderBys": [
{
"metric": {
"metricName": "sessions"
},
"desc": true
}
]
}
Ответ API данных v1
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "United States"
}
],
"metricValues": [
{
"value": "510449"
}
]
},
{
"dimensionValues": [
{
"value": "Japan"
}
],
"metricValues": [
{
"value": "283430"
}
]
},
....
],
"totalSize": 212,
"metadata": {}
}
Запрос API отчетности v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"orderBys": [
{
"fieldName": "ga:sessions",
"sortOrder": "DESCENDING"
}
]
}
]
}
Ответ API для отчетов v4
{
"reports": [
{
....
"data": {
"rows": [
{
"dimensions": [
"United States"
],
"metrics": [
{
"values": [
"510449"
]
}
]
},
{
"dimensions": [
"Japan"
],
"metrics": [
{
"values": [
"283430"
]
}
]
},
....
}
]
}
Фильтрация
Предложения DimensionFilter и metricFilter Data API v1 можно использовать, чтобы попросить API возвращать данные только для определенных значений измерения или показателя. Это похоже на DimensionFilterClauses и metricFilterClauses Reporting API v4.
API данных версии 1 не поддерживает строки выражений фильтров, такие как предложение filterExpression API отчетов версии 4. Эти выражения следует переписать с использованием предложений dimensionFilter и metricFilter .
Запрос API данных v1
Этот пример запроса возвращает список количества сеансов для определенных путей к страницам, которые посетили пользователи.
Предложение DimensionFilter используется для возврата только строк со значениями измерения pagePath начинающимися с /webstore/ и содержащими строку action=a12345 .
Предложение metricFilter требует, чтобы метод runReport возвращал только строки со значениями метрик sessions , превышающими 1000.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "pagePath"
}
],
"dimensionFilter": {
"andGroup": {
"expressions": [
{
"filter": {
"stringFilter": {
"value": "/webstore/",
"matchType": "BEGINS_WITH"
},
"fieldName": "pagePath"
}
},
{
"filter": {
"stringFilter": {
"matchType": "CONTAINS",
"value": "action=a12345"
},
"fieldName": "pagePath"
}
}
]
}
},
"metricFilter": {
"filter": {
"numericFilter": {
"value": {
"int64Value": 1000
},
"operation": "GREATER_THAN"
},
"fieldName": "sessions"
}
},
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Запрос API отчетности v4
Этот пример запроса аналогичен примеру Data API v1. Он возвращает список количества сеансов для определенных путей к страницам, которые посетили пользователи.
Поле DimensionFilterClauses используется для возврата только строк со значениями измерения pagePath начинающимися с /webstore/ и содержащими строку action=a12345 .
Поле metricFilterClauses используется для возврата только строк со значениями метрики ga:sessions превышающими 1000.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:pagePath"
}
],
"metricFilterClauses": [
{
"filters": [
{
"metricName": "ga:sessions",
"operator": "GREATER_THAN",
"comparisonValue": "1000"
}
]
}
],
"dimensionFilterClauses": [
{
"filters": [
{
"dimensionName": "ga:pagePath",
"operator": "BEGINS_WITH",
"expressions": [
"/webstore/"
]
},
{
"dimensionName": "ga:pagePath",
"operator": "PARTIAL",
"expressions": [
"action=a12345"
]
}
],
"operator": "AND"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
]
}
Пагинация
API данных версии 1 использует поля предела и смещения для разбиения на страницы результатов ответов, охватывающих несколько страниц, тогда как API отчетов версии 4 использует pageToken и pageSize .
Для запросов сводных данных Data API v1 поля limit и offset объекта Pivot должны использоваться для реализации разбиения на страницы для каждой сводной таблицы индивидуально. Поле limit теперь является обязательным для каждого объекта Pivot .
По умолчанию API данных версии 1 возвращает не более первых 10 000 строк данных о событиях, тогда как значение по умолчанию для API отчетов версии 4 составляет 1 000 строк.
Общее количество строк, соответствующих запросу, возвращается с помощью поля rowCount в ответе API данных версии 1, который аналогичен API отчетов версии 4.
Запрос API данных v1
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"limit": 5,
"offset": 15
}
Ответ API данных v1
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"rowCount": 228,
}
Запрос API отчетности v4
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
....
],
"metrics": [
....
],
"dimensions": [
....
],
"pageSize": 5,
"pageToken": "5"
}
]
}
Ответ API для отчетов v4
{
"reports": [
{
....
"data": {
"rows": [
....
],
....
"rowCount": 225,
},
"nextPageToken": "15"
}
]
}
Агрегации показателей
Data API v1 вычисляет значения агрегирования только в том случае, если в запросе указано поле metricAggregations . Напротив, Reporting API v4 по умолчанию возвращает итоговые, минимальные и максимальные значения для каждой метрики, если только для полейideTotals и displayValueRanges не установлено true
Запрос API данных v1
Агрегации будут рассчитываться только в том случае, если в запросе указано поле metricAggregations .
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"metricAggregations": [
"TOTAL",
"MAXIMUM",
"MINIMUM"
],
"metrics": [
{
"name": "sessions"
}
],
"dimensions": [
{
"name": "country"
}
],
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
]
}
Ответ API данных v1
Строки агрегированных показателей возвращаются в полях totals , minimum и maximum ответа. Для строк агрегированных показателей поле dimensionValues содержит специальное значение RESERVED_TOTAL , RESERVED_MAX или RESERVED_MIN .
{
"dimensionHeaders": [
....
],
"metricHeaders": [
....
],
"rows": [
....
],
"totals": [
{
"dimensionValues": [
{
"value": "RESERVED_TOTAL"
},
{
"value": "RESERVED_TOTAL"
}
],
"metricValues": [
{
"value": "6026053"
}
]
}
],
"maximums": [
{
"dimensionValues": [
{
"value": "RESERVED_MAX"
},
{
"value": "RESERVED_MAX"
}
],
"metricValues": [
{
"value": "493655"
}
]
}
],
"minimums": [
{
"dimensionValues": [
{
"value": "RESERVED_MIN"
},
{
"value": "RESERVED_MIN"
}
],
"metricValues": [
{
"value": "1"
}
]
}
],
....
}
Запрос API отчетности v4
Пример запроса на возврат количества сеансов по странам.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "yesterday",
"endDate": "today"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
}
]
}
Ответ API для отчетов v4
Поля totals , minimums и maximums по умолчанию присутствуют в ответе Reporting API v4.
{
"reports": [
{
"columnHeader": {
....
},
"data": {
"rows": [
....
],
....
"totals": [
{
"values": [
"4493363"
]
}
],
"minimums": [
{
"values": [
"1"
]
}
],
"maximums": [
{
"values": [
"684005"
]
}
]
}
}
]
}
Повороты
Data API v1 поддерживает функции сводки в методах отчетов runPivotReport и BatchRunPivotReports .
Reporting API v4 позволяет включать сводные данные в запросы отчетов с использованием метода BatchGet .
Сводные точки реализованы в API данных версии 1 по-разному по сравнению с API отчетов версии 4: каждая строка ответа представляет одну ячейку таблицы, тогда как в API отчетов версии 4 одна строка ответа представляет полную строку таблицы.
API данных v1
Ниже приведен фрагмент ответа Data API v1 на запрос runPivotReport . Каждая ячейка сводного отчета возвращается индивидуально:
"rows": [
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
API отчетности v4
Ниже приведен фрагмент ответа Reporting API v4 на запрос BatchGet . Одна строка ответа представляет собой полную строку таблицы, содержащую все значения показателей для сводной таблицы в pivotValueRegions :
"data": {
"rows": [
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
В Data API версии 1 каждое измерение запроса runPivotReport batchRunPivotReports должно быть определено в сводном объекте. Измерение не будет отображаться в отчете, если оно не используется ни в одной сводной таблице сводного запроса.
Столбцы сводной таблицы Data API v1 задаются с помощью поля fieldNames вместо поля dimensions Reporting API v4.
Фильтр измерений на уровне запроса необходимо использовать, если фильтрация измерений требуется в запросе отчетов Data API v1. Это отличается от API отчетов версии 4, который принимает спецификацию DimensionFilterClauses в сводном объекте.
Поле смещения Data API v1 функционально аналогично полю startGroup Reporting API v4.
Поле ограничения Data API v1 аналогично значению maxGroupCount Reporting API v4 и должно использоваться для ограничения количества элементов отчета.
API данных версии 1 поддерживает несколько сводных данных, если произведение limit параметра для каждого сводного значения не превышает 100 000. Reporting API v4 поддерживает только одно сводное измерение.
По умолчанию API данных версии 1 упорядочивает измерения внутри сводной таблицы по первой метрике в отчете. Это поведение отличается от API отчетов версии 4, где порядок сводных данных определяется по убыванию «общего количества» запрошенных метрик . Чтобы указать порядок сортировки в Data API v1, используйте поле orderBys спецификации Pivot.
Запрос API данных v1
Этот сводный запрос Data API v1 создает отчет о количестве сеансов по стране, сгруппированный по параметру browser . Обратите внимание, как запрос использует поля orderBys , limit , offset для воспроизведения поведения аналогичного запроса Reporting API v4, чтобы сохранить настройки порядка и разбиения на страницы.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runPivotReport
{
"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"
}
]
}
Ответ API данных v1
{
"pivotHeaders": [
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "(not set)"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
}
]
}
],
"rowCount": 234
},
{
"pivotDimensionHeaders": [
{
"dimensionValues": [
{
"value": "Safari"
}
]
},
{
"dimensionValues": [
{
"value": "Edge"
}
]
},
{
"dimensionValues": [
{
"value": "Opera"
}
]
}
],
"rowCount": 124
}
],
"dimensionHeaders": [
{
"name": "country"
},
{
"name": "browser"
}
],
"metricHeaders": [
{
"name": "sessions",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "(not set)"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "2531"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "1701"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "1564"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Safari"
}
],
"metricValues": [
{
"value": "237"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Edge"
}
],
"metricValues": [
{
"value": "44"
}
]
},
{
"dimensionValues": [
{
"value": "Algeria"
},
{
"value": "Opera"
}
],
"metricValues": [
{
"value": "22"
}
]
},
....
],
....
}
Запрос API отчетности v4
Этот сводный запрос Reporting API v4 создает отчет о количестве сеансов по странам, сгруппированный по параметру ga:browser .
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dateRanges": [
{
"startDate": "2021-01-01",
"endDate": "2021-01-30"
}
],
"metrics": [
{
"expression": "ga:sessions"
}
],
"dimensions": [
{
"name": "ga:country"
}
],
"pivots": [
{
"dimensions": [
{
"name": "ga:browser"
}
],
"startGroup": 3,
"maxGroupCount": 3,
"metrics": [
{
"expression": "ga:sessions"
}
]
}
]
}
]
}
Ответ API для отчетов v4
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:country"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:sessions",
"type": "INTEGER"
}
],
"pivotHeaders": [
{
"pivotHeaderEntries": [
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Edge"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Opera"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
},
{
"dimensionNames": [
"ga:browser"
],
"dimensionValues": [
"Samsung Internet"
],
"metric": {
"name": "ga:sessions",
"type": "INTEGER"
}
}
],
"totalPivotGroupsCount": 19
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"(not set)"
],
"metrics": [
{
"values": [
"781283"
],
"pivotValueRegions": [
{
"values": [
"6923",
"1385",
"66"
]
}
]
}
]
},
{
"dimensions": [
"Albania"
],
"metrics": [
{
"values": [
"42394"
],
"pivotValueRegions": [
{
"values": [
"24658",
"17208",
"132"
]
}
]
}
]
},
{
"dimensions": [
"Algeria"
],
"metrics": [
{
"values": [
"23208"
],
"pivotValueRegions": [
{
"values": [
"19252",
"66",
"1582"
]
}
]
}
]
},
....
],
....
}
}
]
}
когорты
Data API v1 использует спецификацию CohortSpec для настройки когортных отчетов. Это похоже на спецификацию CohortGroup Reporting API v4.
Все метрики, доступные в Data API v1, в настоящее время совместимы с когортными запросами, тогда как Reporting API v4 позволяет использовать в когортном запросе только подмножество специальных метрик .
В запросе когорты Data API v1 требуется метрика cohortActiveUsers .
И Data API v1, и Reporting API v4 позволяют использовать до 12 когорт в одном запросе.
Метрики жизненной ценности (LTV) в настоящее время не поддерживаются в Data API v1.
Эквивалентность когортных показателей
Большинство показателей когорты, определенных в Reporting API версии 4, можно заменить выражением для достижения эквивалентного результата в Data API версии 1, как показано на диаграмме ниже.
| Название метрики Reporting API v4 | Имя или выражение метрики Data API v1 |
|---|---|
| ga:cohortActiveUsers | когортаАктивныеПользователи |
| ga:cohortTotalUsers | когортаВсего пользователей |
| ga:cohortRetentionRate | "expression": "cohortActiveUsers/cohortTotalUsers" |
| ga:cohortRevenuePerUser | "expression": "totalRevenue/cohortActiveUsers" |
| ga:cohortVisitDurationPerUser | "expression": "userEngagementDuration/cohortActiveUsers" |
| ga:cohortAppviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortPageviewsPerUser | "expression": "screenPageViews/cohortActiveUsers" |
| ga:cohortSessionsPerUser | "expression": "sessions/cohortActiveUsers" |
| ga:cohortGoalCompletionsPerUser | "expression": "eventCount/cohortActiveUsers" в дополнение к фильтру измерения по eventName , соответствующему желаемому событию достижения цели . |
Запрос API данных v1
Пример запроса, настраивающего группу пользователей, первый сеанс которых произошел на неделе 3 января 2021 г. Количество активных пользователей и коэффициент удержания пользователей рассчитываются для когорты за 5 недель с ЕЖЕНЕДЕЛЬНОЙ детализацией.
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runReport
{
"cohortSpec": {
"cohorts": [
{
"dimension": "firstSessionDate",
"name": "cohort",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
],
"cohortsRange": {
"startOffset": 0,
"endOffset": 4,
"granularity": "WEEKLY"
}
},
"metrics": [
{
"name": "cohortActiveUsers"
},
{
"expression": "cohortActiveUsers/cohortTotalUsers",
"name": "cohortRetentionRate"
}
],
"dimensions": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
]
}
Ответ API данных v1
{
"dimensionHeaders": [
{
"name": "cohort"
},
{
"name": "cohortNthWeek"
}
],
"metricHeaders": [
{
"name": "cohortActiveUsers",
"type": "TYPE_INTEGER"
},
{
"name": "cohortRetentionRate",
"type": "TYPE_FLOAT"
}
],
"rows": [
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0000"
}
],
"metricValues": [
{
"value": "4268816"
},
{
"value": "0.999913800857494"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0001"
}
],
"metricValues": [
{
"value": "241580"
},
{
"value": "0.056586926213534013"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0002"
}
],
"metricValues": [
{
"value": "159390"
},
{
"value": "0.037335003597877253"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0003"
}
],
"metricValues": [
{
"value": "131512"
},
{
"value": "0.030804950079453122"
}
]
},
{
"dimensionValues": [
{
"value": "cohort"
},
{
"value": "0004"
}
],
"metricValues": [
{
"value": "96793"
},
{
"value": "0.022672482610259947"
}
]
}
],
"totalSize": 5,
"metadata": {}
}
Запрос API отчетности v4
Пример запроса, настраивающего группу пользователей, первый сеанс которых произошел на неделе 3 января 2021 г. Количество активных пользователей и коэффициент удержания пользователей рассчитываются для когорты за 5 недель с WEEKLY детализацией.
POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
"reportRequests": [
{
"viewId": "UA_VIEW_ID",
"dimensions": [
{
"name": "ga:cohort"
},
{
"name": "ga:cohortNthWeek"
}
],
"metrics": [
{
"expression": "ga:cohortActiveUsers"
},
{
"expression": "ga:cohortRetentionRate"
}
],
"cohortGroup": {
"cohorts": [
{
"name": "cohort",
"type": "FIRST_VISIT_DATE",
"dateRange": {
"startDate": "2021-01-03",
"endDate": "2021-01-09"
}
}
]
}
}
]
}
Ответ API для отчетов v4
{
"reports": [
{
"columnHeader": {
"dimensions": [
"ga:cohort",
"ga:cohortNthWeek"
],
"metricHeader": {
"metricHeaderEntries": [
{
"name": "ga:cohortActiveUsers",
"type": "INTEGER"
},
{
"name": "ga:cohortRetentionRate",
"type": "PERCENT"
}
]
}
},
"data": {
"rows": [
{
"dimensions": [
"cohort",
"0000"
],
"metrics": [
{
"values": [
"40793",
"100.0"
]
}
]
},
{
"dimensions": [
"cohort",
"0001"
],
"metrics": [
{
"values": [
"3883",
"9.518789988478416"
]
}
]
},
{
"dimensions": [
"cohort",
"0002"
],
"metrics": [
{
"values": [
"2165",
"5.307283112298679"
]
}
]
},
{
"dimensions": [
"cohort",
"0003"
],
"metrics": [
{
"values": [
"1703",
"4.174735861544873"
]
}
]
},
{
"dimensions": [
"cohort",
"0004"
],
"metrics": [
{
"values": [
"1484",
"3.637879047875861"
]
}
]
},
{
"dimensions": [
"cohort",
"0005"
],
"metrics": [
{
"values": [
"1103",
"2.7038952761503197"
]
}
]
},
{
"dimensions": [
"cohort",
"0006"
],
"metrics": [
{
"values": [
"933",
"2.28715711028853"
]
}
]
},
{
"dimensions": [
"cohort",
"0007"
],
"metrics": [
{
"values": [
"336",
"0.8236707278209496"
]
}
]
}
],
"totals": [
{
"values": [
"52400",
"16.056676390557204"
]
}
],
"rowCount": 8,
"minimums": [
{
"values": [
"336",
"0.8236707278209496"
]
}
],
"maximums": [
{
"values": [
"40793",
"100.0"
]
}
],
"isDataGolden": true
}
}
]
}
Выборка
API данных версии 1 автоматически использует выборку данных , если предполагает, что ограничения по количеству элементов приведут к снижению качества данных. Если выполняется выборка результатов для диапазона дат, metadata RunReportResponse будут содержать соответствующий SamplingMetadata , аналогичный полю sampleLevel , которое присутствовало в Reporting API v4.
Свежесть данных
API данных не предоставляет эквивалента поля isDataGolden API отчетов версии 4, которое использовалось для указания того, завершилась ли обработка всех обращений к отчету. Один и тот же отчет по-прежнему может возвращать разные результаты при более позднем запросе из-за дополнительной обработки.
(Не поддерживается) Сегменты
Сегменты в настоящее время не поддерживаются в Data API v1.
Отчетность в режиме реального времени
Используйте метод Properties.runRealtimeReport Data API v1, чтобы создавать отчеты в реальном времени для ресурсов Google Аналитики 4. Функциональность создания отчетов в реальном времени для ресурсов Universal Analytics была предоставлена методом data.realtime.get Google Analytics API v3.
Схема отчетов Data API в реальном времени отличается от схемы отчетов в реальном времени Analytics API v3 из-за концептуальных различий между Universal Analytics и Google Analytics 4.
Запрос API данных v1
В следующем примере, чтобы сохранить поведение сортировки по умолчанию Google Analytics API v3, в образец запроса Data API v1 был добавлен необязательный элемент orderBy .
POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID:runRealtimeReport
{
"dimensions": [{ "name": "country" }],
"metrics": [{ "name": "activeUsers" }],
"orderBys": [
{
"dimension": {
"dimensionName": "country"
}
}
]
}
Ответ API данных v1
{
"dimensionHeaders": [
{
"name": "country"
}
],
"metricHeaders": [
{
"name": "activeUsers",
"type": "TYPE_INTEGER"
}
],
"rows": [
{
"dimensionValues": [
{
"value": ""
}
],
"metricValues": [
{
"value": "199"
}
]
},
{
"dimensionValues": [
{
"value": "Afghanistan"
}
],
"metricValues": [
{
"value": "4"
}
]
},
{
"dimensionValues": [
{
"value": "Albania"
}
],
"metricValues": [
{
"value": "136"
}
]
},
....
],
"rowCount": 172
}
Запрос Google Analytics API v3
GET https://analytics.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&metrics=rt:activeUsers&dimensions=rt:country
Ответ Google Analytics API v3
{
"kind": "analytics#realtimeData",
"id": "https://www.googleapis.com/analytics/v3/data/realtime?ids=ga:UA_VIEW_ID&dimensions=rt:country&metrics=rt:activeUsers",
"query": {
"ids": "ga:UA_VIEW_ID",
"dimensions": "rt:country",
"metrics": [
"rt:activeUsers"
],
"max-results": 10
},
"totalResults": 178,
"profileInfo": {
"profileId": "XXXXXX",
"accountId": "XXXXXX",
"webPropertyId": "UA-XXXXXX",
"profileName": "View Name",
},
"columnHeaders": [
{
"name": "rt:country",
"columnType": "DIMENSION",
"dataType": "STRING"
},
{
"name": "rt:activeUsers",
"columnType": "METRIC",
"dataType": "INTEGER"
}
],
"totalsForAllResults": {
"rt:activeUsers": "80351"
},
"rows": [
[
"(not set)",
"97"
],
[
"Afghanistan",
"2"
],
[
"Albania",
"78"
],
....
]
}
(Не поддерживается) Отчеты об активности пользователей
Data API v1 в настоящее время не поддерживает функцию отчета об активности отдельных пользователей, аналогичную методу userActivity.search Reporting API v4.
Изменения квот API
Категории квот «Ядро» и «В реальном времени»
Для целей квоты API данных имеет две категории запросов: основные и в реальном времени. Запросы API к основным методам отчетности ( runReport , getMetadata , runPivotReport , batchRunReports , batchRunPivotReports ) взимают квоты Core. Запросы API для runRealtimeReport метода RealtimeReport взимают квоты в реальном времени.
Квоты токенов
Помимо квот проекта, каждый запрос использует квоты маркеров свойств, плата за которые взимается в зависимости от сложности запроса. Подробное описание квот и ограничений API см. в документации по квотам Data API v1 .
Текущее состояние всех квот для ресурса Analytics можно получить, установив для returnPropertyQuota значение true в основном запросе или запросе отчетов в режиме реального времени. Состояние квоты будет возвращено в PropertyQuota .
(Не поддерживается) Квота на основе ресурсов
Поскольку все основные отчеты в Google Analytics 4 основаны на полных данных, квота на основе ресурсов, введенная в Reporting API v4, больше не применима, и в запросе отчетов Data API v1 нет эквивалента поля useResourceQuotas .
(Не поддерживается) Количество запросов на просмотр (профиль) в день
Поскольку в Google Analytics 4 нет представлений, requests per view (profile) per day отсутствует в Data API v1 и заменяется квотами токенов .