除了单元格中包含的值数据之外,电子表格还包含许多其他类型的数据,例如:
- 尺寸
- 单元格格式和边框
- 命名的范围
- 受保护的范围
- 条件格式
这些是控制电子表格外观和操作的众多数据种类的一部分。使用 spreadsheets.batchUpdate
方法,您可以更新上述任何电子表格详细信息。更改会分批进行,因此如果一个请求失败,则系统不会写入其他(潜在相关的)更改。
本页面介绍了使用 spreadsheets.batchUpdate
方法的基础知识。如果您需要读取和写入单元格值数据,还可以使用读取和写入单元格值中所述的 spreadsheets.values
资源。
操作的类别
spreadsheets.batchUpdate
支持的特定操作可分为以下几个大类:
类别 | 说明 |
---|---|
添加(和复制) | 添加新对象(有时基于旧对象,如在“重复”请求中)。 |
Update(和 Set) | 更新对象的某些属性,通常保留旧属性(而 Set 请求会覆盖之前的数据)。 |
删除 | 移除对象。 |
下一部分将使用这些类别来描述具体操作的行为。
批量更新操作
spreadsheets.batchUpdate
方法的工作原理是获取一个或多个 Request 对象,每个对象都指定一种要执行的请求。有很多不同类型的请求。下面是各种请求类型,它们按类别分为不同的组
此外,还有一些请求会模拟用户的数据操作操作:
- AutoFillRequest
- CutPasteRequest
- CopyPasteRequest
- FindReplaceRequest
- PasteDataRequest
- TextToColumnsRequest
- SortRangeRequest
限制
如需详细了解 Google 表格中的单元格和行数上限,请参阅可存储在 Google 云端硬盘中的文件。
字段掩码
许多“更新”请求都需要字段掩码。这些字段是以英文逗号分隔的字段列表,用于仅更新对象中的特定字段,同时保持其他字段不变。字段掩码 *
会被视为通配符,是一种简写形式,用于表示消息中的每个字段(这意味着,如果您未在请求中为某个字段指定值,该字段可能会还原为其默认状态)。如需详细了解字段掩码,请参阅使用字段掩码。
以下示例使用 UpdateSpreadsheetPropertiesRequest
仅更新电子表格的标题:
请求:
POST .../v4/spreadsheets/spreadsheetId:batchUpdate
请求正文:
{
"requests": [{
"updateSpreadsheetProperties": {
"properties": {"title": "TITLE"},
"fields": "title"
}
}]
}
将 TITLE 替换为电子表格的新标题。
响应
在更新电子表格时,某些类型的请求可能会返回响应。这些响应以数组的形式返回,并且每个响应与对应的请求占用相同的索引。一些请求没有响应,而对于这些请求,响应为空。
通常,“添加”请求具有返回信息(例如所添加对象的 ID)的响应。如需查看支持的响应列表,请参阅响应。
示例
以下代码示例将执行这些操作:
- 使用
title
变量更新电子表格的标题。 - 使用
find
和replacement
变量查找并替换电子表格中的单元格值。