欄位遮罩可讓 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"
}
}
]
}