Tischservice

Mit dem Tables-Dienst können Scripts Zeilen in Google Tabellen programmatisch lesen und bearbeiten.

Hinweis :Dies ist ein erweiterter Dienst, der vor der Verwendung aktiviert werden muss.

Referenz

Weitere Informationen zu diesem Dienst finden Sie in der Dokumentation für die Tables API. Wie alle erweiterten Dienste in Apps Script verwendet der Tables-Dienst dieselben Objekte, Methoden und Parameter wie die öffentliche API. Weitere Informationen finden Sie unter So werden Methodensignaturen ermittelt.

Informationen zum Melden von Problemen und zum Support finden Sie im Supportleitfaden für Tables.

Beispielcode

Liste der Tabellen abrufen

Im folgenden Beispiel wird gezeigt, wie Sie eine Liste aller Tabellen abrufen, deren Inhaber der Nutzer ist.

// Get list of tables the user owns
var response = Area120Tables.Tables.list();
if (response) {
  var tables = response.tables;
  Logger.log(JSON.stringify(tables[0]));
}

Unten sehen Sie ein Beispiel für die Antwort, die Informationen zur Tabelle und den Tabellenspaltendefinitionen enthält:

{
  “tables”: [
    {
      "name": "tables/b6prMlkWyekbsCFeX6IOdu",
      "displayName": "Applicants"
      "columns": [
        {"id": "9qVCMvgh", "name": "Name", "dataType": "text"},
        {"id": "aD8dDXAS", "name": "Email", "dataType": "text"},
        {"id": "9pc0kdNX", "name": "Experience", "dataType": "tags_list",
          "labels": [
            {"id": "aAqi235Q", "name": "Android"},
            {"id": "bULZ4OK3", "name": "iOS"},
          ],
        },
        {"id": "8abYfCyo", "name": "Home Address", "dataType": "location"},
        {"id": "8ccERJ2v", "name": "Doc", "dataType": "file_attachment_list"},
        {"id": "aFb-tXf1", "name": "Stage", "dataType": "dropdown",
          "labels": [
            {"id": "8Hcb-Pxe", "name": "Applied"},
            {"id": "aM3EDGFf", "name": "Phone Screen"},
            {"id": "abyFLVKU", "name": "Onsite Interview"},
          ],
        },
        {"id": "9yKUThTi", "name": "Recruiter", "dataType": "person_list"},
        {"id": "a5c9WPVA", "name": "Interview Date", "dataType": "date"},
        {"id": "bqtbYPtH", "name": "Created", "dataType": "create_timestamp"},
        {"id": "bWR08pBv", "name": "Updated", "dataType": "update_timestamp"}
      ]
    },
    ... // more tables
  ]
}

Die Antwort enthält standardmäßig bis zu 20 Tabellen. Wenn Sie weitere Tabellen abrufen möchten, können Sie die Antworten mit den Parametern page_token und page_size wie unten dargestellt paginalisieren:

// Paginate through a list of tables
var pageSize = 1000;
var pageToken;
var response = Area120Tables.Tables.list({page_size: pageSize});
while (response) {
  var tables = response.tables;

  // get next page of tables
  pageToken = response.nextPageToken;
  if (!pageToken) {
    response = undefined;
  } else {
    response = Area120Tables.Tables.list(tableRequest, {page_size: pageSize, page_token: pageToken});
  }
}

Der Maximalwert des Parameters page_size für Listentabellen ist 100.

Informationen und Spaltendefinitionen einer Tabelle abrufen

Im folgenden Beispiel wird gezeigt, wie Sie die Informationen und die Spaltendefinition einer bestimmten Tabelle abrufen.

var tableID = "TABLE_ID";  // ID for the table
var tableName = "tables/" + tableID;
var response = Area120Tables.Tables.get(tableName);
Logger.log(JSON.stringify(response));

Tabellen-ID ermitteln

Wenn Sie die ID einer Tabelle ermitteln möchten, öffnen Sie die Tabelle in der Tables-Web-App. Die Tabellen-ID finden Sie oben in der URL direkt nach /table/.

Im folgenden Beispiel wird gezeigt, wo Sie die Tabellen-ID in verschiedenen Tabellen-URLs finden:

https://tables.area120.google.com/u/0/workspace/abcdefghijklmnop/table/TABLE_ID
https://tables.area120.google.com/u/0/table/TABLE_ID
https://tables.area120.google.com/u/0/table/TABLE_ID/view/abcedfghijk

Zeilen einer Tabelle lesen

Im folgenden Beispiel wird gezeigt, wie Sie eine Liste der Zeilen einer Tabelle abrufen und die Feldwerte lesen.

var tableID = "TABLE_ID";  // ID for the table
var pageToken;
var pageSize = 1000;
var tableName = "tables/" + tableID;
var response = Area120Tables.Tables.Rows.list(tableName)
if (response) {
  for (var i = 0, rows = response.rows; i < rows.length; i++) {
    if (!rows[i].values) { // If blank row, keep going
      Logger.log("Empty row");
      continue;
    }
    Logger.log(rows[i].values);
    Logger.log(rows[i].values["Description"]);
  }
}

Eine Beispielantwort finden Sie unten. Die Antwort enthält eine Liste der Zeilen in der Tabelle und die Werte für jedes Feld.

{
  “rows”: [
    {
      "name": "tables/TABLE_ID/rows/a6tvEPska7l8rAlHlSdOLb",
      "values": {
        "Thing to do": "First item",  // Text
        "Size": 100,                  // Number
        "ETA":{"month":12,"day":3,"year":2021}  // Date
        "Stage": "Completed",         // Dropdown
        "Checklist": [                // Checklist
          "Do this",
          "then this"
        ],
        "Labels": [                   // Tags
          "Green",
          "Purple"
        ],
        "Address": {                  // Location
          "latitude": 40.740726470947266,
          "longitude": -74.00206756591797,
          "address": "3014 Watson Lane, Sattler, TX 78130, USA"
        },
        "Archive?": true,             // Checkbox
        "ID#": 1,                     // Auto ID
        "Row creator": "[e-mail]",  // Creator / Updater / Person
        "Last updated": "October 7, 2020 6:30:38 PM EDT",
        "Created on": "March 2, 2020 1:07:54 PM EST",
      }
    },
    ... // More rows
  ],
}

Die Antwort enthält standardmäßig bis zu 50 Zeilen. Wenn Sie weitere Zeilen abrufen möchten, können Sie die Antworten mit den Parametern page_token und page_size wie unten dargestellt paginarisieren:

var pageToken;
var pageSize = 1000;
var response = Area120Tables.Tables.Rows.list(tableName, {page_size: pageSize});
while (response) {
  var rows = response.rows;

  // read next page of rows
  pageToken = response.nextPageToken;
  if (!pageToken) {
    response = undefined;
  } else {
    response = Area120Tables.Tables.Rows.list(tableName, {page_size: pageSize, page_token: pageToken});
  }
}

Wenn weitere Seiten verfügbar sind, enthält die Antwort ein nextPageToken. Andernfalls ist die Antwort nicht definiert. Wenn Sie die nächste Ergebnisseite abrufen möchten, geben Sie das nextPageToken für den nächsten Listenaufruf ein.

Der Maximalwert des Parameters page_size ist 1.000.

Eine Zeile aus einer Tabelle abrufen

Im folgenden Beispiel wird gezeigt, wie die Feldwerte einer Zeile aus einer Tabelle gelesen werden.

var tableID = "TABLE_ID";  // ID for the table
var tableName = "tables/" + tableID;
var rowID = "ROW_ID";  // ID for the row to fetch
var rowName = tableName + "/rows/" + rowID;    // Construct row name
var response = Area120Tables.Tables.Rows.get(rowName)
if (response) {
  Logger.log(response.values);
}

Zeilenliste filtern

Verwenden Sie den Parameter filter, um die Zeilenliste zu filtern und nur die Ergebnisse zu erhalten, die Sie interessieren. Weitere Informationen zur Syntax und zu den Spaltentypen, die vom Filter unterstützt werden, finden Sie in der Dokumentation zur Filtering API.

var tableID = "TABLE_ID";  // ID for the table
var pageToken;
var pageSize = 1000;
var tableName = "tables/" + tableID;
var response = Area120Tables.Tables.Rows.list(tableName, {filter:"values.\"Point of Contact\"=\"[e-mail]\""})
if (response) {
  for (var i = 0, rows = response.rows; i < rows.length; i++) {
    if (!rows[i].values) { // If blank row, keep going
      Logger.log("Empty row");
      continue;
    }
    Logger.log(rows[i].values);
    Logger.log(rows[i].values["Description"]);
  }
}

Die Antwort enthält die Zeilen, in denen die Spalte „Ansprechpartner“ auf „[e-mail]“ festgelegt ist.

{
  “rows”: [
    {
      "name": "tables/TABLE_ID/rows/a6tvEPska7l8rAlHlSdOLb",
      "values": {
        "Thing to do": "Second item",  // Text
        "Size": 110,                  // Number
        "ETA":{"month":12,"day":3,"year":2021}  // Date

        "Stage": "Completed",         // Dropdown
        "Checklist": [                // Checklist
          "Do this",
          "then this",
          "finally this"
        ],
        "Labels": [                   // Tags
          "Green",
          "Orange"
        ],
        "Address": {                  // Location
          "latitude": 45.740726470947266,
          "longitude": -88.00206756591797,
          "address": "6027 Holmes Lane, Sattler, TX 78130, USA"
        },
        "Archive?": false,             // Checkbox
        "ID#": 2,                     // Auto ID
        "Point of Contact": "[e-mail]",  // Person
        "Last updated": "October 9, 2020 6:35:38 PM EDT",
        "Created on": "March 10, 2020 1:07:54 PM EST",
      }
    },
    ... // More rows
  ],
}

Zeile in einer Tabelle erstellen

Im folgenden Beispiel wird gezeigt, wie einer Tabelle eine Zeile hinzugefügt wird.

var tableID = "TABLE_ID";  // ID for the table
var tableName = "tables/" + tableID;
var values = {
    "Number Column": 100,
    "Text Column 2": "hello world",
    "Date Column 3": new Date(),
    "Dropdown Col.": "Dropdown value",
};
Area120Tables.Tables.Rows.create({values: values}, tableName);

Wenn Sie die Werte für die neue Zeile angeben, müssen die Schlüssel der Objekt-Schlüssel/Wert-Paare genau mit den Titeln der Tabellenspalten übereinstimmen (bei Groß- und Kleinschreibung beachten), es sei denn, der Typ der beschreibbaren Spalte ist eine Suchspalte oder Zusammenfassungsspalte. Sie legen Werte für die Spalten Suche und Zusammenfassung mit dem Wert für die Beziehung fest. Sie müssen den Wert für die Beziehung mit dem Beziehungsnamen aktualisieren, der im Dialogfeld Beziehungen angezeigt wird.

Hinweis: Achten Sie beim Erstellen von Spaltentiteln darauf, dass sie keine Endzeichen enthalten, um Verwechslungen zu vermeiden.

Die zulässigen Werte für eine Spalte hängen vom Datentyp der Spalte ab:

Spaltentyp	Datentyp (Lesen)	Zulässige Eingabetypen (Schreiben)
Standarddaten
Text	String	String
Number	Number	Number
Datum	Date Object { "year": Number, "month": Number, "day": Number }	Date, String (in den meisten Datumsformaten)
Rich-Daten
Person	String (E-Mail-Adresse)	String (muss mit dem Google-Nutzer übereinstimmen)
Dateianhänge	Object[] { "id": String, "name": String, "mimeType": String, "url": String }	Dieses Feld kann nicht über die API geändert werden.
Standort	Object { "latitude": Number, "longitude": Number, "address": String }	Object { "latitude": Number (required), "longitude": Number (required), "address": String }
Rich Entry
Drop-down-Liste	String	String (muss mit den Drop-down-Optionen übereinstimmen)
Tags	String[] (Array mit Tag-Optionen)	String[] (muss mit den Tag-Optionen übereinstimmen)
Kästchen	Boolean	Boolean
Checkliste	String[] (Array von Listenelementen)	String[] (muss mit den Listenelementen übereinstimmen)
Verknüpfte Daten
Beziehung	String	String: "tables/[LINKED_TABLE_ID]/rows/[LINKED_ROW_ID]"
Suchen	Hängt vom Typ der Quellspalte ab.	Dieses Feld kann nicht geändert werden und wird mit dem verknüpften Wert aktualisiert.
Zusammenfassung	Abhängig vom Typ der Quellspalte und der Zusammenfassungsfunktion: Anzahl: Number Maximum in einer Spalte vom Typ „Datum“: String Listenwerte: Array	Dieses Feld kann nicht geändert werden.
Berechnetes Feld
Auto-ID	Number	Dieses Feld kann nicht geändert werden.
Metadaten
Ersteller/Urheber	String	Dieses Feld kann nicht geändert werden.
Erstellungszeit	Object { “seconds”: Number, “nanos”: Number }	Dieses Feld kann nicht geändert werden.
Updater	String	Dieses Feld kann nicht geändert werden.
Aktualisierungszeit	Object { “seconds”: Number, “nanos”: Number }	Dieses Feld kann nicht geändert werden.

Der Tables-Dienst versucht, die angegebenen Werte so zu konvertieren, dass sie dem Spaltentyp entsprechen. Wenn die Daten nicht übereinstimmen, wird der Wert nicht festgelegt und für neue Zeilen leer gelassen.

Einer Tabelle mehrere Zeilen hinzufügen

Im folgenden Beispiel wird gezeigt, wie Sie einer Tabelle mehrere Zeilen gleichzeitig hinzufügen.

var tableID = “TABLE_ID”;
var tableName = "tables/" + tableID;
Area120Tables.Tables.Rows.batchCreate({requests: [
  {row:{values:{"Col 1":"Sample",  "Col 2":"One",   "Col 3":"A"}}},
  {row:{values:{"Col 1":"Example", "Col 2":"Two",   "Col 3":"B"}}},
  {row:{values:{"Col 1":"Test",    "Col 2":"Three", "Col 3":"C"}}},
]}, tableName)

Hinweis: Batch-Vorgänge können bis zu 500 Zeilen umfassen.

Zeilen in einer Tabelle aktualisieren

Im folgenden Beispiel wird gezeigt, wie die Werte einer vorhandenen Zeile in einer Tabelle aktualisiert werden:

var rowName = "tables/TABLE_ID/rows/ROW_ID";
var values = {"Column": "HELLO"};
var response = Area120Tables.Tables.Rows.patch({values: values}, rowName);
Logger.log("Update row:" + JSON.stringify(response));

Die Antwort gibt die aktualisierte Zeile zurück.

Zeilen-ID ermitteln

Sie haben zwei Möglichkeiten, die ID für eine Zeile zu finden:

Zeilen-ID mit der API abrufen

Wenn Sie Zeilen aus einer Tabelle lesen, können Sie für jede Zeile das Attribut name verwenden, das die Tabellen- und Zeilen-IDs enthält.

Zeilen-ID über die Tabellen-Benutzeroberfläche abrufen

1. Öffnen Sie die Tabelle in der Tables-Web-App.
2. Klicken Sie mit der rechten Maustaste auf die Zeile.
3. Klicken Sie auf Link zu dieser Zeile abrufen.
4. Fügen Sie die URL an einer beliebigen Stelle ein, damit Sie die ID kopieren können.
5. In der URL befindet sich die ID nach /row/.

Im folgenden Beispiel wird gezeigt, wo sich die Zeilen-ID in der URL befindet:

https://tables.area120.google.com/table/TABLE_ID/row/ROW_ID

Mehrere Zeilen in einer Tabelle aktualisieren

Im folgenden Beispiel wird gezeigt, wie die Werte mehrerer Zeilen in einer Tabelle aktualisiert werden:

var tableID = “TABLE_ID”;
var tableName = "tables/" + tableID;
var requests = [
  {row: {name: "tables/TABLE_ID/rows/ROW_ID_1", values: {"Column": "WORLD"}}},
  {row: {name: "tables/TABLE_ID/rows/ROW_ID_2", values: {"Column": "WORLD"}}},
  {row: {name: "tables/TABLE_ID/rows/ROW_ID_3", values: {"Column": "WORLD"}}},
];
var response = Area120Tables.Tables.Rows.batchUpdate({requests: requests}, tableName);
Logger.log("Batch update rows:" + JSON.stringify(response));

Hinweis: Batch-Vorgänge können bis zu 500 Zeilen umfassen.

Zeile in einer Tabelle löschen

Im folgenden Beispiel wird gezeigt, wie eine einzelne Zeile aus einer Tabelle gelöscht wird:

var rowName = "tables/TABLE_ID/rows/ROW_ID";
var response = Area120Tables.Tables.Rows.remove(rowName);
Logger.log("Delete row:" + JSON.stringify(response));

Mehrere Zeilen in einer Tabelle löschen

Im folgenden Beispiel wird gezeigt, wie mehrere Zeilen in einer Tabelle gelöscht werden:

var tableID = “TABLE_ID”;
var tableName = "tables/" + tableID;
var rowNames = [
  "tables/TABLE_ID/rows/ROW_ID_1",
  "tables/TABLE_ID/rows/ROW_ID_2",
  "tables/TABLE_ID/rows/ROW_ID_3",
];
Area120Tables.Tables.Rows.batchDelete({names: rowNames}, tableName);

Gelöschte Zeilen wiederherstellen

Sie können gelöschte Zeilen über die Tabellen-Benutzeroberfläche wiederherstellen. So stellen Sie eine gelöschte Zeile wieder her:

1. Öffnen Sie auf Ihrem Computer die Tables-Web-App.
2. Öffnen Sie die Tabelle, in der Sie Zeilen wiederherstellen möchten.
3. Klicken Sie oben auf „Gelöschte Zeilen und Spalten anzeigen“ .
4. Klicken Sie auf Gelöschte Zeilen.
5. Klicken Sie rechts neben der Zeile, die Sie wiederherstellen möchten, auf „Aus dem Papierkorb wiederherstellen“ .

Liste der Arbeitsbereiche abrufen

Im folgenden Beispiel wird gezeigt, wie eine Liste aller Workspaces abgerufen wird, deren Inhaber der Nutzer ist.

// Get list of workspaces the user owns and lists the tables in each one:
var response = Area120Tables.Workspaces.list();
if (response) {
  var workspaces = response.workspaces;
  for (var workspace of workspaces){
    Logger.log(workspace.displayName);
    for (var table of workspace.tables) {
      Logger.log('Table: ' + table);
    }
  }
}

Unten sehen Sie ein Beispiel für die Ausgabeprotokolle:

My Workspace
Table: Table 1
Table: Table 2
My TODOs
Table: Tasks