Field masks are a way for API callers to list the fields that a request should return or update. Using fields masks allows the API to avoid unnecessary work and improves performance. Field masks are used for both read and update methods in the Slides API.
Reading with a field mask
Presentations are big, and often you don't need every part of the presentation
returned by a read request. You can limit what's returned in a Slides API
response, using the fields
URL parameter. For best performance,
explicitly list only the fields you need
in the reply.
The format of the fields parameter is the same as the JSON encoding of a FieldMask. Stated briefly, multiple different fields are comma separated and subfields are dot-separated. Field names can be specified in camelCase or separated_by_underscores. For convenience, multiple subfields from the same type can be listed within parentheses.
The following presentations.get
request example uses a field mask of
slides.pageElements(objectId,size,transform)
to fetch only the object IDs,
sizes,
and transforms
of all of the pageElements
on slides in a presentation:
GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)
The response to this method call is a
Presentation
object containing the components requested in the field mask:
{ "slides": [ { "pageElements": [ { "objectId": "i0", "size": { "width": { "magnitude": 3000000, "unit": "EMU" }, "height": { "magnitude": 3000000, "unit": "EMU" } }, "transform": { "scaleX": 1, "scaleY": 1 "translateX": 311708, "translateY": 744575, "unit": "EMU" } }, { "objectId": "i1", "size": { "width": { "magnitude": 3000000, "unit": "EMU" }, "height": { "magnitude": 3000000, "unit": "EMU" } }, "transform": { "scaleX": 1, "scaleY": 1 "translateX": 311700, "translateY": 2834125, "unit": "EMU" } } ] } ] }
Updating with a field mask
Sometimes you need to update only certain fields in an object while leaving the other fields unchanged. Update requests inside a presentations.batchUpdate operation use field masks to tell the API which fields are being changed. The update request ignores any fields that aren't specified in the field mask, leaving them with their current values.
You can also unset a field by not specifying it in the updated message, but adding the field to the mask. This clears whatever value that field previously had.
The syntax for update field masks is the same as read field masks. Additionally,
a field mask of *
is treated like a wildcard and is shorthand for specifying
all of the fields in a message.
The following example uses an updateShapeProperties
request to change a shape's color fill to the DARK1
theme color and unset
the shape's outline:
POST https://slides.googleapis.com/v1/presentations/presentationId:batchUpdate
{ "requests": [ { "updateShapeProperties": { "objectId": elementId, "shapeProperties": { "shapeBackgroundFill": { "solidFill": { "color": { "themeColor": "DARK1" } } } }, "fields": "shapeBackgroundFill.solidFill.color,outline" } } ] }