使用欄位遮罩

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

使用欄位遮罩讀取

簡報檔案可能很龐大，而且往往不需要所有功能 Presentation敬上 讀取要求傳回的資源。您可以在 Slides API 回應：使用 fields 網址參數。最佳 成效 明確列出您需要的欄位 回覆。

欄位參數的格式與 FieldMask 的 JSON 編碼。 簡單來說，多個不同欄位以半形逗號分隔，而子欄位為 以點分隔欄位名稱可用 camelCase 或 separated_by_underscores。為了方便起見，請從同一個區域中使用多個子欄位 類型可列在括弧中。

下列 presentations.get 要求範例使用 只擷取物件 ID 的 slides.pageElements(objectId,size,transform)， Size和 轉換 的 pageElement 物件：

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

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

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