API Google Таблиц позволяет записывать значения и формулы в ячейки, диапазоны, наборы диапазонов и целые листы. Примеры на этой странице иллюстрируют, как некоторые распространенные операции записи могут быть выполнены с помощью ресурса spreadsheets.values API Таблиц.
Обратите внимание, что значения ячеек также можно записывать с помощью метода spreadsheet.batchUpdate , который может быть полезен, если вы хотите одновременно обновить форматирование ячеек или другие свойства, на которые не влияет ресурс spreadsheets.values . Например, если вы хотите скопировать диапазон ячеек с одного листа на другой, перезаписывая при этом как формулу ячейки, так и форматирование ячейки, вы можете использовать метод UpdateCellsRequest с методом spreadsheet.batchUpdate .
Однако для простой записи значений проще использовать метод spreadsheets.values.update или метод spreadsheets.values.batchUpdate .
Эти примеры представлены в виде HTTP-запросов, которые не зависят от языка. Чтобы узнать, как реализовать запись на разных языках с помощью клиентских библиотек Google API, см. раздел Чтение и запись значений ячеек .
В этих примерах заполнитель SPREADSHEET_ID указывает, где вы должны указать идентификатор электронной таблицы , который можно найти по URL-адресу электронной таблицы. Диапазоны записи указываются с использованием нотации A1 . Пример диапазона: Лист1!A1:D5.
Напишите один диапазон
Начиная с новой пустой электронной таблицы, в следующем примере кода spreadsheets.values.update показано, как записать значения в диапазон. Параметр запроса ValueInputOption является обязательным и определяет, анализируются ли записанные значения (например, преобразуется ли строка в дату).
Тело запроса представляет собой объект ValueRange , описывающий записываемые значения диапазона. Поле majorDimension указывает, что массивы представляют собой списки значений, организованные по строкам. Существующие значения в целевом диапазоне перезаписываются.
Протокол запроса показан ниже.
PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?valueInputOption=VALUE_INPUT_OPTION{
"range": "Sheet1!A1:D5",
"majorDimension": "ROWS",
"values": [
["Item", "Cost", "Stocked", "Ship Date"],
["Wheel", "$20.50", "4", "3/1/2016"],
["Door", "$15", "2", "3/15/2016"],
["Engine", "$100", "1", "3/20/2016"],
["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
],
} Ответ состоит из объекта UpdateValuesResponse , такого как этот:
{
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!A1:D5",
"updatedRows": 5,
"updatedColumns": 4,
"updatedCells": 20,
}В результате лист выглядит следующим образом:
| А | Б | С | Д | |
| 1 | Элемент | Расходы | Запасено | Дата отправки |
| 2 | Колесо | 20,50 долларов США | 4 | 01.03.2016 |
| 3 | Дверь | 15 долларов США | 2 | 15.03.2016 |
| 4 | Двигатель | 100 долларов | 1 | 20.03.2016 |
| 5 | Итоги | 135,5 долларов США | 7 | 20.03.2016 |
Выборочная запись в диапазон
При записи значений в диапазон можно избежать изменения некоторых существующих ячеек, установив для соответствующих элементов массива значение null . Также можно очистить ячейку, записав в нее пустую строку ( "" ).
Начиная с листа, содержащего те же данные, что и в приведенном выше примере , в следующем примере кода spreadsheets.values.update показано, как записать значения в диапазон B1:D4, выборочно оставляя одни ячейки без изменений и очищая другие. Параметр запроса ValueInputOption является обязательным и определяет, анализируются ли записанные значения (например, преобразуется ли строка в дату).
Тело запроса представляет собой объект ValueRange , описывающий записываемые значения диапазона. Поле majorDimension указывает, что массивы представляют собой списки значений, организованные по столбцам.
Протокол запроса показан ниже.
PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!B1?valueInputOption=VALUE_INPUT_OPTION{
"range": "Sheet1!B1",
"majorDimension": "COLUMNS",
"values": [
[null,"$1","$2", ""],
[],
[null,"4/1/2016", "4/15/2016", ""]
]
} В поле values перечислены изменения, внесенные в каждый столбец диапазона. Первый массив указывает, что B1 следует оставить неизменным (из-за null элемента массива), а B4 следует очистить (пустая строка). Значения B2 и B3 обновлены. Третий массив выполняет те же операции со столбцом D, а второй пустой массив указывает, что столбец C следует оставить без изменений.
Ответ состоит из объекта UpdateValuesResponse такого как этот:
{
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!B1:D5",
"updatedRows": 3,
"updatedColumns": 2,
"updatedCells": 6,
}В результате лист выглядит следующим образом:
| А | Б | С | Д | |
| 1 | Элемент | Расходы | Запасено | Дата отправки |
| 2 | Колесо | 1,00 доллара США | 4 | 01.04.2016 |
| 3 | Дверь | 2 доллара | 2 | 15.04.2016 |
| 4 | Двигатель | 1 | ||
| 5 | Итоги | 3,00 доллара США | 7 | 15.04.2016 |
Обратите внимание, что строка «Итоги», хотя и не изменяется напрямую этим запросом, меняется, поскольку ее ячейки содержат формулы, зависящие от измененных ячеек.
Запись в несколько диапазонов
Начиная с чистого листа, в следующем примере кода spreadsheets.values.batchUpdate показано, как записать значения в диапазоны Sheet1!A1:A4 и Sheet1!B1:D2. Существующие значения в целевом диапазоне перезаписываются. Тело запроса состоит из объекта ValueInputOption , который показывает, как интерпретировать входные данные, и массива объектов ValueRange соответствующих каждому записанному диапазону. Поле majorDimension определяет, интерпретируются ли включенные массивы как массивы столбцов или строк.
Протокол запроса показан ниже.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchUpdate{
"valueInputOption": "VALUE_INPUT_OPTION",
"data": [
{
"range": "Sheet1!A1:A4",
"majorDimension": "COLUMNS",
"values": [
["Item", "Wheel", "Door", "Engine"]
]
},
{
"range": "Sheet1!B1:D2",
"majorDimension": "ROWS",
"values": [
["Cost", "Stocked", "Ship Date"],
["$20.50", "4", "3/1/2016"]
]
}
]
} Ответ состоит из объекта, в котором перечислены обновленные статистические данные ячеек, и массива объектов UpdateValuesResponse , по одному для каждого обновленного диапазона. Например:
{
"spreadsheetId": SPREADSHEET_ID,
"totalUpdatedRows": 4,
"totalUpdatedColumns": 4,
"totalUpdatedCells": 10,
"totalUpdatedSheets": 1,
"responses": [
{
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!A1:A4",
"updatedRows": 4,
"updatedColumns": 1,
"updatedCells": 4,
},
{
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!B1:D2",
"updatedRows": 2,
"updatedColumns": 3,
"updatedCells": 6,
}
],
}В результате лист выглядит следующим образом:
| А | Б | С | Д | |
| 1 | Элемент | Расходы | Запасено | Дата отправки |
| 2 | Колесо | 20,50 долларов США | 4 | 01.03.2016 |
| 3 | Дверь | |||
| 4 | Двигатель | |||
| 5 |
Запись значений без синтаксического анализа
Начиная с чистого листа, в следующем примере кода spreadsheets.values.update показано, как записать значения в диапазон Sheet1!A1:E1, но используется параметр запроса RAW ValueInputOption чтобы предотвратить анализ записанных строк как формул, логических значений, или цифры. Они отображаются в виде строк, а выравнивание текста на листе выравнивается.
Тело запроса представляет собой объект ValueRange , описывающий записываемые значения диапазона. Поле majorDimension указывает, что массивы представляют собой списки значений, организованные по строкам. Существующие значения в целевом диапазоне перезаписываются.
Протокол запроса показан ниже.
PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1?valueInputOption=RAW{
"range": "Sheet1!A1:E1",
"majorDimension": "ROWS",
"values": [
["Data", 123.45, true, "=MAX(D2:D4)", "10"]
],
} Ответ состоит из объекта UpdateValuesResponse такого как этот:
{
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!A1:E1",
"updatedRows": 1,
"updatedColumns": 5,
"updatedCells": 5,
}В результате лист выглядит следующим образом:
| А | Б | С | Д | Э | |
| 1 | Данные | 123,45 | истинный | =МАКС(D2:D4) | 10 |
| 2 |
Обратите внимание, что «ИСТИНА» выравнивается по центру и представляет собой логическое значение, тогда как «123,45» выравнивается по правому краю, поскольку это число, а «10» выравнивается по левому краю, поскольку это строка. Формула не анализируется и также отображается в виде строки.
Добавить значения
Начните с листа, подобного таблице ниже:
| А | Б | С | Д | |
| 1 | Элемент | Расходы | Запасено | Дата отправки |
| 2 | Колесо | 20,50 долларов США | 4 | 01.03.2016 |
| 3 |
В следующем примере кода spreadsheets.values.append показано, как добавить две новые строки значений, начиная со строки 3. Параметр запроса ValueInputOption является обязательным и определяет, анализируются ли записанные значения (например, преобразуется ли строка в дата).
Тело запроса представляет собой объект ValueRange , описывающий записываемые значения диапазона. Поле majorDimension указывает, что массивы представляют собой списки значений, организованные по строкам.
Протокол запроса показан ниже.
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1:append?valueInputOption=VALUE_INPUT_OPTION{
"range": "Sheet1!A1:E1",
"majorDimension": "ROWS",
"values": [
["Door", "$15", "2", "3/15/2016"],
["Engine", "$100", "1", "3/20/2016"],
],
} Ответ состоит из объекта AppendValuesResponse такого как этот:
{
"spreadsheetId": SPREADSHEET_ID,
"tableRange": "Sheet1!A1:D2",
"updates": {
"spreadsheetId": SPREADSHEET_ID,
"updatedRange": "Sheet1!A3:D4",
"updatedRows": 2,
"updatedColumns": 4,
"updatedCells": 8,
}
}В результате лист выглядит следующим образом:
| А | Б | С | Д | |
| 1 | Элемент | Расходы | Запасено | Дата отправки |
| 2 | Колесо | 20,50 долларов США | 4 | 01.03.2016 |
| 3 | Дверь | 15 долларов США | 2 | 15.03.2016 |
| 4 | Двигатель | 100 долларов | 1 | 20.03.2016 |
| 5 |