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

借助 Google Sheets API，您可以创建、修改和删除命名或受保护 范围。本页面上的示例说明了如何实现一些常见的 使用 Sheets API 实现 Google 表格操作。

这些示例以 HTTP 请求的形式呈现， 中性。了解如何使用 请参阅更新 电子表格。

在这些示例中，占位符 SPREADSHEET_ID 和 SHEET_ID 指明提供这些 ID 的位置。您可以在电子表格 ID。您可以获得 工作表 ID spreadsheets.get 方法。通过 范围使用 A1 表示法指定。一个 示例范围是“Sheet1!A1:D5”。

此外，占位符 NAMED_RANGE_ID 和 PROTECTED_RANGE_ID 用于提供已命名范围和受保护的范围的 ID。namedRangeId 和 protectedRangeId 在请求更新或删除 关联的范围。此 ID 会在对 Sheets API 的响应中返回 请求来创建命名或保护范围。您可以从 范围 spreadsheets.get 方法，位于 Spreadsheet 响应正文。

添加命名或保护范围

以下 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 使用 NAMED_RANGE_ID 删除现有的命名范围， 之前的 API 调用第二项使用 DeleteProtectedRangeRequest 使用 PROTECTED_RANGE_ID 删除现有的范围保护 从之前的 API 调用中获取的

请求协议如下所示。

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 使用 NAMED_RANGE_ID 将现有命名范围的名称更新为“InitialCounts” 从之前的 API 调用中获取的第二项使用 UpdateProtectedRangeRequest 更新现有保护范围，使其现在保护 范围。通过 Editors 方法 仅允许所列用户编辑这些单元格。此请求使用 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": [
              "[e-mail]",
              "[e-mail]"
            ]
          }
        },
        "fields": "namedRangeId,warningOnly,editors"
      }
    }
  ]
}