Mit Feldmasken können API-Aufrufer Felder auflisten, die in einer Anfrage zurückgegeben oder aktualisiert werden sollen. Wenn Sie eine FieldMask verwenden, 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 Slides API verwendet.
Einen Vergleich der zurückgegebenen Elemente in einem Antworttext, wenn Sie keine Feldmaske verwenden, und wenn Sie eine Feldmaske verwenden, finden Sie unter Mit Teilressourcen arbeiten.
Mit einer Feldmaske lesen
Präsentationen können sehr groß sein. Oft benötigen Sie nicht alle Teile der presentations-Ressource, die von einer Leseanfrage zurückgegeben werden. Mit dem URL-Parameter fields können Sie einschränken, was in einer Slides API-Antwort zurückgegeben wird. Für eine optimale Leistung sollten Sie in der Antwort nur die Felder explizit auflisten, die Sie benötigen.
Das Format des Parameters „fields“ entspricht dem JSON-Format einer FieldMask. Kurz gesagt: Mehrere verschiedene Felder werden durch Kommas getrennt und Unterfelder durch Punkte. Feldnamen können in camelCase oder separated_by_underscores angegeben werden. Aus Gründen der Übersichtlichkeit können mehrere Unterfelder desselben Typs in Klammern aufgeführt werden.
Im folgenden Beispiel für eine presentations.get-Methodenanfrage 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 presentations-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, während die anderen Felder unverändert bleiben. Bei Aktualisierungsanfragen in einer presentations.batchUpdate-Methode wird mithilfe von Feldmasken angegeben, 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 deaktivieren, indem Sie es in der aktualisierten Nachricht nicht angeben, aber der Maske hinzufügen. Dadurch wird der vorherige Wert des Felds gelöscht.
Die Syntax für Aktualisierungsfeldmasken ist dieselbe wie für Lesefeldmasken.
Im folgenden Beispiel wird mit der Methode UpdateShapePropertiesRequest die Füllfarbe einer Form in die DARK1-Designfarbe geändert und die Kontur 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" } } ] }