API 调用方可以通过字段掩码来列出请求应返回或更新的字段。使用 FieldMask 可让该 API 避免不必要的工作并提高性能。Google 幻灯片 API 中的 read 和 update 方法都使用字段掩码。
使用字段掩码进行读取
演示文稿可能很大,通常您不需要读取请求返回的 Presentation
资源的每个部分。您可以使用 fields
网址参数限制 Google 幻灯片 API 响应中返回的内容。为获得最佳性能,请在回复中仅明确列出您需要的字段。
fields 参数的格式与 FieldMask 的 JSON 编码相同。简单来说,多个不同字段用英文逗号分隔,子字段用句点分隔。字段名称可以采用 camelCase 或 Separate_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"
}
}
]
}