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，以便建立已命名或受保護的範圍。您可以在 Spreadsheet 回應主體中，使用 spreadsheets.get 方法取得現有區間的 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" } } ] }