Feldmasken verwenden

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 Docs API verwendet.

Mit einer Feldmaske lesen

Dokumente können groß sein und oft benötigen Sie nicht jeden Teil der Document-Ressource, die von einer Leseanfrage zurückgegeben wird. Mit dem URL-Parameter fields können Sie einschränken, was in einer Docs API-Antwort 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.

Im folgenden Beispiel für eine documents.get-Anfrage wird eine Feldmaske von title,tabs(documentTab(body.content(paragraph))),revisionId verwendet, um die title des Dokuments, die Paragraph eines Body-Objekts (aus allen Tabs) und die revisionId des Dokuments innerhalb eines Dokuments abzurufen:

GET https://docs.googleapis.com/v1/documents/documentId?fields=title,tabs(documentTab(body.content(paragraph))),revisionId

Die Antwort auf diesen Methodenaufruf ist ein Document-Objekt mit den in der Feldmaske angeforderten Komponenten:

{
  "title": "TITLE",
  "revisionId": "REVISION_ID",
  "tabs": [
    {
      "documentTab": {
        "body": {
          "content": [
            {},
            {
              "paragraph": {
                "elements": [
                  {
                    "startIndex": 1,
                    "endIndex": 59,
                    "textRun": {
                      "content": "CONTENT",
                      "textStyle": {}
                    }
                  }
                ],
                "paragraphStyle": {
                  "namedStyleType": "NORMAL_TEXT",
                  "direction": "LEFT_TO_RIGHT"
                }
              }
            }
          ]
        }
      }
    }
  ]
}

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 documents.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 es 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 die UpdateTextStyleRequest verwendet, um die Wörter „Google Docs API“ im Dokument in den Zeilen 5–20 fett zu formatieren:range

POST https://docs.googleapis.com/v1/documents/documentId:batchUpdate
 
{
  "title": "TITLE",
  "revisionId": "REVISION_ID",
  "suggestionsViewMode": "SUGGESTIONS_INLINE",
  "documentId": "DOCUMENT_ID",
  "tabs": [
    {
      "documentTab": {
        "body": {
          "content": [
            {
              "endIndex": 1,
              "sectionBreak": {
                "sectionStyle": {
                  "columnSeparatorStyle": "NONE",
                  "contentDirection": "LEFT_TO_RIGHT",
                  "sectionType": "CONTINUOUS"
                }
              }
            },
            {
              "startIndex": 1,
              "endIndex": 59,
              "paragraph": {
                "elements": [
                  {
                    "startIndex": 1,
                    "endIndex": 5,
                    "textRun": {
                      "content": "CONTENT",
                      "textStyle": {}
                    }
                  },
                  {
                    "startIndex": 5,
                    "endIndex": 20,
                    "textRun": {
                      "content": "CONTENT",
                      "textStyle": {
                        "bold": true
                      }
                    }
                  },
                  {
                    "startIndex": 20,
                    "endIndex": 59,
                    "textRun": {
                      "content": "CONTENT",
                      "textStyle": {}
                    }
                  }
                ],
                "paragraphStyle": {
                  "namedStyleType": "NORMAL_TEXT",
                  "direction": "LEFT_TO_RIGHT"
                }
              }
            }
          ]
        },
        {
          ... // style details
        },
      }
    }
  ],
}