В этом документе показано, как группировать вызовы API, чтобы уменьшить количество подключений, которые должен выполнить ваш клиент. Пакетная обработка может повысить эффективность приложения за счет уменьшения количества обращений по сети и увеличения пропускной способности.
Обзор
Каждое соединение, которое устанавливает ваш клиент, приводит к определенному количеству накладных расходов. API Google Sheets поддерживает пакетную обработку, что позволяет вашему клиенту помещать несколько объектов запроса, каждый из которых определяет один тип запроса для выполнения, в один пакетный запрос. Пакетный запрос может повысить производительность за счет объединения нескольких подзапросов в один вызов сервера и получения обратно одного ответа.
Мы рекомендуем пользователям всегда группировать несколько запросов вместе. Вот несколько примеров ситуаций, в которых можно использовать пакетную обработку:
- Вы только начали использовать API, и у вас есть много данных для загрузки.
- Вам необходимо обновить метаданные или свойства, такие как форматирование, для нескольких объектов.
- Вам нужно удалить много объектов.
Рекомендации по ограничениям, авторизации и зависимостям
Вот список других моментов, которые следует учитывать при пакетном обновлении:
- Каждый пакетный запрос, включая все подзапросы, учитывается как один запрос API в рамках вашего лимита использования .
- Пакетный запрос аутентифицируется один раз. Эта единая аутентификация применяется ко всем объектам пакетного обновления в запросе.
- Сервер обрабатывает подзапросы в том же порядке, в котором они появляются в пакетном запросе. Последние подзапросы могут зависеть от действий, предпринятых во время предыдущих подзапросов. Например, в одном и том же пакетном запросе пользователи могут вставлять текст в существующий документ, а затем стилизовать его.
Детали партии
Пакетный запрос состоит из одного вызова метода batchUpdate с несколькими подзапросами, например, для добавления и последующего форматирования электронной таблицы.
Каждый запрос проверяется перед применением. Все подзапросы в пакетном обновлении применяются атомарно. То есть, если какой-либо запрос недействителен, то все обновление завершается неудачей и ни одно из (потенциально зависимых) изменений не применяется.
Некоторые запросы предоставляют ответы с информацией о примененных запросах. Например, все запросы пакетного обновления для добавления объектов возвращают ответы, чтобы вы могли получить доступ к метаданным вновь добавленного объекта, таким как идентификатор или заголовок.
При таком подходе вы можете создать весь документ Google, используя один запрос пакетного обновления API с несколькими подзапросами.
Формат пакетного запроса
Запрос — это одиночный запрос JSON, содержащий несколько вложенных подзапросов с одним обязательным свойством: requests . Запросы формируются в виде массива отдельных запросов. Каждый запрос использует JSON для представления объекта запроса и хранения его свойств.
Формат пакетного ответа
Формат ответа на пакетный запрос аналогичен формату запроса. Ответ сервера содержит полный ответ одного объекта ответа.
Свойство основного объекта JSON называется replies . Ответы возвращаются в массиве, причем каждый ответ на один из запросов занимает тот же порядок индекса, что и соответствующий запрос. Некоторые запросы не имеют ответов, и ответ по этому индексу массива пуст.
Пример
В следующем примере показано использование пакетной обработки с API Таблиц.
Запрос
В этом примере пакетного запроса показано, как:
- Добавьте лист в существующую электронную таблицу с
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
}
}
}
}
]