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

Google Sheets API 可讓您建立、修改及刪除已命名或受保護的 範圍。本頁的範例將說明如何達成一些常見的 透過 Sheets API 執行試算表作業。

這些範例是以 HTTP 要求的形式呈現 中立。如要瞭解如何使用 Google API 用戶端程式庫，請參閱 試算表。

在這些範例中，預留位置 SPREADSHEET_ID 和 SHEET_ID 代表這些 ID 的提供位置。您可以找到這份試算表 ID。您可以 工作表 ID spreadsheets.get 方法。 範圍是使用 A1 標記法來指定。一個 範例範圍是 Sheet1!A1:D5

此外，預留位置 NAMED_RANGE_ID 和 PROTECTED_RANGE_ID 提供已命名和受保護的範圍的 ID。namedRangeId和 系統會使用 protectedRangeId 來提出更新或刪除要求 相關聯的範圍這個 ID 會在試算表 API 回應中傳回 要求會建立已命名或受保護的範圍。您可以取得現有 Pod 的 ID 包含 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": [
              "charlie@example.com",
              "sasha@example.com"
            ]
          }
        },
        "fields": "namedRangeId,warningOnly,editors"
      }
    }
  ]
}