Пакетированные запросы Google Analytics API

В этой статье рассказывается о том, как группировать вызовы API, чтобы снизить количество требуемых подключений HTTP.

Это руководство посвящено созданию пакета путем отправки запроса HTTP. Если для создания пакетированного запроса вы используете клиентскую библиотеку Google, обратитесь к документации по ней.

Обзор

Каждое подключение HTTP, выполняемое клиентом, требует вычислительных ресурсов. Однако в Google Analytics API есть функция пакетирования, которая позволяет объединять несколько вызовов API в один запрос HTTP.

Пакетирование запросов может пригодиться в следующих случаях:

В этих случаях отдельные вызовы можно объединить в один запрос HTTP. Поддерживается пакетирование запросов для разных пользователей и API Google.

В одном запросе может быть до 1000 вызовов. Если их больше, создайте дополнительные пакеты.

Примечание. Система пакетирования API Google Analytics использует такой же синтаксис, как система обработки пакетов OData, но семантика различается.

Сведения о пакетах

Пакет – это набор вызовов, объединенных в один запрос HTTP. Ниже вы сможете почитать о его синтаксисе и ознакомиться с примером.

Примечание. С точки зрения действующих ограничений пакет из n запросов засчитывается как n запросов, а не один. Перед обработкой пакет разбирается на отдельные запросы.

Формат пакетированного запроса

Этот объект представляет собой стандартный запрос HTTP, содержащий несколько вызовов API Google Analytics с типом контента multipart/mixed. Все части основного запроса HTTP содержат вложенный запрос.

Каждая часть начинается с собственного HTTP-заголовка Content-Type: application/http. Кроме того, возможно присутствие необязательного заголовка Content-ID. Они обозначают начало части и не имеют отношения к вложенному запросу. После того как сервер разделяет пакет на отдельные запросы, заголовки частей игнорируются.

Каждая часть представляет собой полноценный запрос HTTP с собственной командой, URL, заголовками и телом. Он должен содержать только путь URL. Полные URL не поддерживаются.

Заголовки HTTP во внешнем пакетном запросе (кроме заголовков Content-, например Content-Type) применяются ко всем запросам в пакете. Если определенный заголовок HTTP указан и во внешнем запросе, и в отдельном вызове, во втором случае его значение переопределяет содержание внешнего заголовка. Заголовки отдельных вызовов применяются только к соответствующим вызовам.

Например, если указать в конкретном вызове заголовок авторизации, он будет применяться только к выбранному вызову. Если же задать его для внешнего запроса, он будет применяться ко всем отдельным вызовам за исключением тех, в которых указан собственный заголовок авторизации.

При получении пакетированного запроса сервер применяет к каждой части в соответствующем порядке параметры и заголовки, указанные во внешнем запросе, после чего обрабатывает каждую часть как отдельный запрос HTTP.

Ответ на пакетированный запрос

Ответ сервера представляет собой стандартный ответ HTTP с типом содержания multipart/mixed. Каждая часть ответа представляет собой отклик на соответствующий вызов в пакетированном запросе, выполняемый в том же порядке.

Подобно элементам запроса, компоненты ответа сервера представляют собой полноценные ответы HTTP, включающие код статуса, заголовок и тело. Как и в случае с запросом, каждая часть ответа имеет заголовок Content-Type, указывающий на ее начало.

Если в определенной части запроса присутствовал заголовок Content-ID, в соответствующей части ответа будет такой же заголовок Content-ID, в котором исходному значению будет предшествовать строка response-, как показано в примере ниже.

Внимание! Сервер может выполнять вызовы в любом порядке и не обязательно в той последовательности, в которой вы их указали. Если она для вас важна, не отправляйте их в одном запросе. Выполните первый вызов отдельно, дождитесь ответа на него, а затем отправьте второй.

Пример

В примере ниже показано, как работает пакетирование в API Google Analytics.

Пример пакетированного запроса

POST /batch HTTP/1.1
Host: www.googleapis.com
Content-length: 731
Content-type: multipart/mixed; boundary=batch_0123456789
Authorization: Bearer ya29.5gFZooleNoSpGqYOOF0eFciUGz1x26k9GagZoW7HJCogWlCoNOotxlZPo7bDbwo1ykDq
--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary


POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 68


{
 "name": "Campaign Group",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789
Content-Type: application/http
Content-ID: 
Content-Transfer-Encoding: binary


POST https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions
Content-Type: application/json
Content-Length: 67


{
 "name": "Campaign Type",
 "scope": "SESSION",
 "active": true
}

--batch_0123456789--

Пример пакетированного ответа

Это ответ на пример запроса выше.

HTTP/1.1 200 OK
Content-length: 1876
X-xss-protection: 1; mode=block
X-content-type-options: nosniff
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Vary: Origin,X-Origin
Server: GSE
Cache-control: private, max-age=0
Date: Wed, 02 Sep 2015 21:36:35 GMT
X-frame-options: SAMEORIGIN
Content-type: multipart/mixed; boundary=batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/L-Y_3uM9BpST8Sea-SJDRQ7N7vE"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 548

{"kind":"analytics#customDimension","id":"ga:dimension18","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Group","index":18,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:34.143Z","updated":"2015-09-02T21:36:34.143Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension18","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
ETag: "o-85COrcxoYkAw5itMLG4AKNpMY/VN-21fLS1T0Qko3pHEB5fi8vYJ8"
Content-Type: application/json; charset=UTF-8
Date: Wed, 02 Sep 2015 21:36:35 GMT
Expires: Wed, 02 Sep 2015 21:36:35 GMT
Cache-Control: private, max-age=0
Content-Length: 547

{"kind":"analytics#customDimension","id":"ga:dimension19","accountId":"XXXXXX","webPropertyId":"UA-XXXXXX-1","name":"Campaign Type","index":19,"scope":"SESSION","active":true,"created":"2015-09-02T21:36:35.099Z","updated":"2015-09-02T21:36:35.099Z","selfLink":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1/customDimensions/ga:dimension19","parentLink":{"type":"analytics#webproperty","href":"https://www.googleapis.com/analytics/v3/management/accounts/XXXXXX/webproperties/UA-XXXXXX-1"}}
--batch_KDU-RkhYyNI_AAkR9Jc5Z_Q--

Клиентские библиотеки

Если вы хотите реализовать пакетирование на определенном языке, прочитайте соответствующие инструкции ниже:

Пакетирование и квоты Google Analytics

Использование пакетов позволяет сэкономить системные ресурсы на отправке запросов HTTP, однако каждый запрос API Google Analytics засчитывается при расчете ежедневного ограничения на число запросов в проекте. По умолчанию проект может выполнять до 50 000 запросов в день. В отношении этого лимита пакетирование не обеспечивает никакого преимущества.

Будут применяться все обычные ограничения за исключением пакетированных запросов разрешений пользователей на запись (удаление, добавление, изменение). Например, для Core Reporting API действует лимит в размере 10 параллельных запросов на представление (профиль). Пакетирование ситуацию не изменит.