Mit Feldmasken können API-Aufrufer die Felder auflisten, die von einer Anfrage zurückgegeben oder aktualisiert werden sollen. Die Verwendung einer FieldMask ermöglicht der API, unnötige Arbeit zu vermeiden, und verbessert die Leistung. Eine Feldmaske wird sowohl für die Lese- als auch für die Aktualisierungsmethode in der Google Slides API verwendet.
Mit einer Feldmaske lesen
Präsentationen können groß sein und Sie benötigen häufig nicht jeden Teil der Presentation-Ressource, die von einer Leseanfrage zurückgegeben wird. Mit dem URL-Parameter fields können Sie einschränken, was in einer Google Präsentationen API-Antwort zurückgegeben wird. Für eine optimale Leistung sollten Sie in der Antwort explizit nur die benötigten Felder auflisten.
Das Format des „fields“-Parameters entspricht der JSON-Codierung einer FieldMask. Kurz gesagt: Mehrere verschiedene Felder sind durch Kommas und Unterfelder durch Punkte getrennt. Feldnamen können in camelCase oder separate_by_underscores angegeben werden. Der Einfachheit halber können mehrere Unterfelder desselben Typs in Klammern aufgeführt werden.
Im folgenden Beispiel für eine presentations.get-Anfrage wird die Feldmaske slides.pageElements(objectId,size,transform) verwendet, um nur die Objekt-ID Size und die Transformation eines pageElement-Objekts auf allen Folien einer Präsentation abzurufen:
GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)
Die Antwort auf diesen Methodenaufruf ist ein Presentation-Objekt, das die in der Feldmaske angeforderten Komponenten enthält:
{
"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"
}
}
]
}
]
}
Mit einer Feldmaske aktualisieren
Manchmal müssen Sie nur bestimmte Felder in einem Objekt aktualisieren und die anderen Felder unverändert lassen. Bei Aktualisierungsanfragen innerhalb eines presentations.batchUpdate-Vorgangs werden der API mithilfe von Feldmasken mitgeteilt, welche Felder geändert werden. Die Aktualisierungsanfrage ignoriert alle Felder, die nicht in der Feldmaske angegeben sind, und behält ihre aktuellen Werte bei.
Sie können die Festlegung eines Felds auch aufheben, indem Sie es nicht in der aktualisierten Nachricht angeben, sondern der Maske hinzufügen. Dadurch wird der zuvor festgelegte Wert des Felds gelöscht.
Die Syntax für Aktualisierung von Feldmasken entspricht der von gelesenen Feldmasken.
Im folgenden Beispiel wird UpdateShapePropertiesRequest verwendet, um die Farbfüllung einer Form in die Designfarbe DARK1 zu ändern und den Umriss der Form aufzuheben:
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"
}
}
]
}