Базовое письмо

API Google Таблиц позволяет записывать значения и формулы в ячейки, диапазоны, наборы диапазонов и целые таблицы. Примеры на этой странице иллюстрируют, как некоторые распространённые операции записи можно выполнить с помощью ресурса spreadsheets.values ​​API Таблиц.

Обратите внимание, что значения ячеек также можно записывать с помощью метода spreadsheet.batchUpdate . Это может быть полезно, если вы хотите одновременно обновить форматирование ячеек или другие свойства, на которые ресурс spreadsheets.values ​​не влияет. Например, если вы хотите скопировать диапазон ячеек с одного листа на другой, перезаписав как формулу ячейки, так и форматирование, вы можете использовать метод UpdateCellsRequest с методом spreadsheet.batchUpdate .

Однако для простой записи значений проще использовать метод spreadsheets.values.update или метод spreadsheets.values.batchUpdate .

Эти примеры представлены в виде HTTP-запросов, чтобы не зависеть от языка. Чтобы узнать, как реализовать запись на разных языках с помощью клиентских библиотек API Google, см. статью Чтение и запись значений ячеек .

В этих примерах плейсхолдер SPREADSHEET_ID указывает, где следует указать идентификатор электронной таблицы , который можно узнать по URL-адресу таблицы. Диапазоны для записи указываются с использованием нотации A1 . Пример диапазона: Sheet1!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,
}

Полученный лист выглядит следующим образом:

Записывать выборочно в диапазон

При записи значений в диапазон можно избежать изменения некоторых существующих ячеек, установив соответствующие элементы массива в 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,
}

Полученный лист выглядит следующим образом:

Обратите внимание, что строка «Итоги», хотя и не изменяется напрямую этим запросом, изменяется, поскольку ее ячейки содержат формулы, которые зависят от измененных ячеек.

Запись в несколько диапазонов

Следующий пример кода 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,
    }
  ],
}

Полученный лист выглядит следующим образом:

Запись значений без разбора

Следующий пример кода 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,
}

Полученный лист выглядит следующим образом:

Обратите внимание, что «ИСТИНА» центрировано и является логическим значением, тогда как «123.45» выравнивается по правому краю, поскольку это число, а «10» — по левому краю, поскольку это строка. Формула не анализируется и также отображается как строка.

Добавить значения

Начните с листа, подобного представленной ниже таблице:

В следующем примере кода 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,
  }
}

Полученный лист выглядит следующим образом: