Электронные таблицы могут состоять из нескольких листов, каждый из которых может иметь любое количество строк или столбцов. Ячейка — это место на пересечении определенной строки и столбца, которое может содержать значение данных. API Google Таблиц предоставляет ресурс 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 | FORMATTED_VALUE |
dateTimeRenderOption | СЕРИЙНЫЙ НОМЕР |
Обратите внимание: вам следует использовать dateTimeRenderOption
только в том случае, если valueRenderOption
не FORMATTED_VALUE
.
Нет явного ограничения на объем возвращаемых данных. Ошибки не возвращают данные. Пустые конечные строки и столбцы опускаются.
Ниже описаны методы единичного и пакетного получения. Примеры основных операций чтения см. в разделе «Основное чтение» .
Чтение одного диапазона
Чтобы прочитать один диапазон значений из электронной таблицы, используйте запрос spreadsheets.values.get
:
Скрипт приложений
Ява
JavaScript
Node.js
PHP
Питон
Руби
Ответ на этот запрос возвращается в виде объекта ValueRange
.
Чтение нескольких диапазонов
Чтобы прочитать несколько прерывистых диапазонов значений из электронной таблицы, используйте запрос spreadsheets.values.batchGet
, который позволяет указать несколько диапазонов для извлечения:
Скрипт приложений
Ява
JavaScript
Node.js
PHP
Питон
Руби
Ответ на этот запрос возвращается в виде объекта BatchGetValuesResponse
, который содержит spreadsheetId
и список объектов ValueRange
.
Писать
Для записи на лист вам понадобится идентификатор электронной таблицы, диапазон ячеек в нотации A1 и данные, которые вы хотите записать в соответствующий объект тела запроса. Дополнительную информацию об идентификаторах электронных таблиц и обозначении A1 см. в разделе Обзор API Google Sheets .
Для обновлений требуется действительный параметр ValueInputOption
. Для единичных обновлений это обязательный параметр запроса. Для пакетных обновлений этот параметр является обязательным в теле запроса. Параметр ValueInputOption
управляет тем, как следует интерпретировать входные данные и анализировать ли входные строки, как описано в следующей таблице:
ValueInputOption | Описание |
---|---|
RAW | Ввод не анализируется и вставляется как строка. Например, ввод «=1+2» помещает в ячейку строку, а не формулу «=1+2». (Нестроковые значения, такие как логические значения или числа, всегда обрабатываются как RAW .) |
USER_ENTERED | Ввод анализируется точно так же, как если бы он был введен в пользовательский интерфейс Таблиц. Например, «1 марта 2016 г.» становится датой, а «=1+2» — формулой. Форматы также могут быть выведены, поэтому «100,15 долларов США» становится числом с форматированием валюты. |
Ниже описаны методы единичного и пакетного обновления. Примеры основных операций записи см. в разделе «Базовые операции записи» .
Запись в один диапазон
Чтобы записать данные в один диапазон, используйте запрос spreadsheets.values.update
:
Скрипт приложений
Ява
JavaScript
Node.js
PHP
Питон
Руби
Тело запроса на обновление должно быть объектом ValueRange
, хотя единственное обязательное поле — это values
. Если указан range
, он должен соответствовать диапазону в URL-адресе. В ValueRange
вы можете дополнительно указать его majorDimension
. По умолчанию используется ROWS
. Если указано COLUMNS
, каждый внутренний массив записывается в столбец, а не в строку.
При обновлении значения без данных пропускаются. Чтобы очистить данные, используйте пустую строку ("").
Напишите несколько диапазонов
Если вы хотите записать несколько прерывистых диапазонов, вы можете использовать запрос spreadsheets.values.batchUpdate
:
Скрипт приложений
Ява
JavaScript
Node.js
PHP
Питон
Руби
Телом запроса пакетного обновления должен быть объект BatchUpdateValuesRequest
, который содержит ValueInputOption
и список объектов ValueRange
(по одному для каждого записанного диапазона). Каждый объект ValueRange
указывает свой собственный range
, majorDimension
и входные данные.
Добавить значения
Чтобы добавить данные после таблицы данных на листе, используйте запрос spreadsheets.values.append
:
Скрипт приложений
Ява
JavaScript
Node.js
PHP
Питон
Руби
Тело запроса на обновление должно быть объектом ValueRange
, хотя единственное обязательное поле — это values
. Если указан range
, он должен соответствовать диапазону в URL-адресе. В ValueRange
вы можете дополнительно указать его majorDimension
. По умолчанию используется ROWS
. Если указано COLUMNS
, каждый внутренний массив записывается в столбец, а не в строку.
Диапазон ввода используется для поиска существующих данных и поиска «таблицы» в этом диапазоне. Значения добавляются в следующую строку таблицы, начиная с первого столбца таблицы. Например, рассмотрим Sheet1
, который выглядит так:
А | Б | С | Д | Э | |
1 | х | й | я | ||
2 | х | й | я | ||
3 | |||||
4 | х | й | |||
5 | й | я | |||
6 | х | й | я | ||
7 |
На листе есть 2 таблицы: A1:C2
и B4:D6
. Добавленные значения будут начинаться с B7
для всех следующих входных range
:
-
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 Диске .