欄位遮罩是可讓 API 呼叫端列出要求傳回或更新的欄位的方式。使用 FieldMask 可讓 API 避免不必要的作業並改善效能。欄位遮罩適用於 Google 簡報 API 的讀取和更新方法。
使用欄位遮罩讀取
簡報檔案可能相當大，且通常不需要讀取要求傳回的所有 Presentation 資源部分。您可以使用 fields 網址參數，限制在 Slides 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"
}
}
]
}