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
。如果試算表 API 要求會建立已命名或受保護的範圍,系統就會在回應中傳回 ID。您可以在 Spreadsheet
回應主體中使用 spreadsheets.get
方法取得現有範圍的 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 個要求物件。第一個使用 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
使用先前 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" } } ] }