API 调用方可以使用字段掩码来列出请求应返回或更新的字段。通过使用 FieldMask，该 API 可避免不必要的工作并提高性能。Google 表格 API 中的读取和更新方法会使用字段掩码。
使用字段掩码进行读取
电子表格可能很大，并且通常并不需要读取请求返回的 Spreadsheet 资源的每个部分。您可以使用 fields 网址参数限制在 Sheets API 响应中返回的内容。为获得最佳性能，请在回复中仅明确列出您需要的字段。
fields 参数的格式与 FieldMask 的 JSON 编码相同。简而言之，多个不同字段用英文逗号分隔，子字段用英文句点分隔。字段名称可以在 camelCase 或 specified_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
}
}
}
}
}
]
}