Mit Feldmasken können API-Aufrufer die Felder auflisten, die eine Anfrage enthalten soll zurückgeben oder aktualisieren. Mit einem 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
Tabellenkalkulationen können groß sein und oft benötigen Sie nicht jeden Teil des
Spreadsheet
Ressource, die von einer Leseanfrage zurückgegeben wird. Sie können einschränken, was in einem
Sheets API-Antwort mit dem URL-Parameter fields Für optimale
Leistung,
explizit nur die benötigten Felder auflisten
.
Das Format des Parameters „fields“ entspricht dem des JSON-Codierung einer FieldMask Kurz gesagt: Mehrere verschiedene Felder sind durch Kommas getrennt und Unterfelder sind durch einen Punkt getrennt. Feldnamen können in camelCase oder separated_by_underscores: Der Einfachheit halber sind mehrere Unterfelder in Klammern angegeben werden.
Die folgenden
spreadsheets.get-Anfrage
Beispiel mit einer Feldmaske von sheets.properties(sheetId,title,sheetType,gridProperties), um
nur die Tabellen-ID, den Titel
SheetType und
GridProperties
von einem
SheetProperties.
-Objekt in allen Tabellenblättern einer Tabelle hinzufügen:
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. Beachten Sie, dass
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, während Sie die
andere Felder unverändert lassen. Aktualisierungsanfragen innerhalb eines
spreadsheets.batchUpdate
verwenden Feldmasken, um der API mitzuteilen, welche Felder geändert werden. Die
Bei einer Aktualisierungsanforderung werden alle Felder ignoriert, die nicht in der Feldmaske angegeben sind.
und belassen sie bei ihren aktuellen Werten.
Sie können die Festlegung eines Felds auch aufheben, indem Sie es nicht in der aktualisierten Nachricht angeben. durch Hinzufügen des Felds zur Maske. Dadurch wird der zuvor im Feld was wir hatten.
Die Syntax für Aktualisierung von Feldmasken entspricht der von gelesenen Feldmasken.
Im folgenden Beispiel wird die Methode
AddSheetRequest
um ein neues Tabellenblatt des Typs Grid hinzuzufügen, fixieren Sie die erste Zeile und färben Sie das neue
roter Tab des Tabellenblatts:
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
}
}
}
}
}
]
}