Помимо значений, содержащихся в ячейках, электронная таблица включает в себя множество других типов данных, таких как:
- Размеры
- Форматы ячеек и границы
- Именованные диапазоны
- Защищенные ареалы
- Условное форматирование
Это лишь некоторые из множества типов данных, управляющих внешним видом и работой электронной таблицы. Метод spreadsheets.batchUpdate
позволяет обновлять любые из этих данных в таблице. Изменения группируются в пакет, поэтому, если один запрос не удается, никакие другие (потенциально зависимые) изменения не записываются.
На этой странице описаны основы использования метода spreadsheets.batchUpdate
. Если вам нужно читать и записывать значения ячеек, вы также можете использовать ресурс spreadsheets.values
описанный в разделе Чтение и запись значений ячеек .
Категории операций
Конкретные операции, поддерживаемые spreadsheets.batchUpdate
, можно сгруппировать в следующие общие категории:
Категория | Описание |
---|---|
Добавить (и дублировать ) | Добавлять новые объекты (иногда на основе старых, как в запросах на дубликаты). |
Обновление (и установка ) | Обновляет определенные свойства объекта, обычно оставляя старые свойства нетронутыми (тогда как запрос Set перезаписывает предыдущие данные). |
Удалить | Удалить объекты. |
Эти категории используются в следующем разделе для описания поведения конкретных операций.
Пакетные операции обновления
Метод spreadsheets.batchUpdate
принимает один или несколько объектов Request , каждый из которых определяет один тип запроса для выполнения. Существует множество различных типов запросов. Ниже представлена разбивка по типам запросов, сгруппированным по различным категориям.
Также имеются некоторые дополнительные запросы, имитирующие действия пользователя по манипулированию данными:
- AutoFillRequest
- CutPasteRequest
- CopyPasteRequest
- FindReplaceRequest
- PasteDataRequest
- TextToColumnsRequest
- SortRangeRequest
Пределы
Дополнительную информацию об ограничениях ячеек и строк в Google Таблицах см. в статье Файлы, которые можно хранить на Google Диске .
Полевые маски
Для многих запросов на обновление требуются маски полей. Это список полей, разделённый запятыми, для обновления только определённых полей объекта, оставляя остальные поля без изменений. Маска поля *
рассматривается как подстановочный знак и является сокращённой записью для указания всех полей в сообщении (это означает, что поле может вернуться к состоянию по умолчанию, если вы не укажете для него значение в запросе). Подробнее о масках полей см. в разделе Использование масок полей .
В следующем примере UpdateSpreadsheetPropertiesRequest
используется для обновления только заголовка электронной таблицы:
Запрос:
POST .../v4/spreadsheets/spreadsheetId:batchUpdate
Текст запроса:
{ "requests": [{ "updateSpreadsheetProperties": { "properties": {"title": "TITLE"}, "fields": "title" } }] }
Замените TITLE новым заголовком электронной таблицы.
Ответы
При обновлении электронной таблицы некоторые типы запросов могут возвращать ответы. Они возвращаются в массиве, где каждый ответ занимает тот же индекс, что и соответствующий запрос. Некоторые запросы не имеют ответов, и для них ответ пустой.
Обычно запросы на добавление имеют ответы, возвращающие такую информацию, как идентификатор добавленного объекта. Список поддерживаемых ответов см. в разделе Ответы .
Пример
Следующий пример кода выполняет эти действия:
- Обновляет заголовок электронной таблицы, используя переменную
title
. - Находит и заменяет значения ячеек в электронной таблице, используя переменные
find
иreplacement
.