Servizio tabelle

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

Nota: questo è un servizio avanzato che deve essere attivato prima dell'uso.

Riferimento

Per saperne di più su questo servizio, consulta la documentazione dell'API Tables. Come tutti i servizi avanzati in 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 altro supporto, consulta la Guida all'assistenza di Tables.

Codice di esempio

Ottenere un elenco di tabelle

Il seguente esempio 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 le 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 più tabelle, impagina le risposte utilizzando i parametri page_token e page_size, mostrati 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 l'elenco delle tabelle è 100.

Recuperare le informazioni e le definizioni delle colonne di una tabella

L'esempio seguente mostra come ottenere le informazioni e la definizione delle colonne 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

Lettura delle righe di una tabella

Il seguente esempio mostra come ottenere un elenco delle 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 è riportato un esempio di risposta. 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, impagina le risposte utilizzando i parametri page_token e page_size, mostrati 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 successiva dei risultati, passa il valore nextPageToken alla chiamata di elenco successiva.

Il valore massimo del parametro page_size è 1000.

Recuperare una riga da una tabella

Il seguente esempio mostra come leggere i valori dei campi 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 delle 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 filtraggio.

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

Il seguente esempio 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 delle colonne della tabella sensibili alle maiuscole e minuscole, a meno che il tipo della colonna scrivibile non sia una colonna di ricerca o di riepilogo. Imposti i valori per le colonne lookup e summary utilizzando il valore per la relazione. Devi aggiornare il valore della relazione utilizzando il nome della relazione che si trova nella finestra di dialogo Relazioni.

Nota :quando crei i titoli delle colonne, assicurati che non abbiano 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 accettabili (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)
Informazioni aggiuntive
Person	String (indirizzo email)	String (deve corrispondere all'utente Google)
File allegato	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 per i tag)	String[] (deve corrispondere alle opzioni per i tag)
Casella di controllo	Boolean	Boolean
Elenco di controllo	String[] (array di voci di elenco)	String[] (deve corrispondere alle voci 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 Elenca valori: 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 tenta di convertire al meglio i valori forniti in modo che corrispondano al tipo di colonna. Se i dati non corrispondono, il valore non viene impostato e rimane vuoto per le nuove righe.

Aggiungere più righe a una tabella

L'esempio seguente 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.

Aggiorna una riga in una tabella

Il seguente esempio 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 link a questa riga.
4. Incolla l'URL in un punto qualsiasi per poter copiare l'ID.
5. All'interno dell'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

Il seguente esempio 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

Il seguente esempio 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

Il seguente esempio 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, segui questi passaggi:

1. Sul computer, apri l'app web 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 da ripristinare, fai clic su Ripristina dal cestino .

Ottenere un elenco di spazi di lavoro

L'esempio seguente mostra come ottenere un elenco di tutti i workspace 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 dei log di output:

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