使用欄位遮罩

API 呼叫者可透過欄位遮罩列出要求應傳回或更新的欄位。使用 FieldMask 可讓 API 避免不必要的工作，進而提升效能。在 Google 試算表 API 中，讀取和更新方法都會使用欄位遮罩。

使用欄位遮罩讀取

試算表可能很大，而且您通常不需要讀取要求傳回的資源中每個部分。Spreadsheet您可以使用 fields 網址參數，限制在 Google 試算表 API 回應中傳回的內容。為達到最佳成效，請在回覆中明確列出您需要的欄位。

欄位參數的格式與 FieldMask 的 JSON 編碼相同。 簡單來說，多個不同欄位會以半形逗號分隔，子欄位則以半形句號分隔。欄位名稱可以指定為 camelCase 或以底線分隔。為方便起見，同一類型的多個子欄位可以列在括號內。

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