使用字段掩码

API 调用方可通过字段掩码列出请求应返回或更新的字段。使用 FieldMask 可以使 API 避免不必要的工作,从而提高性能。Google 表格 API 中的读取和更新方法会使用字段掩码。

使用字段掩码进行读取

电子表格可能会很大,并且通常情况下,您不需要读取请求返回的 Spreadsheet 资源的每个部分。您可以使用 fields 网址参数限制 Sheets API 响应中返回的内容。为获得最佳性能,请在回复中仅明确列出您需要的字段

字段参数的格式与 FieldMask 的 JSON 编码相同。简而言之,多个不同字段用英文逗号分隔,子字段用英文句点分隔。字段名称可以在 camelCasespecified_by_underscores 中指定。为方便起见,可在括号中列出多个相同类型的子字段。

以下 spreadsheets.get 请求示例使用 sheets.properties(sheetId,title,sheetType,gridProperties) 字段掩码来仅提取电子表格中所有工作表 SheetProperties 对象的工作表 ID、标题、SheetTypeGridProperties

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
            }
          }
        }
      }
    }
  ]
}