JAVA: Google Sheet API V4 入门二 ：基本写入

利用 Sheets API，您可以向单元格、范围、范围集以及整个工作表写入值和公式。 本页面上的示例说明了如何使用此 API 的 spreadsheets.values 集合实现一些常用的写入操作。

请注意，也可以使用 spreadsheet.batchUpdate 方法写入单元格值，如果您希望同步更新单元格格式设置或 spreadsheets.values 集合不会影响的其他属性，此方法将非常实用。不过，对于简单的值写入操作，使用 spreadsheets.values.update 或 spreadsheets.values.batchUpdate 更简单。

在这些示例中，占位符 spreadsheetId 用于表示您需要提供电子表格 ID 的位置，可以从电子表格网址中找到此 ID。要写入的范围在请求网址中使用 A1 表示法指定。

向单个范围写入数据

下面的 spreadsheets.values.update 请求会从一个新的空电子表格开始，将值写入范围 Sheet1!A1:D5。ValueInputOption 查询参数是一个必要参数，并确定是否解析写入的值（例如，是否将字符串转换为日期）。

请求正文是一个 ValueRange 对象，该对象对要写入的范围值进行了说明。majorDimension 字段确定是否将包含的数组解释为列或行数组。目标范围中的现有值将被替换。

请求协议如下所示。 读取和写入值指南介绍了如何使用 Google API 客户端内容库以不同语言实现写入。

PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A1:D5?valueInputOption=USER_ENTERED
{
  "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", "30/20/2016"],
    ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
  ],
}

响应将包含一个如下所示的 UpdateValuesResponse 对象：

{
  "spreadsheetId": spreadsheetId,
  "updatedRange": "Sheet1!A1:D5",
  "updatedRows": 5,
  "updatedColumns": 4,
  "updatedCells": 20,
}

生成的工作表将如下所示：

向范围选择性写入值

在向范围写入值时，将相应的数组元素设为 null 可以避免对某些现有单元格进行更改。 向单元格中写入空字符串也可以清除其数据。

下面的 spreadsheets.values.update 请求会从一个通过上面的示例生成并包含相同数据的工作表开始，将值写入范围 B1:D4，同时选择性保留某些单元格不变和清除其他单元格。ValueInputOption 查询参数是一个必要参数，并确定是否解析写入的值（例如，是否将字符串是否为日期）。

请求正文是一个 ValueRange 对象，该对象对要写入的范围值进行了说明。 majorDimension 字段指示数组是否为按列组织的值列表。

请求协议如下所示。 读取和写入值指南介绍了如何使用 Google API 客户端内容库以不同语言实现写入。

PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!B1?valueInputOption=USER_ENTERED
{
  "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": spreadsheetId,
  "updatedRange": "Sheet1!B1:D5",
  "updatedRows": 3,
  "updatedColumns": 2,
  "updatedCells": 6,
}

生成的工作表将如下所示：

请注意，尽管“Totals”行不是直接通过此请求更改，该行也会发生变化，因为其单元格包含依赖于已更改单元格的公式。

向多个范围写入数据

下面的 spreadsheets.values.batchUpdate 请求会从一个空白工作表开始，写入来自范围 Sheet1!A1:A4 和 Sheet1!B1:D2 的值。目标范围中的现有值将被替换。 请求正文将包含一个带 ValueInputOption（用于写入）的对象和一组对应于每个已写入范围的 ValueRange 对象。majorDimension 字段确定是否将包含的数组解释为列或行数组。

请求协议如下所示。 读取和写入值指南介绍了如何使用 Google API 客户端内容库以不同语言实现写入。

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values:batchUpdate
{
  "valueInputOption": "USER_ENTERED",
  "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": spreadsheetId,
  "totalUpdatedRows": 4,
  "totalUpdatedColumns": 4,
  "totalUpdatedCells": 10,
  "totalUpdatedSheets": 1,
  "responses": [
    {
      "spreadsheetId": spreadsheetId,
      "updatedRange": "Sheet1!A1:A4",
      "updatedRows": 4,
      "updatedColumns": 1,
      "updatedCells": 4,
    },
    {
      "spreadsheetId": spreadsheetId,
      "updatedRange": "Sheet1!B1:D2",
      "updatedRows": 2,
      "updatedColumns": 3,
      "updatedCells": 6,
    }
  ],
}

生成的工作表将如下所示：

写入值但不解析

下面的 spreadsheets.values.update 请求会从一个空白工作表开始，将值写入范围 Sheet1!A1:E1，不过将使用 RAW ValueInputOption 查询参数来防止将写入的字符串解析为公式、布尔值或数字；这些数据将在工作表中以字符串形式显示和对齐。

请求正文是一个 ValueRange 对象，该对象对要写入的范围值进行了说明。majorDimension 字段确定是否将包含的数组解释为列或行数组。目标范围中的现有值将被替换。

请求协议如下所示。 读取和写入值指南介绍了如何使用 Google API 客户端内容库以不同语言实现写入。

PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A1:E1?valueInputOption=RAW
{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Data", 123.45, true, "=MAX(D2:D4)", "10"]
  ],
}

响应将包含一个如下所示的 UpdateValuesResponse 对象：

{
  "spreadsheetId": spreadsheetId,
  "updatedRange": "Sheet1!A1:E1",
  "updatedRows": 1,
  "updatedColumns": 5,
  "updatedCells": 5,
}

生成的工作表将如下所示：

请注意“true”的居中方式以及它将成为原生的 TRUE 布尔值，“123.45”靠右对齐，因为它是一个数字，而“10”靠左对齐，因为它是一个字符串。公式不会解析，也将作为字符串显示。

追加值

从一个类似于下面表格的工作表开始：

根据上面的数据，以下 spreadsheets.values.append 请求将从第 3 行开始添加两行新值。ValueInputOption 查询参数是一个必要参数，并确定是否解析写入的值（例如，是否将字符串转换为日期）。

请求正文是一个 ValueRange 对象，该对象对要写入的范围值进行了说明。majorDimension 字段确定是否将包含的数组解释为列或行数组。

请求协议如下所示。 读取和写入值指南介绍了如何使用 Google API 客户端内容库以不同语言实现写入。

POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A1:E1:append?valueInputOption=USER_ENTERED
{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "3/20/2016"],
  ],
}

响应将包含一个如下所示的 AppendValuesResponse 对象：

{
  "spreadsheetId": spreadsheetId,
  "tableRange": "Sheet1!A1:D2",
  "updates": {
    "spreadsheetId": spreadsheetId,
    "updatedRange": "Sheet1!A3:D4",
    "updatedRows": 2,
    "updatedColumns": 4,
    "updatedCells": 8,
  }
}

生成的工作表将如下所示：