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 Tabellen API verwendet.
Mit einer Feldmaske lesen
Tabellen können groß sein und oft benötigen Sie nicht jeden Teil der Spreadsheet-Ressource, die von einer Leseanfrage zurückgegeben wird. Mit dem URL-Parameter fields können Sie einschränken, was in einer Antwort der Google Tabellen API 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 spreadsheets.get-Anfrage wird mithilfe einer Feldmaske vom Typ sheets.properties(sheetId,title,sheetType,gridProperties) nur die Tabellen-ID, der Titel, SheetType und GridProperties eines SheetProperties-Objekts auf allen Tabellen in einer Tabelle abgerufen:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties(sheetId,title,sheetType,gridProperties)
Die Antwort auf diesen Methodenaufruf ist ein Spreadsheet-Objekt mit den in der Feldmaske angeforderten Komponenten. Beachten Sie, dass sheetType=OBJECT kein gridProperties enthält:
{
"sheets": [
{
"properties": {
"sheetId": SHEET_ID,
"title": "TITLE",
"sheetType": "GRID",
"gridProperties": {
"rowCount": 1000,
"columnCount": 25
}
}
},
{
"properties": {
"sheetId": SHEET_ID,
"title": "TITLE",
"sheetType": "OBJECT"
}
}
]
}
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 spreadsheets.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 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 mit AddSheetRequest ein neues Tabellenblatt vom Typ Grid hinzugefügt, die erste Zeile eingefroren und der Tab des neuen Tabellenblatts rot eingefärbt:
POST https://sheets.googleapis.com/v1/spreadsheets/spreadsheetId:batchUpdate
{
"spreadsheetId": "SPREADSHEET_ID",
"replies": [
{
"addSheet": {
"properties": {
"sheetId": SHEET_ID,
"title": "TITLE",
"index": 6,
"sheetType": "GRID",
"gridProperties": {
"rowCount": 1000,
"columnCount": 26,
"frozenRowCount": 1
},
"tabColor": {
"red": 0.003921569
},
"tabColorStyle": {
"rgbColor": {
"red": 0.003921569
}
}
}
}
}
]
}