Электронные таблицы могут содержать несколько листов, каждый из которых может иметь любое количество строк или столбцов. Ячейка — это место на пересечении определенной строки и столбца, и она может содержать значение данных. API Google Sheets предоставляет ресурс spreadsheets.values , позволяющий читать и записывать значения.
На этой странице описаны основные принципы использования ресурса spreadsheets.values . Если вам необходимо вставить строки или обновить форматирование и другие свойства листа, вы должны использовать метод spreadsheets.batchUpdate , описанный в разделе «Обновление электронных таблиц» .
Методы
Ресурс spreadsheets.values предоставляет следующие методы для чтения и записи значений, каждый из которых предназначен для выполнения определенной задачи:
| Доступ к полигону | Чтение | Письмо |
|---|---|---|
| Один диапазон | spreadsheets.values.get | spreadsheets.values.update |
| Несколько диапазонов | spreadsheets.values.batchGet | spreadsheets.values.batchUpdate |
| Добавление | spreadsheets.values.append |
В целом, целесообразно комбинировать несколько операций чтения или обновления с помощью методов batchGet и batchUpdate (соответственно), поскольку это повышает эффективность.
Примеры каждого из этих методов можно найти на страницах с примерами базового чтения и базового письма . Чтобы увидеть все примеры, перейдите на страницу обзора примеров .
Читать
Для чтения значений данных из листа вам потребуется идентификатор электронной таблицы и обозначение диапазона в формате A1. Указание диапазона без идентификатора листа ( A1:B2 ) означает, что запрос будет выполнен на первом листе электронной таблицы. Дополнительную информацию об идентификаторах электронных таблиц и обозначении A1 см. в разделе «Обзор API Google Sheets» .
Формат выходных данных определяется несколькими необязательными параметрами запроса:
| Параметр формата | Значение по умолчанию |
|---|---|
majorDimension | РЯДЫ |
valueRenderOption | ОТФОРМАТИРОВАННОЕ_ЗНАЧЕНИЕ |
dateTimeRenderOption | СЕРИЙНЫЙ НОМЕР |
Обратите внимание, что dateTimeRenderOption следует использовать только в том случае, если значение valueRenderOption не равно FORMATTED_VALUE .
Нет явного ограничения на объем возвращаемых данных. В случае ошибок данные не возвращаются. Пустые строки и столбцы в конце строки опускаются.
Ниже описаны методы получения отдельных данных и пакетного чтения. Примеры основных операций чтения см. в разделе «Основы чтения» .
Прочитать один диапазон
Для чтения диапазона значений из электронной таблицы используйте запрос spreadsheets.values.get :
Apps Script
Java
JavaScript
Node.js
PHP
Python
Руби
В ответ на этот запрос возвращается объект ValueRange .
Прочитать несколько диапазонов
Для чтения нескольких несмежных диапазонов значений из электронной таблицы используйте запрос spreadsheets.values.batchGet , который позволяет указать несколько диапазонов для получения:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Руби
В ответ на этот запрос возвращается объект BatchGetValuesResponse , содержащий spreadsheetId и список объектов ValueRange .
Писать
Для записи данных в таблицу вам потребуется идентификатор электронной таблицы, диапазон ячеек в формате A1 и данные, которые вы хотите записать, в соответствующем объекте тела запроса. Дополнительную информацию об идентификаторах электронных таблиц и формате A1 см. в разделе «Обзор API Google Sheets» .
Для обновлений требуется действительный параметр ValueInputOption . Для единичных обновлений это обязательный параметр запроса. Для пакетных обновлений этот параметр необходим в теле запроса. Параметр ValueInputOption определяет, как следует интерпретировать входные данные и следует ли анализировать входные строки, как описано в следующей таблице:
ValueInputOption | Описание |
|---|---|
RAW | Вводимые данные не анализируются и вставляются как строка. Например, ввод "=1+2" помещает в ячейку строку, а не формулу "=1+2". (Нестроковые значения, такие как логические значения или числа, всегда обрабатываются как RAW .) |
USER_ENTERED | Вводимые данные обрабатываются точно так же, как если бы они были введены в пользовательский интерфейс Google Sheets. Например, "1 марта 2016 г." становится датой, а "=1+2" — формулой. Форматы также могут быть определены автоматически, поэтому "$100.15" становится числом с денежным форматированием. |
Ниже описаны методы сингулярного и пакетного обновления. Примеры основных операций записи см. в разделе «Основы записи» .
Запись в один диапазон
Для записи данных в один диапазон используйте запрос spreadsheets.values.update :
Apps Script
Java
JavaScript
Node.js
PHP
Python
Руби
Тело запроса на обновление должно представлять собой объект ValueRange , хотя единственным обязательным полем является values . Если указан range , он должен совпадать с диапазоном в URL-адресе. В ValueRange можно дополнительно указать его majorDimension . По умолчанию используется ROWS . Если указан COLUMNS , каждый внутренний массив записывается в столбец, а не в строку.
При обновлении значения, не содержащие данных, пропускаются. Для очистки данных используйте пустую строку (").
Напишите несколько диапазонов
Если вам нужно записать несколько несмежных диапазонов, вы можете использовать запрос spreadsheets.values.batchUpdate :
Apps Script
Java
JavaScript
Node.js
PHP
Python
Руби
Тело запроса на пакетное обновление должно представлять собой объект BatchUpdateValuesRequest , содержащий ValueInputOption и список объектов ValueRange (по одному для каждого записанного диапазона). Каждый объект ValueRange указывает свой собственный range , majorDimension и входные данные.
Добавить значения
Для добавления данных после таблицы данных на листе используйте запрос spreadsheets.values.append :
Apps Script
Java
JavaScript
Node.js
PHP
Python
Руби
Тело запроса на обновление должно представлять собой объект ValueRange , хотя единственным обязательным полем является values . Если указан range , он должен совпадать с диапазоном в URL-адресе. В ValueRange можно дополнительно указать его majorDimension . По умолчанию используется ROWS . Если указан COLUMNS , каждый внутренний массив записывается в столбец, а не в строку.
Диапазон ввода используется для поиска существующих данных и нахождения «таблицы» в пределах этого диапазона. Значения добавляются к следующей строке таблицы, начиная с первого столбца. Например, рассмотрим Sheet1 , который выглядит следующим образом:
| А | Б | С | Д | Е | |
| 1 | х | й | з | ||
| 2 | х | й | з | ||
| 3 | |||||
| 4 | х | й | |||
| 5 | й | з | |||
| 6 | х | й | з | ||
| 7 |
На листе находятся 2 таблицы: A1:C2 и B4:D6 . Добавленные значения для всех следующих range будут начинаться с ячейки B7 :
-
Sheet1, потому что он проанализирует все данные на листе и определит, что таблица вB4:D6является последней таблицей. -
B4илиC5:D5, потому что оба они находятся в таблицеB4:D6. -
B2:D4, потому что последняя таблица в диапазоне — это таблицаB4:D6(несмотря на то, что она также содержит таблицуA1:C2). -
A3:G10, потому что последняя таблица в диапазоне — это таблицаB4:D6(несмотря на то, что она начинается перед ней и заканчивается после нее).
При вводе данных в следующих range запись не начиналась бы с B7 :
- Запись из ячейки
A1начнется с ячейкиA3, поскольку она находится в таблицеA1:C2. - В
E4запись начнётся сE4, потому что она отсутствует в какой-либо таблице. (ВA4запись начнётся сA4по тем же причинам.)
Кроме того, вы можете выбрать, хотите ли вы перезаписать существующие данные после таблицы или вставить новые строки с новыми данными. По умолчанию ввод перезаписывает данные после таблицы. Чтобы записать новые данные в новые строки, используйте параметр InsertDataOption и укажите insertDataOption=INSERT_ROWS .
Чтобы узнать больше об ограничениях на ячейки и строки в Google Таблицах, см. раздел «Файлы, которые можно хранить в Google Диск» .