Feldmasken verwenden

Mit Feldmasken können API-Aufrufer die Felder auflisten, die eine Anfrage zurückgeben oder aktualisieren soll. 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 Sheets API verwendet.

Mit einer Feldmaske lesen

Tabellen können groß sein und oft benötigen Sie nicht alle Teile der Spreadsheet Ressource, die von einer Leseanfrage zurückgegeben werden. Sie können die zurückgegebenen Daten in einer Sheets API-Antwort mit dem URL-Parameter fields einschränken. Für eine optimale Leistung sollten Sie nur die Felder explizit auflisten, die Sie benötigen in der Antwort.

Das Format des Parameters „fields“ entspricht der JSON-Codierung einer Feldmaske. Kurz gesagt: Mehrere verschiedene Felder werden kommagetrennt und Unterfelder durch Punkte. Feldnamen können in camelCase oder mit_Unterstrichen_getrennt angegeben werden. Zur Vereinfachung können mehrere Unterfelder desselben Typs in Klammern aufgeführt werden.

Im folgenden spreadsheets.get Anfragebeispiel wird eine Feldmaske von sheets.properties(sheetId,title,sheetType,gridProperties)verwendet, um nur die Tabellenblatt-ID, den Titel, SheetType, und GridProperties eines SheetProperties Objekts für alle Tabellenblätter in 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 keine 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 die anderen Felder unverändert bleiben. Bei Aktualisierungsanfragen in einem spreadsheets.batchUpdate -Vorgang werden Feldmasken verwendet, 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 aufheben, indem Sie es nicht in der aktualisierten Nachricht angeben, aber der Maske hinzufügen. Dadurch wird der vorherige Wert des Felds gelöscht.

Die Syntax für Feldmasken für Aktualisierungen ist dieselbe wie für Feldmasken für Lesevorgänge.

Im folgenden Beispiel wird das AddSheetRequest verwendet, um ein neues Tabellenblatt vom Typ Gridhinzuzufügen, die erste Zeile einzufrieren 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
            }
          }
        }
      }
    }
  ]
}