Feldmasken verwenden

Mit Feldmasken können API-Aufrufer die Felder auflisten, die eine Anfrage enthalten soll zurückgeben oder aktualisieren. Mit 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 umfangreich sein und oft benötigen Sie nicht Presentation Ressource, die von einer Leseanfrage zurückgegeben wird. Sie können einschränken, was in einem Slides API-Antwort mit dem URL-Parameter fields Für optimale Leistung, explizit nur die benötigten Felder auflisten .

Das Format des Parameters „fields“ entspricht dem des JSON-Codierung einer FieldMask Kurz gesagt: Mehrere verschiedene Felder sind durch Kommas getrennt und Unterfelder sind durch einen Punkt getrennt. Feldnamen können in camelCase oder separated_by_underscores: Der Einfachheit halber sind mehrere Unterfelder in Klammern angegeben werden.

Die folgenden presentations.get Anfragebeispiel eine Feldmaske von slides.pageElements(objectId,size,transform), um nur die Objekt-ID abzurufen. Size und Transformieren von pageElement Objekt auf allen Folien einer Präsentation einfügen:

GET https://slides.googleapis.com/v1/presentations/presentationId?fields=slides.pageElements(objectId,size,transform)

Die Antwort auf diesen Methodenaufruf ist ein Objekt Presentation mit den Komponenten, die in der Feldmaske angefordert wurden:

{
  "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 Sie die andere Felder unverändert lassen. Aktualisierungsanfragen innerhalb eines presentations.batchUpdate verwenden Feldmasken, um der API mitzuteilen, welche Felder geändert werden. Die Bei einer Aktualisierungsanforderung werden alle Felder ignoriert, die nicht in der Feldmaske angegeben sind. und belassen sie bei ihren aktuellen Werten.

Sie können die Festlegung eines Felds auch aufheben, indem Sie es nicht in der aktualisierten Nachricht angeben. durch Hinzufügen des Felds zur Maske. Dadurch wird der zuvor im Feld was wir hatten.

Die Syntax für Aktualisierung von Feldmasken entspricht der von gelesenen Feldmasken.

Im folgenden Beispiel wird die Methode UpdateShapePropertiesRequest um die Füllfarbe einer Form in die Designfarbe DARK1 zu ändern und die Gliederung:

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"
      }
    }
  ]
}