Пакетные запросы

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

Обзор

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

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

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

Рекомендации по ограничениям, авторизации и зависимостям

Вот список других моментов, которые следует учитывать при пакетном обновлении:

• Каждый пакетный запрос, включая все подзапросы, учитывается как один запрос API в рамках вашего лимита использования .
• Пакетный запрос аутентифицируется один раз. Эта единая аутентификация применяется ко всем объектам пакетного обновления в запросе.
• Сервер обрабатывает подзапросы в том же порядке, в котором они появляются в пакетном запросе. Последние подзапросы могут зависеть от действий, предпринятых во время предыдущих подзапросов. Например, в одном и том же пакетном запросе пользователи могут вставлять текст в существующий документ, а затем стилизовать его.

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

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

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

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

При таком подходе вы можете создать весь документ Google, используя один запрос пакетного обновления API с несколькими подзапросами.

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

Запрос — это одиночный запрос JSON, содержащий несколько вложенных подзапросов с одним обязательным свойством: requests . Запросы формируются в виде массива отдельных запросов. Каждый запрос использует JSON для представления объекта запроса и хранения его свойств.

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

Формат ответа на пакетный запрос аналогичен формату запроса. Ответ сервера содержит полный ответ одного объекта ответа.

Свойство основного объекта JSON называется replies . Ответы возвращаются в массиве, причем каждый ответ на один из запросов занимает тот же порядок индекса, что и соответствующий запрос. Некоторые запросы не имеют ответов, и ответ по этому индексу массива пуст.

Пример

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

Запрос

В этом примере пакетного запроса показано, как:

• Добавьте presentations.pages в существующую презентацию со insertionIndex , равным 1 , с помощью метода CreateSlideRequest .

• Добавьте shapeType типа TEXT_BOX к новому слайду с помощью метода CreateShapeRequest .

• Вставьте текст «Hello World» в новое поле с помощью метода InsertTextRequest .

{
   "requests":[
      {
         "createSlide":{
            "insertionIndex":1,
            "objectId":"newSlide"
         }
      },
      {
         "createShape":{
            "elementProperties":{
               "pageObjectId":"newSlide",
               "size":{
                  "height":{
                     "magnitude":50,
                     "unit":"PT"
                  },
                  "width":{
                     "magnitude":200,
                     "unit":"PT"
                  }
               }
            },
            "shapeType":"TEXT_BOX",
            "objectId":"newTextBox"
         }
      },
      {
         "insertText":{
            "objectId":"newTextBox",
            "text":"Hello World"
         }
      }
   ]
}

Ответ

В этом примере пакетного ответа отображается информация о том, как был применен каждый подзапрос в пакетном запросе. Обратите внимание, что метод InsertTextRequest не содержит ответа, поэтому значение индекса массива в [2] состоит из пустых фигурных скобок. Пакетный запрос отображает свойство WriteControl , которое показывает, как были выполнены запросы на запись.

{
   "requiredRevisionId": ID
   "presentationId": "",
   "replies":[
      {
         "createSlide":{
            "objectId":"newSlide"
         }
      },
      {
         "createShape":{
            "objectId":"newTextBox"
         }
      },
      {
         
      }
   ],
   "writeControl":{
      "requiredRevisionId": REVISION_ID
   }
}