Obsługa tabel

Usługa Tables umożliwia skryptom programowe odczytywanie i edytowanie wierszy w Tabelach Google.

Dokumentacja

Więcej informacji o tej usłudze znajdziesz w dokumentacji interfejsu Tables API. Podobnie jak wszystkie usługi zaawansowane w Apps Script, usługa Tables używa tych samych obiektów, metod i parametrów co publiczny interfejs API. Więcej informacji znajdziesz w artykule Jak określa się sygnatury metod.

Aby zgłosić problemy i uzyskać dodatkową pomoc, zapoznaj się z przewodnikiem pomocy dotyczącym tabel.

Przykładowy kod

Pobieranie listy tabel

Poniższy przykład pokazuje, jak uzyskać listę wszystkich tabel należących do użytkownika.

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

Poniżej znajdziesz przykład odpowiedzi, która zawiera informacje o tabeli i definicje kolumn tabeli:

{   “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   ] }

Odpowiedź domyślnie zawiera do 20 tabel. Aby pobrać więcej tabel, podziel odpowiedzi na strony za pomocą parametrów page_token i page_size, jak pokazano poniżej:

// 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});   } }

Maksymalna wartość parametru page_size w przypadku tabel z listami to 100.

Pobieranie informacji o tabeli i definicji kolumn

Poniższy przykład pokazuje, jak uzyskać informacje o konkretnej tabeli i definicję kolumny.

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

Znajdowanie identyfikatora tabeli

Aby znaleźć identyfikator tabeli, otwórz ją w aplikacji internetowej Tabele. W adresie URL u góry identyfikator tabeli znajduje się bezpośrednio po znaku /table/.

Poniższy przykład pokazuje, gdzie znaleźć identyfikator tabeli w różnych adresach URL Arkuszy:

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

Odczytywanie wierszy tabeli

Poniższy przykład pokazuje, jak uzyskać listę wierszy tabeli i odczytać wartości pól.

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"]);   } }

Przykładowa odpowiedź jest widoczna poniżej. Odpowiedź zawiera listę wierszy w tabeli i wartości każdego pola.

{   “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": "[email protected]",  // 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   ], }

Domyślnie odpowiedź zawiera maksymalnie 50 wierszy. Aby pobrać więcej wierszy, podziel odpowiedzi na strony za pomocą parametrów page_token i page_size, jak pokazano poniżej:

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});   } }

Jeśli dostępnych jest więcej stron, w odpowiedzi pojawi się symbol nextPageToken. W przeciwnym razie odpowiedź jest nieokreślona. Aby pobrać następną stronę wyników, przekaż nextPageToken do wywołania następnej listy.

Maksymalna wartość parametru page_size to 1000.

Pobieranie jednego wiersza z tabeli

W przykładzie poniżej pokazujemy, jak odczytać wartości pól z jednego wiersza tabeli.

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); }

Filtrowanie listy wierszy

Aby przefiltrować listę wierszy i uzyskać tylko te wyniki, które Cię interesują, użyj parametru filter. Więcej informacji o składni i typach kolumn obsługiwanych przez filtr znajdziesz w dokumentacji interfejsu API filtrowania.

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\"=\"john.doe@gmail.com\""}) 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"]);   } }

Odpowiedź zawiera wiersze, w których kolumna „Osoba kontaktowa” ma wartość „[email protected]”.

{   “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": "[email protected]",  // Person         "Last updated": "October 9, 2020 6:35:38 PM EDT",         "Created on": "March 10, 2020 1:07:54 PM EST",       }     },     ... // More rows   ], }

Tworzenie wiersza w tabeli

Poniższy przykład pokazuje, jak dodać wiersz do tabeli.

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);

Gdy określasz wartości, które mają zostać ustawione w nowym wierszu, klucze par klucz-wartość obiektu muszą dokładnie odpowiadać tytułom kolumn tabeli z uwzględnieniem wielkości liter, chyba że typ kolumny z możliwością zapisu to kolumna wyszukiwania lub podsumowania. Wartości kolumn lookup i summary ustawiasz za pomocą wartości relacji. Musisz zaktualizować wartość relacji, używając nazwy relacji znalezionej w oknie Relationships (Relacje).

Akceptowane wartości kolumny zależą od jej typu danych:

Typ kolumny Typ danych (odczyt) Akceptowane typy danych wejściowych (zapis)
Dane standardowe
Text String String
Number Number Number
Data Date
Object {
"year": Number,
"month": Number,
"day": Number
} 		Date, String (w większości formatów daty)
Dane rozszerzone
Person String (adres e-mail) String (musi być zgodny z użytkownikiem Google)
Załącznik Object[] {
"id": String,
"name": String,
"mimeType": String,
"url": String
} 		Tego pola nie można modyfikować za pomocą interfejsu API.
Lokalizacja Object {
"latitude": Number,
"longitude": Number,
"address": String
} 		Object {
"latitude": Number (required),
"longitude": Number (required),
"address": String
}
Rozbudowany wpis
Menu String String (musi pasować do opcji menu)
Tagi String[] (tablica opcji tagów) String[] (musi być zgodny z opcjami tagu)
Pole wyboru Boolean Boolean
Lista kontrolna String[] (tablica elementów listy) String[] (musi pasować do elementów listy)
Połączone dane
Relacja String String: "tables/[LINKED_TABLE_ID]/rows/[LINKED_ROW_ID]"
Wyszukiwanie Zależy od typu kolumny źródłowej. Tego pola nie można modyfikować. Będzie ono aktualizowane zgodnie z połączoną wartością.
Podsumowanie Zależy od typu kolumny źródłowej i funkcji podsumowania:
Liczba: Number
Maksymalna wartość w kolumnie typu Data: String
Lista wartości: Array		 Tego pola nie można modyfikować.
Pole obliczeniowe
Identyfikator automatyczny Number Tego pola nie można zmienić.
Metadane
Twórca String Tego pola nie można zmienić.
Czas utworzenia Object {
“seconds”: Number,
“nanos”: Number
} 		Tego pola nie można zmienić.
Aktualizator String Tego pola nie można zmienić.
Czas aktualizacji Object {
“seconds”: Number,
“nanos”: Number
}		 Tego pola nie można zmienić.

Usługa Tabele dokłada wszelkich starań, aby przekonwertować podane wartości tak, aby pasowały do typu kolumny. Jeśli dane nie pasują, wartość nie zostanie ustawiona i w przypadku nowych wierszy pozostanie pusta.

Dodawanie wielu wierszy do tabeli

Poniższy przykład pokazuje, jak jednocześnie dodać do tabeli kilka wierszy. 

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)

Aktualizowanie wiersza w tabeli

Poniższy przykład pokazuje, jak zaktualizować wartości w istniejącym wierszu tabeli: 

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));
 Odpowiedź zwraca zaktualizowany wiersz.

Znajdowanie identyfikatora wiersza

Identyfikator wiersza możesz znaleźć na 2 sposoby:

Pobieranie identyfikatora wiersza za pomocą interfejsu API

Podczas odczytywania wierszy z tabeli możesz użyć atrybutu name dla każdego wiersza, który zawiera identyfikatory tabeli i wiersza.

Pobieranie identyfikatora wiersza z interfejsu tabel
  1. Otwórz tabelę w aplikacji internetowej Tables.
  2. Kliknij wiersz prawym przyciskiem myszy.
  3. Kliknij Pobierz link do tego wiersza.
  4. Wklej adres URL w dowolnym miejscu, aby móc skopiować identyfikator.
  5. W adresie URL identyfikator znajduje się po znaku /row/.

Poniższy przykład pokazuje, gdzie w adresie URL znajduje się identyfikator wiersza:

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

Aktualizowanie wielu wierszy w tabeli

Poniższy przykład pokazuje, jak zaktualizować wartości w wielu wierszach tabeli: 

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));

Usuwanie wiersza w tabeli

Poniższy przykład pokazuje, jak usunąć jeden wiersz z tabeli: 

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

Usuwanie wielu wierszy w tabeli

Poniższy przykład pokazuje, jak usunąć wiele wierszy w tabeli: 

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);

Przywracanie usuniętych wierszy

Usunięte wiersze możesz przywrócić w interfejsie tabel. Aby przywrócić usunięty wiersz, wykonaj te czynności:

  1. Na komputerze otwórz aplikację internetową Tables.
  2. Otwórz tabelę, w której chcesz przywrócić wiersze.
  3. U góry kliknij Pokaż usunięte wiersze i kolumny .
  4. Kliknij Usunięte wiersze.
  5. Po prawej stronie wiersza, który chcesz przywrócić, kliknij Przywróć z kosza.

Pobieranie listy obszarów roboczych

Poniższy przykład pokazuje, jak uzyskać listę wszystkich obszarów roboczych, których użytkownik jest właścicielem.

// 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);     }   } }

Poniżej znajdziesz przykład dzienników wyjściowych: 

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