Mit Feldmasken können API-Aufrufer die Felder auflisten, die von 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 für die Methoden zum Lesen und Aktualisieren in der Google Sheets API verwendet.
Mit einer Feldmaske lesen
Tabellen können sehr groß sein und häufig 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 Sheets API-Antwort zurückgegeben wird. Die beste Leistung erzielen Sie, wenn Sie in der Antwort explizit nur die Felder auflisten, die Sie benötigen.
Das Format des Parameters „fields“ entspricht der JSON-Codierung einer FieldMask. Kurz gesagt: Mehrere verschiedene Felder sind durch Kommas getrennt und Unterfelder sind durch Punkte getrennt. Feldnamen können in camelCase oder separated_by_underscores angegeben werden. Der Einfachheit halber können mehrere Unterfelder desselben Typs in Klammern aufgeführt werden.
Im folgenden Beispiel für eine spreadsheets.get-Anfrage wird die Feldmaske sheets.properties(sheetId,title,sheetType,gridProperties) verwendet, um nur die Tabellen-ID, den Titel, SheetType und GridProperties des Objekts SheetProperties auf allen Tabellenblättern einer Tabelle abzurufen:
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties(sheetId,title,sheetType,gridProperties)
Die Antwort auf diesen Methodenaufruf ist ein Spreadsheet-Objekt, das die in der Feldmaske angeforderten Komponenten enthält. gridProperties ist in sheetType=OBJECT nicht enthalten:
{
"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 nur bestimmte Felder in einem Objekt aktualisiert werden, 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 behalten die aktuellen Werte bei.
Sie können die Festlegung eines Felds auch aufheben, indem Sie es nicht in der aktualisierten Nachricht angeben, sondern das Feld der Maske hinzufügen. Dadurch wird der Wert gelöscht, den das Feld zuvor hatte.
Die Syntax für Update-Feldmasken entspricht der für Lesefeldmasken.
Im folgenden Beispiel wird mit AddSheetRequest ein neues Tabellenblatt vom Typ Grid hinzugefügt, die erste Zeile fixiert 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
}
}
}
}
}
]
}