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

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

Обзор

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

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

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

Ограничения, авторизация и вопросы зависимости

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

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

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

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

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

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

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

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

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

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

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

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

Пример

Приведённый ниже пример кода демонстрирует использование пакетной обработки с API Docs.

Запрос

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

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

  • Обновите слово "Hello", используя UpdateTextStyleRequest . Параметры startIndex и endIndex определяют range форматированного текста внутри сегмента.

  • С помощью textStyle установите для слова "Hello" стиль шрифта на "жирный" и цвет на синий.

  • С помощью поля 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`
}
 ,

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

Обзор

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

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

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

Ограничения, авторизация и вопросы зависимости

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

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

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

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

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

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

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

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

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

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

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

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

Пример

Приведённый ниже пример кода демонстрирует использование пакетной обработки с API Docs.

Запрос

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

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

  • Обновите слово "Hello", используя UpdateTextStyleRequest . Параметры startIndex и endIndex определяют range форматированного текста внутри сегмента.

  • С помощью textStyle установите для слова "Hello" стиль шрифта на "жирный" и цвет на синий.

  • С помощью поля 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`
}