欄位遮罩可讓 API 呼叫端列出要求應有的欄位 傳回或更新。使用 FieldMask ,讓 API 避免不必要的作業,並改善效能。欄位遮罩 用於 Google Sheets API 的讀取和更新方法。
使用欄位遮罩讀取
試算表可能相當龐大,通常不需要
Spreadsheet
敬上
讀取要求傳回的資源。您可以在
使用 Sheets API 回應,使用 fields
網址參數。最佳
成效
明確列出您需要的欄位
回覆。
欄位參數的格式與 FieldMask 的 JSON 編碼。 簡單來說,多個不同欄位以半形逗號分隔,而子欄位為 以點分隔欄位名稱可用 camelCase 或 separated_by_underscores。為了方便起見,請從同一個區域中使用多個子欄位 類型可列在括弧中。
下列
spreadsheets.get
要求
範例會使用 sheets.properties(sheetId,title,sheetType,gridProperties)
的欄位遮罩
只會擷取工作表 ID、標題
SheetType
和
GridProperties
/
SheetProperties
物件:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties(sheetId,title,sheetType,gridProperties)
這個方法呼叫的回應是
Spreadsheet
敬上
物件,其中包含欄位遮罩中要求的元件。請注意,
sheetType=OBJECT
不含 gridProperties
:
{ "sheets": [ { "properties": { "sheetId":SHEET_ID
, "title": "TITLE
", "sheetType": "GRID", "gridProperties": { "rowCount": 1000, "columnCount": 25 } } }, { "properties": { "sheetId":SHEET_ID
, "title": "TITLE
", "sheetType": "OBJECT" } } ] }
更新欄位遮罩
有時候,您只需要更新物件中的某些欄位,
其他欄位保持不變在
spreadsheets.batchUpdate
敬上
作業會使用欄位遮罩來告知 API 哪些欄位即將變更。
更新要求會忽略欄位遮罩中未指定的任何欄位;
以維持原值
你也可以在更新後的訊息中不指定欄位,藉此取消設定。 將該欄位新增至遮罩中。這麼做會清除欄位之前的值 。
更新欄位遮罩的語法與讀取欄位遮罩的語法相同。
以下範例使用
AddSheetRequest
敬上
即可新增 Grid
類型的工作表,凍結第一列,並將新的工作表上色
工作表標籤中的紅色:
POST https://sheets.googleapis.com/v1/spreadsheets/spreadsheetId:batchUpdate
{ "spreadsheetId": "SPREADSHEET_ID
", "replies": [ { "addSheet": { "properties": { "sheetId":SHEET_ID
, "title": "TITLE
", "index": 6, "sheetType": "GRID", "gridProperties": { "rowCount": 1000, "columnCount": 26, "frozenRowCount": 1 }, "tabColor": { "red": 0.003921569 }, "tabColorStyle": { "rgbColor": { "red": 0.003921569 } } } } } ] }