已命名 (&A)；受保護範圍

您可以使用 Google Sheets API 建立、修改及刪除具名或受保護的範圍。本頁的範例說明如何透過 Google 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。在建立已命名或受保護範圍的 Sheets API 要求的回應中，系統會傳回 ID。您可以使用 spreadsheets.get 方法，在 Spreadsheet 回應主體中取得現有範圍的 ID。

新增具名或受保護的範圍

以下程式碼範例說明如何使用 2 個要求物件。spreadsheets.batchUpdate第一個範例使用 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
        }
      }
    }
  ]
}

刪除已命名或受保護的範圍

以下程式碼範例說明如何使用 2 個要求物件。spreadsheets.batchUpdate第一個範例會使用 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,
      }
    }
  ]
}

更新已命名或受保護的範圍

以下程式碼範例說明如何使用 2 個要求物件。spreadsheets.batchUpdate第一個範例使用 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"
      }
    }
  ]
}