Эта страница переведена с помощью Cloud Translation API.

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

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

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

Обзор

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

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

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

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

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

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

Примечание : пакеты большего размера могут привести к ограничению скорости. Отправка пакетов размером более 50 запросов не рекомендуется.

Подробности партии

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример

В следующем примере показано использование пакетной обработки с помощью универсального (вымышленного) демонстрационного API под названием Farm API. Однако те же принципы применимы и к API Gmail.

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

POST /batch/farm/v1 HTTP/1.1
Authorization: Bearer your_auth_token
Host: www.googleapis.com
Content-Type: multipart/mixed; boundary=batch_foobarbaz
Content-Length: total_content_length

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item1:12930812@barnyard.example.com>

GET /farm/v1/animals/pony

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item2:12930812@barnyard.example.com>

PUT /farm/v1/animals/sheep
Content-Type: application/json
Content-Length: part_content_length
If-Match: "etag/sheep"

{
  "animalName": "sheep",
  "animalAge": "5"
  "peltColor": "green",
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item3:12930812@barnyard.example.com>

GET /farm/v1/animals
If-None-Match: "etag/animals"

--batch_foobarbaz--

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

Это ответ на пример запроса в предыдущем разделе.

HTTP/1.1 200
Content-Length: response_total_content_length
Content-Type: multipart/mixed; boundary=batch_foobarbaz

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item1:12930812@barnyard.example.com>

HTTP/1.1 200 OK
Content-Type application/json
Content-Length: response_part_1_content_length
ETag: "etag/pony"

{
  "kind": "farm#animal",
  "etag": "etag/pony",
  "selfLink": "/farm/v1/animals/pony",
  "animalName": "pony",
  "animalAge": 34,
  "peltColor": "white"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item2:12930812@barnyard.example.com>

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: response_part_2_content_length
ETag: "etag/sheep"

{
  "kind": "farm#animal",
  "etag": "etag/sheep",
  "selfLink": "/farm/v1/animals/sheep",
  "animalName": "sheep",
  "animalAge": 5,
  "peltColor": "green"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item3:12930812@barnyard.example.com>

HTTP/1.1 304 Not Modified
ETag: "etag/animals"

--batch_foobarbaz--

Пакетирование запросов Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.