借助 Google 表格 API，您可以创建、修改和删除命名或受保护的范围。本页面上的示例说明了如何使用 Sheets API 实现一些常见的 Google 表格操作。
为保证语言中立性，这些示例以 HTTP 请求的形式呈现。如需了解如何使用 Google API 客户端库以不同语言实现批量更新，请参阅更新电子表格。
在这些示例中，占位符 SPREADSHEET_ID 和 SHEET_ID 表示您应提供相应 ID 的位置。您可以在电子表格网址中找到电子表格 ID。您可以使用 spreadsheets.get 方法获取工作表 ID。范围使用 A1 表示法指定。示例范围为 Sheet1!A1:D5。
此外，占位符 NAMED_RANGE_ID 和 PROTECTED_RANGE_ID 提供命名范围和受保护范围的 ID。在发出更新或删除关联范围的请求时，会使用 namedRangeId 和 protectedRangeId。ID 会在创建命名或保护范围的 Sheets API 请求的响应中返回。您可以使用 spreadsheets.get 方法在 Spreadsheet 响应正文中获取现有范围的 ID。
添加命名或保护范围
以下 spreadsheets.batchUpdate 代码示例展示了如何使用 2 个请求对象。第一个请求对象使用 AddNamedRangeRequest 将范围 A1:E3 命名为“Counts”。第二个请求对象使用 AddProtectedRangeRequest 为范围 A4:E4 附加警告级保护。此级别的保护仍然允许编辑范围内的单元格，但会在更改前显示警告。
这些请求会返回 AddNamedRangeResponse 和 AddProtectedRangeResponse，其中包含范围 ID 和属性。
请求协议如下所示。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"addNamedRange": {
"namedRange": {
"name": "Counts",
"range": {
"sheetId": SHEET_ID,
"startRowIndex": 0,
"endRowIndex": 3,
"startColumnIndex": 0,
"endColumnIndex": 5,
},
}
}
},
{
"addProtectedRange": {
"protectedRange": {
"range": {
"sheetId": SHEET_ID,
"startRowIndex": 3,
"endRowIndex": 4,
"startColumnIndex": 0,
"endColumnIndex": 5,
},
"description": "Protecting total row",
"warningOnly": true
}
}
}
]
}
删除命名或保护范围
以下 spreadsheets.batchUpdate 代码示例展示了如何使用 2 个请求对象。第一个请求对象将使用之前 API 调用中的 NAMED_RANGE_ID 使用 DeleteNamedRangeRequest 删除现有命名范围。第二个请求对象将使用从之前的 API 调用中获取的 PROTECTED_RANGE_ID 使用 DeleteProtectedRangeRequest 删除现有范围保护。
请求协议如下所示。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"deleteNamedRange": {
"namedRangeId": "NAMED_RANGE_ID",
}
},
{
"deleteProtectedRange": {
"protectedRangeId": PROTECTED_RANGE_ID,
}
}
]
}
更新命名或保护范围
以下 spreadsheets.batchUpdate 代码示例展示了如何使用 2 个请求对象。第一个请求对象使用 UpdateNamedRangeRequest 将现有命名范围的名称更新为“InitialCounts”，并使用之前 API 调用中的 NAMED_RANGE_ID。第二个请求使用 UpdateProtectedRangeRequest 更新现有保护范围，使其现在保护相同的命名范围。Editors 方法仅允许列出的用户修改这些单元格。此请求使用上一个 API 调用中的 NAMED_RANGE_ID 和 PROTECTED_RANGE_ID。
请求协议如下所示。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID:batchUpdate
{
"requests": [
{
"updateNamedRange": {
"namedRange": {
"namedRangeId": NAMED_RANGE_ID,
"name": "InitialCounts",
},
"fields": "name",
}
},
{
"updateProtectedRange": {
"protectedRange": {
"protectedRangeId": PROTECTED_RANGE_ID,
"namedRangeId": NAMED_RANGE_ID,
"warningOnly": false,
"editors": {
"users": [
"charlie@example.com",
"sasha@example.com"
]
}
},
"fields": "namedRangeId,warningOnly,editors"
}
}
]
}