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

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,
}

В результате лист выглядит следующим образом:

Выборочная запись в диапазон

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

В результате лист выглядит следующим образом: