Пакетная обработка запросов API Google Analytics

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

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

Обзор

Каждое HTTP-соединение, которое создает ваш клиент, приводит к определенным затратам. API Google Analytics поддерживает пакетную обработку, что позволяет вашему клиенту помещать несколько вызовов API в один HTTP-запрос.

Примеры ситуаций, когда вы можете использовать пакетную обработку:

В каждом случае вместо отправки каждого вызова отдельно вы можете сгруппировать их в один HTTP-запрос. Все внутренние запросы должны направляться к одному и тому же API Google.

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

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

Детали партии

Пакетный запрос состоит из нескольких вызовов API, объединенных в один HTTP-запрос, который можно отправить по batchPath , указанному в документе обнаружения API . Путь по умолчанию — /batch/ api_name / api_version . В этом разделе подробно описан синтаксис пакетной обработки; позже будет пример .

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

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

Пакетный запрос – это один стандартный HTTP-запрос, содержащий несколько вызовов API Google Analytics, использующий multipart/mixed тип контента. Внутри этого основного HTTP-запроса каждая часть содержит вложенный HTTP-запрос.

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

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

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

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

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

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

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

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

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

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

Пример

В следующем примере показано использование пакетной обработки с API Google Analytics.

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

POST /batch/analytics/v3 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-запросов, каждый запрос Google Analytics API в рамках пакетного запроса будет учитываться в вашей ежедневной квоте проекта . По умолчанию проект может делать до 50 000 запросов в день; пакетная обработка не поможет вам остаться ниже этой квоты.

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

Ограничение в 1,5 запроса в секунду (QPS) на идентификатор учетной записи применяется к запросам на запись Management API и запросам на запись API обеспечения . Следовательно, пакетная обработка этих запросов на запись может не улучшить производительность.