使用欄位遮罩

欄位遮罩可讓 API 呼叫端列出要求應有的欄位 傳回或更新。使用 FieldMask ，讓 API 避免不必要的作業，並改善效能。欄位遮罩 用於 Google Sheets API 的讀取和更新方法。

使用欄位遮罩讀取

試算表可能相當龐大，通常不需要 Spreadsheet敬上 讀取要求傳回的資源。您可以在 使用 Sheets API 回應，使用 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 哪些欄位即將變更。 更新要求會忽略欄位遮罩中未指定的任何欄位； 以維持原值

你也可以在更新後的訊息中不指定欄位，藉此取消設定。 將該欄位新增至遮罩中。這麼做會清除欄位之前的值 。

更新欄位遮罩的語法與讀取欄位遮罩的語法相同。

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