Feldmasken verwenden

Mit Feldmasken können API-Aufrufer 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 sowohl für die Lese- als auch für die Aktualisierungsmethoden in der Google Präsentationen API verwendet.

Einen Vergleich der zurückgegebenen Werte im Antworttext, wenn Sie eine Feldmaske verwenden oder nicht, finden Sie unter Mit Teilressourcen arbeiten.

Mit einer Feldmaske lesen

Präsentationen können groß sein und oft benötigen Sie nicht alle Teile der presentations Ressource, die von einer Leseanfrage zurückgegeben werden. Sie können die zurückgegebenen Werte in einer Präsentationen API-Antwort mit dem URL-Parameter fields einschränken. Für eine optimale Leistung sollten Sie nur die Felder explizit auflisten, die Sie benötigen in der Antwort.

Das Format des Parameters „fields“ entspricht der JSON-Codierung einer Feldmaske. Kurz gesagt: Mehrere verschiedene Felder sind kommagetrennt und Unterfelder werden durch Punkte getrennt. Feldnamen können in camelCase oder mit_Unterstrichen_getrennt angegeben werden. Zur Vereinfachung können mehrere Unterfelder desselben Typs in Klammern aufgeführt werden.

Im folgenden presentations.get Beispiel für eine Methodenanfrage wird eine Feldmaske von slides.pageElements(objectId,size,transform)verwendet, um nur die Objekt-ID, Sizeund die Transformation eines pageElement -Objekts auf allen Folien in 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 werden Feldmasken verwendet, 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 aufheben, indem Sie es nicht in der aktualisierten Nachricht angeben, aber der Maske hinzufügen. Dadurch wird der vorherige Wert des Feldes gelöscht.

Die Syntax für Feldmasken für Aktualisierungen ist dieselbe wie für Feldmasken für Lesevorgänge.

Eine Feldmaske von * wird wie ein Platzhalter behandelt und ist eine Kurzform für die Angabe aller Felder in einer Nachricht. Die Platzhaltersyntax kann zu unerwünschten Ergebnissen führen, wenn die API in Zukunft aktualisiert wird, da schreibgeschützte Felder und neu hinzugefügte Felder Fehler verursachen können. Bei Produktionsanwendungen sollten Sie immer die spezifischen Felder auflisten, die in Feldmasken aktualisiert werden, und die Verwendung von *-Platzhaltern vermeiden.

Im folgenden Beispiel wird die UpdateShapePropertiesRequest Methode verwendet, um die Füllfarbe einer Form in die DARK1 Designfarbe zu ändern und die Kontur 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"
      }
    }
  ]
}