Как было объявлено в блоге Google Developers , 12 августа 2020 года был закрыт один конкретный подход к пакетной обработке — конечная точка Global HTTP Batch ( www.googleapis.com/batch ). Другие подходы к пакетной обработке по-прежнему работают, как описано в остальной части этой страницы. Если в вашем коде используется глобальная конечная точка пакетной обработки HTTP, см. запись в блоге, где приведены инструкции по переходу на использование других подходов, таких как конечные точки пакетной обработки HTTP для конкретных www.googleapis.com/batch/ API / VERSION ).
В этом документе показано, как объединить вызовы API в пакет, чтобы уменьшить количество HTTP-соединений, которые должен выполнить ваш клиент.
Этот документ посвящен созданию пакетного запроса путем отправки HTTP-запроса. Если вместо этого вы используете клиентскую библиотеку Google для выполнения пакетного запроса, см . документацию по клиентской библиотеке .
Обзор
Каждое HTTP-соединение, которое устанавливает ваш клиент, приводит к определенным накладным расходам. Google Ad Experience Report API поддерживает пакетную обработку, чтобы ваш клиент мог поместить несколько вызовов API в один HTTP-запрос.
Примеры ситуаций, когда вы можете захотеть использовать пакетную обработку:
- Вы только начали использовать API и вам нужно загрузить много данных.
- Пользователь внес изменения в данные, когда ваше приложение было в автономном режиме (отключено от Интернета), поэтому вашему приложению необходимо синхронизировать свои локальные данные с сервером, отправляя множество обновлений и удалений.
В каждом случае вместо отправки каждого вызова по отдельности вы можете сгруппировать их вместе в один HTTP-запрос. Все внутренние запросы должны направляться в один и тот же Google API.
Вы ограничены 1000 вызовами в одном пакетном запросе. Если вам нужно сделать больше звонков, используйте несколько пакетных запросов.
Примечание . Пакетная система для Google Ad Experience Report API использует тот же синтаксис, что и система пакетной обработки OData , но семантика отличается.
Сведения о партии
Пакетный запрос состоит из нескольких вызовов API, объединенных в один HTTP-запрос, который можно отправить по пути batchPath указанному в документе обнаружения API . Путь по умолчанию: /batch/ api_name / api_version . В этом разделе подробно описывается синтаксис пакета; позже есть пример .
Примечание . Набор из n запросов, объединенных вместе, учитывается при расчете лимита использования как n запросов, а не как один запрос. Перед обработкой пакетный запрос разбивается на набор запросов.
Формат пакетного запроса
Пакетный запрос – это один стандартный HTTP-запрос, содержащий несколько вызовов Google Ad Experience Report API с использованием 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 Ad Experience Report.
Пример пакетного запроса
POST /batch/v1?key=key HTTP/1.1 Content-Type: multipart/mixed; boundary=batch_aer --batch_aer Content-Type: application/http Content-ID: id1 GET /v1/sites/http%3A%2F%2F/site1%2F HTTP/1.1 --batch_aer Content-Type: application/http Content-ID: id2 GET /v1/sites/http%3A%2F%2F/site2%2F HTTP/1.1 --batch_aer--
Пример пакетного ответа
Это ответ на пример запроса в предыдущем разделе.
HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch_aer
--batch_aer
Content-Type: application/http
Content-ID: response-id1
HTTP/1.1 200 OK
Content-Type: application/json
{
"reviewedSite": "site1",
"mobileSummary": {
"lastChangeTime": "2019-02-05T09:46:26.521747Z",
"betterAdsStatus": "PASSING",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-mobile?siteUrl=http://site1/",
"filterStatus": "OFF"
},
"desktopSummary": {
"lastChangeTime": "2019-02-07T23:07:29.017206Z",
"betterAdsStatus": "FAILING",
"enforcementTime": "2018-02-15T15:00:00Z",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-desktop?siteUrl=http://site1/",
"filterStatus": "ON"
}
}
--batch_aer
Content-Type: application/http
Content-ID: response-id2
HTTP/1.1 200 OK
Content-Type: application/json
{
"reviewedSite": "site2",
"mobileSummary": {
"lastChangeTime": "2018-03-06T16:06:33.375851Z",
"betterAdsStatus": "PASSING",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-mobile?siteUrl=http://site2/",
"filterStatus": "OFF"
},
"desktopSummary": {
"lastChangeTime": "2018-03-06T16:06:33.375851Z",
"betterAdsStatus": "PASSING",
"reportUrl": "https://www.google.com/webmasters/tools/ad-experience-desktop?siteUrl=http://site2/",
"filterStatus": "OFF"
}
}
--batch_aer--