使用字段掩码

API 调用方可通过字段掩码列出请求应显示的字段 return 或更新。使用 FieldMask 可让 API 避免不必要的工作并提升性能。字段掩码 用于 Google Sheets API 中的 read 和 update 方法。

使用字段掩码进行读取

电子表格可能很大，而且通常不需要 Spreadsheet 读取请求返回的资源您可以限制在 Sheets API 响应，使用 fields 网址参数。最佳 性能 仅明确列出您需要的字段 。

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 正在更改哪些字段。通过 update 请求会忽略字段掩码中未指定的任何字段， 保留其当前值

您也可以取消设置某个字段，只需不在更新后的消息中指定该字段即可，但 将该字段添加到掩码。这会清除 。

更新字段掩码的语法与读取字段掩码的语法相同。

以下示例使用 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
            }
          }
        }
      }
    }
  ]
}