Mit Feldmasken können API-Aufrufer die Felder auflisten, die von einer Anfrage zurückgegeben oder aktualisiert werden sollen. Durch die Verwendung einer FieldMask kann die API unnötige Arbeit vermeiden und die Leistung verbessern. Eine Feldmaske wird für die Methoden zum Lesen und Aktualisieren in der Google Slides API verwendet.
Mit einer Feldmaske lesen
Präsentationen können sehr groß sein und häufig 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 Google Präsentationen API-Antwort zurückgegeben wird. Die beste Leistung erzielen Sie, wenn Sie in der Antwort explizit nur die Felder auflisten, die Sie benötigen.
Das Format des Parameters „fields“ entspricht der JSON-Codierung einer FieldMask. Kurz gesagt: Mehrere verschiedene Felder sind durch Kommas getrennt und Unterfelder sind durch Punkte getrennt. Feldnamen können in camelCase oder separated_by_underscores angegeben werden. Der Einfachheit halber können mehrere Unterfelder desselben Typs in Klammern aufgeführt werden.
Im folgenden Anfragebeispiel für presentations.get wird die Feldmaske slides.pageElements(objectId,size,transform) verwendet, um nur die Objekt-ID Size und das transform 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 nur bestimmte Felder in einem Objekt aktualisiert werden, 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 behalten die aktuellen Werte bei.
Sie können die Festlegung eines Felds auch aufheben, indem Sie es nicht in der aktualisierten Nachricht angeben, sondern das Feld der Maske hinzufügen. Dadurch wird der Wert gelöscht, den das Feld zuvor hatte.
Die Syntax für Update-Feldmasken entspricht der für Lesefeldmasken.
Im folgenden Beispiel wird mit UpdateShapePropertiesRequest die Farbfüllung einer Form in die Designfarbe DARK1 geändert und der Umriss der Form wird aufgehoben:
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"
}
}
]
}