欄位遮罩是 API 呼叫端用來列出要求應傳回或更新的欄位。使用 FieldMask 可讓 API 避免不必要的工作，並提升效能。欄位遮罩可用於 Google 試算表 API 中的讀取和更新方法。
使用欄位遮罩讀取
試算表可能很大，而且您通常不需要讀取要求傳回的 Spreadsheet 資源的每個部分。您可以使用 fields 網址參數，限制 Google 試算表 API 回應中傳回的內容。為求最佳效能，請在回覆中明確列出您需要的欄位。
fields 參數的格式與 FieldMask 的 JSON 編碼相同。簡單來說，多個不同的欄位以半形逗號分隔，子欄位則以點號分隔。您可以使用 大寫字母與小寫字母混合或 以底線分隔的方式指定欄位名稱。為了方便起見，您可以將同類型中的多個子欄位列在括號內。
以下 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
}
}
}
}
}
]
}