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

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

Обзор

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример

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

Запрос

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

  • Вставьте текст «Hello World» в начало существующего документа с location 1 , используя InsertTextRequest .

  • Обновите слово «Привет» с помощью UpdateTextStyleRequest . startIndex и endIndex определяют range форматированного текста внутри сегмента.

  • Используя textStyle , установите полужирный стиль шрифта и синий цвет только для слова «Привет».

  • Используя поле WriteControl , вы можете контролировать выполнение запросов на запись. Дополнительные сведения см. в разделе Установление согласованности состояния с помощью WriteControl .

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1,
               "tabId":TAB_ID
            },
            "text":"Hello World"
         }
      },
      {
         "updateTextStyle":{
            "range":{
               "startIndex":1,
               "endIndex":6
            },
            "textStyle":{
               "bold":true,
               "foregroundColor":{
                  "color":{
                     "rgbColor":{
                        "blue":1
                     }
                  }
               }
            },
            "fields":"bold,foreground_color"
         }
      }
   ],
   "writeControl": {
      "requiredRevisionId": "REQUIRED_REVISION_ID"
  }
}

Замените TAB_ID и REQUIRED_REVISION_ID идентификатором вкладки и идентификатором редакции соответственно документа, к которому применяется запрос на запись.

Ответ

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

{
   "replies":[
      {},
      {}
   ],
   "writeControl":{
      "requiredRevisionId":`REQUIRED_REVISION_ID`
   },
   "documentId":`DOCUMENT_ID`
}