Servizio tabelle

Il servizio Tables consente agli script di leggere e modificare in modo programmatico le righe all'interno di Google Tables.

Nota: si tratta di un servizio avanzato che deve essere attivato prima dell'uso.

Riferimento

Per ulteriori informazioni su questo servizio, consulta la documentazione dell'API Tables. Come tutti i servizi avanzati di Apps Script, il servizio Tables utilizza gli stessi oggetti, metodi e parametri dell'API pubblica. Per maggiori informazioni, consulta Come vengono determinate le firme dei metodi.

Per segnalare problemi e trovare altra assistenza, consulta la guida all'assistenza di Tables.

Codice di esempio

Ottenere un elenco di tabelle

L'esempio riportato di seguito mostra come ottenere un elenco di tutte le tabelle di proprietà dell'utente.

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

Di seguito è riportato un esempio di risposta, che include informazioni sulla tabella e sulle definizioni delle colonne della tabella:

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

Per impostazione predefinita, la risposta include fino a 20 tabelle. Per recuperare altre tabelle, pagina le risposte utilizzando i parametri page_token e page_size, riportati di seguito:

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

Il valore massimo del parametro page_size per le tabelle di elenco è 100.

Recuperare le informazioni e le definizioni delle colonne di una tabella

L'esempio seguente mostra come recuperare le informazioni e la definizione della colonna di una tabella specifica.

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

Trovare l'ID tabella

Per trovare l'ID di una tabella, apri la tabella nell'app web Tables. Nell'URL in alto, l'ID tabella si trova subito dopo /table/.

L'esempio seguente mostra dove trovare l'ID tabella in vari URL di Tables:

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

Leggere le righe di una tabella

L'esempio riportato di seguito mostra come ottenere un elenco di righe di una tabella e leggere i valori dei campi.

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

Di seguito è riportata una risposta di esempio. La risposta include un elenco delle righe della tabella e i valori per ciascun campo.

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

Per impostazione predefinita, la risposta include fino a 50 righe. Per recuperare più righe, pagina le risposte utilizzando i parametri page_token e page_size, indicati di seguito:

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

Se sono disponibili altre pagine, la risposta offre un nextPageToken. In caso contrario, la risposta non è definita. Per recuperare la pagina di risultati successiva, passa il valore nextPageToken alla chiamata dell'elenco successiva.

Il valore massimo del parametro page_size è 1000.

Recuperare una riga da una tabella

L'esempio seguente mostra come leggere i valori di campo di una riga di una tabella.

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

Filtrare l'elenco di righe

Per filtrare l'elenco di righe in modo da ottenere solo i risultati che ti interessano, utilizza il parametro filter. Per ulteriori dettagli sulla sintassi e sui tipi di colonne supportati dal filtro, consulta la documentazione dell'API di filtri.

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

La risposta include le righe con la colonna "Punto di contatto" impostata su '[e-mail]'

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

Creare una riga in una tabella

L'esempio seguente mostra come aggiungere una riga a una tabella.

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

Quando specifichi i valori da impostare per la nuova riga, le chiavi delle coppie chiave-valore dell'oggetto devono corrispondere esattamente ai titoli sensibili alle maiuscole delle colonne della tabella, a meno che il tipo di colonna scrivibile non sia una colonna di ricerca o di riepilogo. Puoi impostare i valori per le colonne lookup e summary utilizzando il valore della relazione. Devi aggiornare il valore della relazione utilizzando il nome della relazione nella finestra di dialogo Relazioni.

Nota: quando crei i titoli delle colonne, assicurati che non contengano spazi finali per evitare confusione.

I valori accettabili per una colonna dipendono dal tipo di dati della colonna:

Tipo di colonna	Tipo di dati (lettura)	Tipi di input accettati (scrittura)
Dati standard
Testo	String	String
Number	Number	Number
Data	Date Object { "year": Number, "month": Number, "day": Number }	Date, String (nella maggior parte dei formati di data)
Dati avanzati
Person	String (indirizzo email)	String (deve corrispondere all'utente Google)
Allegato file	Object[] { "id": String, "name": String, "mimeType": String, "url": String }	Questo campo non può essere modificato con l'API.
Località	Object { "latitude": Number, "longitude": Number, "address": String }	Object { "latitude": Number (required), "longitude": Number (required), "address": String }
Voce avanzata
Menu a discesa	String	String (deve corrispondere alle opzioni del menu a discesa)
Tag	String[] (array di opzioni di tag)	String[] (deve corrispondere alle opzioni tag)
Casella di controllo	Boolean	Boolean
Elenco di controllo	String[] (array di voci dell'elenco)	String[] (deve corrispondere agli elementi dell'elenco)
Dati collegati
Relazione	String	String: "tables/[LINKED_TABLE_ID]/rows/[LINKED_ROW_ID]"
Ricerca	Dipende dal tipo di colonna di origine.	Questo campo non può essere modificato e verrà aggiornato con il valore collegato.
Riepilogo	Dipende dal tipo di colonna di origine e dalla funzione di riepilogo: Conteggio: Number Massimo in una colonna di tipo Data: String Valori elenco: Array	Questo campo non può essere modificato.
Campo calcolato
ID automatico	Number	Questo campo non può essere modificato.
Metadati
Autore	String	Questo campo non può essere modificato.
Data/ora creazione	Object { “seconds”: Number, “nanos”: Number }	Questo campo non può essere modificato.
Updater	String	Questo campo non può essere modificato.
Data/ora aggiornamento	Object { “seconds”: Number, “nanos”: Number }	Questo campo non può essere modificato.

Il servizio Tables fa del suo meglio per convertire i valori specificati in modo che corrispondano al tipo di colonna. Se i dati non corrispondono, il valore non viene impostato e viene lasciato vuoto per le nuove righe.

Aggiungere più righe a una tabella

L'esempio riportato di seguito mostra come aggiungere più righe a una tabella contemporaneamente.

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)

Nota: le operazioni batch possono includere fino a 500 righe.

Aggiornare una riga in una tabella

L'esempio seguente mostra come aggiornare i valori di una riga esistente in una tabella:

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

La risposta restituisce la riga aggiornata.

Trovare l'ID riga

Puoi trovare l'ID di una riga in due modi:

Ottenere l'ID riga con l'API

Quando leggi le righe di una tabella, puoi utilizzare l'attributo name per ogni riga, che include gli ID tabella e riga.

Recuperare l'ID riga dall'interfaccia utente di Tables

1. Apri la tabella nell'app web Tables.
2. Fai clic con il tasto destro del mouse sulla riga.
3. Fai clic su Ottieni il link a questa riga.
4. Incolla l'URL da qualche parte in modo da poter copiare l'ID.
5. Nell'URL, l'ID si trova dopo /row/.

L'esempio seguente mostra dove trovare l'ID riga nell'URL:

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

Aggiornare più righe in una tabella

L'esempio seguente mostra come aggiornare i valori di più righe in una tabella:

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

Nota: le operazioni batch possono includere fino a 500 righe.

Eliminare una riga in una tabella

L'esempio seguente mostra come eliminare una singola riga da una tabella:

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

Eliminare più righe in una tabella

L'esempio seguente mostra come eliminare più righe in una tabella:

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

Ripristinare le righe eliminate

Puoi ripristinare le righe eliminate dall'interfaccia utente di Tables. Per ripristinare una riga eliminata:

1. Sul computer, apri la web app Tables.
2. Apri la tabella in cui vuoi ripristinare le righe.
3. In alto, fai clic su Mostra righe e colonne eliminate .
4. Fai clic su Righe eliminate.
5. A destra della riga che vuoi ripristinare, fai clic su Ripristina dal cestino .

Visualizzare un elenco di spazi di lavoro

L'esempio riportato di seguito mostra come ottenere un elenco di tutte le aree di lavoro di proprietà dell'utente.

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

Di seguito è riportato un esempio di log di output:

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