Mit Feldmasken können API-Aufrufer die Felder auflisten, die in 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 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 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 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 UpdateTextStyleRequest verwendet, um die Wörter „Google Docs API“ im Dokument in den Zeilen 5 bis 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
},
}
}
],
}