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

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

Обзор

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример

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

Запрос

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

• Добавьте лист в существующую электронную таблицу с идентификатором sheetId 12345, используя функцию AddSheetRequest .
• Добавьте данные на новый лист, начиная с ячейки A1, используя запрос UpdateCellsRequest .
• Добавьте namedRange или представление фильтра на новый лист.

Добавив идентификатор листа в запрос, пользователи могут использовать этот идентификатор для других подзапросов в рамках того же вызова API. Это повышает производительность, избегая цикла "запись-чтение-запись".

Список типов запросов на пакетное обновление, сгруппированных по различным категориям, см. в таблице в разделе «Операции пакетного обновления» .

{
   "requests":[
      {
         "addSheet":{
            "properties":{
               "sheetId":123456
            }
         }
      },
      {
         "updateCells":{
            "start":{
               "sheetId":123456
            },
            "rows":[
               {
                  "values":[
                     {
                        "userEnteredValue":{
                           "stringValue":"hello"
                        }
                     }
                  ]
               },
               {
                  "values":[
                     {
                        "userEnteredValue":{
                           "stringValue":"world"
                        }
                     }
                  ]
               }
            ],
            "fields":"userEnteredValue"
         }
      },
      {
         "addNamedRange":{
            "namedRange":{
               "name":"newRange",
               "range":{
                  "sheetId":123456,
                  "endRowIndex":2
               }
            }
         }
      }
   ]
}

Ответ

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

"replies":[
   {
      "addSheet":{
         "properties":{
            "sheetId":123456,
            "title":"Sheet3",
            "index":2,
            "sheetType":"GRID",
            "gridProperties":{
               "rowCount":1000,
               "columnCount":26
            }
         }
      }
   },
   {
      
   },
   {
      "addNamedRange":{
         "namedRange":{
            "namedRangeId":"2104325079",
            "name":"newRange",
            "range":{
               "sheetId":123456,
               "startRowIndex":0,
               "endRowIndex":2,
               "startColumnIndex":0,
               "endColumnIndex":26
            }
         }
      }
   }
]