您可以使用 Google 表格 API 创建、修改和删除已命名或受保护的范围。本页面上的示例说明了如何使用 Tables 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 会在对创建命名或保护范围的 Google 表格 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 个请求对象。第一种方法使用 UpdateNamedRangeRequest
,使用之前的 API 调用中的 NAMED_RANGE_ID
,将现有命名范围的名称更新为“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" } } ] }