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" } } ] }