已命名的范围和受保护的范围

借助 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 请求的响应中返回。您可以使用 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 个请求对象。第一个示例使用 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 将现有已命名范围的名称更新为“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"
      }
    }
  ]
}