Mithilfe von Feldmasken können API-Caller die Felder auflisten, die eine Anfrage zurückgeben oder aktualisieren soll. Mit einer FieldMask kann die API unnötige Arbeit vermeiden und die Leistung verbessern. Eine Feldmaske wird sowohl für die Lese- als auch für die Aktualisierungsmethoden in der Google Präsentationen API verwendet.
Mit einer Feldmaske lesen
Präsentationen können groß sein und oft benötigen Sie 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 Antwort der Google Präsentationen API zurückgegeben wird. Für eine optimale Leistung sollten Sie in der Antwort nur die Felder angeben, die Sie benötigen.
Das Format des Parameters „fields“ entspricht der JSON-Codierung einer FieldMask. Kurz gesagt: Mehrere verschiedene Felder werden durch Kommas getrennt, Unterfelder durch Punkte. Feldnamen können in CamelCase oder durch_Unterstriche_getrennt angegeben werden. Aus Gründen der Übersichtlichkeit können mehrere Unterfelder desselben Typs in Klammern aufgeführt werden.
In der folgenden presentations.get-Anfrage wird mithilfe einer Feldmaske von slides.pageElements(objectId,size,transform) nur die Objekt-ID, Size, und die Transformation eines pageElement-Objekts auf allen Folien in einer Präsentation abgerufen:
GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)
Die Antwort auf diesen Methodenaufruf ist ein Presentation-Objekt mit den im Feldmasken angeforderten Komponenten:
{
"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, während die anderen Felder unverändert bleiben. Aktualisierungsanfragen innerhalb eines presentations.batchUpdate-Vorgangs verwenden Feldmasken, um der API mitzuteilen, 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 ein Feld auch zurücksetzen, indem Sie es nicht in der aktualisierten Nachricht angeben, sondern der Maske hinzufügen. Dadurch wird der vorherige Wert des Felds gelöscht.
Die Syntax für Aktualisierungsfeldmasken entspricht der von Leserstellungsfeldmasken.
Im folgenden Beispiel wird mit UpdateShapePropertiesRequest die Füllung einer Form in die DARK1-Designfarbe geändert und die Umrisslinie der Form entfernt:
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"
}
}
]
}