使用欄位遮罩

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

如要比較不使用欄位遮罩和使用欄位遮罩時，回應本文中傳回的內容，請參閱「處理部分資源」。

使用欄位遮罩讀取

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

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

下列presentations.get方法要求範例使用 slides.pageElements(objectId,size,transform) 的欄位遮罩，只擷取簡報中所有投影片上 pageElement 物件的物件 ID Size 和轉換：

GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)

這個方法呼叫的回應是 presentations 物件，其中包含欄位遮罩中要求的元件：

{
  "slides": [
    {
      "pageElements": [
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311708,
            "translateY": 744575,
            "unit": "EMU"
          }
        },
        {
          "objectId": "OBJECT_ID",
          "size": {
            "width": {
              "magnitude": 3000000,
              "unit": "EMU"
            },
            "height": {
              "magnitude": 3000000,
              "unit": "EMU"
            }
          },
          "transform": {
            "scaleX": 1,
            "scaleY": 1
            "translateX": 311700,
            "translateY": 2834125,
            "unit": "EMU"
          }
        }
     ]
    }
  ]
}

使用欄位遮罩更新

有時您只需要更新物件中的特定欄位，其他欄位則維持不變。presentations.batchUpdate 方法中的更新要求會使用欄位遮罩，告知 API 要變更哪些欄位。更新要求會忽略欄位遮罩中未指定的任何欄位，並保留這些欄位的目前值。

您也可以在更新的訊息中不指定欄位，但將欄位新增至遮罩，藉此取消設定欄位。這會清除欄位先前的值。

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

下列範例使用 UpdateShapePropertiesRequest 方法，將形狀的填滿顏色變更為 DARK1 主題顏色，並取消設定形狀的外框：

POST https://slides.googleapis.com/v1/presentations/presentationId:batchUpdate
 
{
  "requests": [
    {
      "updateShapeProperties": {
        "objectId": OBJECT_ID,
        "shapeProperties": {
          "shapeBackgroundFill": {
            "solidFill": {
              "color": {
                "themeColor": "DARK1"
              }
            }
          }
        },
        "fields": "shapeBackgroundFill.solidFill.color,outline"
      }
    }
  ]
}