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

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

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

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

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

В этих примерах заполнитель 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,
}

В результате получилась следующая таблица:

Обратите внимание, что "TRUE" центрировано и является логическим значением, тогда как "123.45" выравнивается по правому краю, поскольку это число, а "10" выравнивается по левому краю, поскольку это строка. Формула не анализируется и также отображается как строка.

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

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

Приведенный ниже пример кода spreadsheets.values.append показывает, как добавить две новые строки значений, начиная с третьей строки. Параметр запроса 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,
  }
}

В результате получился следующий документ: