借助 Google Sheets 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 请求的响应中返回。您可以使用 Spreadsheet
响应正文中的 spreadsheets.get
方法获取现有范围的 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 个请求对象。第一次调用使用 DeleteNamedRangeRequest
和之前的 API 调用中的 NAMED_RANGE_ID
删除现有的命名范围。第二项用例使用 DeleteProtectedRangeRequest
通过之前的 API 调用中的 PROTECTED_RANGE_ID
删除现有的范围保护。
请求协议如下所示。
POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID
:batchUpdate
{ "requests": [ { "deleteNamedRange": { "namedRangeId": "NAMED_RANGE_ID
", } }, { "deleteProtectedRange": { "protectedRangeId":PROTECTED_RANGE_ID
, } } ] }
更新命名或受保护的范围
以下 spreadsheets.batchUpdate
代码示例展示了如何使用 2 个请求对象。第一个请求使用之前的 API 调用中的 NAMED_RANGE_ID
,使用 UpdateNamedRangeRequest
将现有命名范围的名称更新为“InitialCounts”。第二项用例使用 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" } } ] }