欄位遮罩可讓 API 呼叫端列出要求應傳回或更新的欄位。使用 FieldMask 可讓 API 避免不必要的作業,並改善效能。欄位遮罩同時用於 Google Sheets API 中的讀取和更新方法。
使用欄位遮罩讀取
試算表可能相當龐大,通常不需要讀取要求傳回的 Spreadsheet
資源部分。您可以利用 fields
網址參數來限制 Sheets API 回應傳回的內容。為獲得最佳效能,請在回覆中明確列出您需要的欄位。
欄位參數的格式與 FieldMask 的 JSON 編碼相同。簡單來說,多個不同欄位以半形逗號分隔,而子欄位則以半形句號分隔。欄位名稱可以使用 camelCase 或 分隔_by_underscores。為了方便起見,您可以在括號中列出相同類型的多個子欄位。
以下 spreadsheets.get
要求範例使用 sheets.properties(sheetId,title,sheetType,gridProperties)
的欄位遮罩,僅擷取試算表中所有工作表中 SheetProperties
物件的工作表 ID、標題、SheetType
和 GridProperties
:
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 } } } } } ] }