Feldmasken verwenden

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

Tabellenkalkulationen können groß sein und häufig 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
            }
          }
        }
      }
    }
  ]
}