欄位遮罩是 API 呼叫端列出要求應傳回或更新欄位的方法。使用 FieldMask 可讓 API 避免不必要的工作並提升效能。Google 簡報 API 中的讀取和更新方法都會使用欄位遮罩。
使用欄位遮罩讀取
簡報可以很大,且通常不需要讀取要求傳回的 Presentation
資源中的所有部分。您可以使用 fields
網址參數,限制簡報 API 回應傳回的內容。為獲得最佳效能,請在回覆中明確列出您需要的欄位。
欄位參數的格式與 FieldMask 的 JSON 編碼相同。簡單來說,多個不同欄位都以半形逗號分隔,子欄位則以半形句號分隔。欄位名稱可使用 camelCase 或 split_by_underscores 指定。為了方便起見,您可以在括號內列出相同類型的多個子欄位。
以下 presentations.get
要求範例使用 slides.pageElements(objectId,size,transform)
的欄位遮罩,在簡報的所有投影片中,只擷取 pageElement
物件的物件 ID、Size
和轉換:
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"
}
}
]
}