Mit Feldmasken können API-Aufrufer die Felder auflisten, die von einer Anfrage zurückgegeben oder aktualisiert werden sollen. Die Verwendung einer FieldMask ermöglicht der API, unnötige Arbeit zu vermeiden, und verbessert die Leistung. Eine Feldmaske wird sowohl für die Lese- als auch für die Aktualisierungsmethode in der Google Sheets API verwendet.
Mit einer Feldmaske lesen
Tabellen können sehr groß sein und Sie benötigen häufig 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. Für eine optimale Leistung sollten Sie in der Antwort explizit nur die benötigten Felder auflisten.
Das Format des „fields“-Parameters entspricht der JSON-Codierung einer FieldMask. Kurz gesagt: Mehrere verschiedene Felder sind durch Kommas und Unterfelder durch Punkte getrennt. Feldnamen können in camelCase oder separate_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 eines Objekts SheetProperties für alle Tabellenblätter 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. sheetType=OBJECT enthält nicht gridProperties:
{
"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 und die anderen Felder unverändert lassen. Bei Aktualisierungsanfragen innerhalb eines spreadsheets.batchUpdate-Vorgangs werden der API mithilfe von Feldmasken mitgeteilt, 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 die Festlegung eines Felds auch aufheben, indem Sie es nicht in der aktualisierten Nachricht angeben, sondern der Maske hinzufügen. Dadurch wird der zuvor festgelegte Wert des Felds gelöscht.
Die Syntax für Aktualisierung von Feldmasken entspricht der von gelesenen Feldmasken.
Im folgenden Beispiel wird AddSheetRequest verwendet, um ein neues Tabellenblatt vom Typ Grid hinzuzufügen, die erste Zeile zu fixieren und den Tab des neuen Tabellenblatts rot zu färben:
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
}
}
}
}
}
]
}