Google 試算表 API 可讓您建立、修改及刪除已命名或受保護的範圍。本頁面的範例將說明如何使用試算表 API 完成一些常見的試算表作業。
這些範例是以 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。對試算表 API 要求建立已命名或受保護的範圍的回應時，會傳回 ID。您可以使用 spreadsheets.get 方法在 Spreadsheet 回應主體中取得現有範圍的 ID。
新增已命名或受保護範圍
以下 spreadsheets.batchUpdate 程式碼範例說明如何使用 2 個要求物件。第一個會使用 AddNamedRangeRequest 將範圍 A1:E3 指派為「計數」。第二種方法則是使用 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 個要求物件。前者會使用先前 API 呼叫中的 NAMED_RANGE_ID，使用 DeleteNamedRangeRequest 刪除現有的已命名範圍。第二個方法是使用 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"
}
}
]
}