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