Mit Feldmasken können API-Aufrufer die 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 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 nur die Felder explizit auflisten, die Sie in der Antwort benötigen.
Das Format des Parameters „fields“ entspricht der JSON-Codierung einer FieldMask. Kurz gesagt: Mehrere verschiedene Felder sind kommagetrennt und Unterfelder werden durch Punkte getrennt. 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 documents.get-Anfrage wird die Feldmaske title,tabs(documentTab(body.content(paragraph))),revisionId verwendet, um die title des Dokuments, die Paragraph eines Body-Objekts (von allen Tabs) und die revisionId des Dokuments in einem Dokument 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, das die in der Feldmaske angeforderten Komponenten enthält:
{
"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. Bei Aktualisierungsanfragen innerhalb eines documents.batchUpdate-Vorgangs 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 das
UpdateTextStyleRequest
verwendet, um die Wörter „Google Docs API“ im Dokument in den Zeilen range5–20 fett zu formatieren:
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
},
}
}
],
}