Servizio tabelle

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

Riferimento

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

Per segnalare problemi e trovare ulteriore assistenza, consulta la guida di assistenza per le tabelle.

Codice campione

Recuperare 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 della 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, suddivide in pagine 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 elencare le tabelle è 100.

Recupero delle informazioni di una tabella e definizioni delle colonne

Il seguente esempio mostra come ottenere le informazioni di una tabella specifica e la definizione delle colonne.

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/.

Il seguente esempio mostra dove trovare l'ID tabella nei 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

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": "[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
  ],
}

Per impostazione predefinita, la risposta include fino a 50 righe. Per recuperare altre 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 più pagine, la risposta offre un nextPageToken. In caso contrario, la risposta non è definita. Per recuperare la pagina di risultati successiva, passa il nextPageToken alla successiva chiamata dell'elenco.

Il valore massimo del parametro page_size è 1000.

Ottieni una riga da una tabella

Il seguente esempio mostra come leggere i valori del 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 e ottenere solo i risultati di tuo interesse, utilizza il parametro filter. Per ulteriori dettagli sulla sintassi e sui tipi di colonne supportati dal filtro, consulta la documentazione relativa all'API sui 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\"=\"[email protected]\""})
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 "[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
  ],
}

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 oggetto devono corrispondere esattamente ai titoli delle colonne della tabella, sensibili alle maiuscole, a meno che il tipo della colonna scrivibile non sia una colonna lookup o summary. I valori per le colonne lookup e summary vengono impostati utilizzando il valore della relazione. Devi aggiornare il valore della relazione utilizzando il nome della relazione indicato nella finestra di dialogo Relazioni.

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.
Posizione Object {
"latitude": Number,
"longitude": Number,
"address": String
} 		Object {
"latitude": Number (required),
"longitude": Number (required),
"address": String
}
Inserimento avanzato
Menu a discesa String String (deve corrispondere alle opzioni del menu a discesa)
Tag String[] (array di opzioni tag) String[] (deve corrispondere alle opzioni dei tag)
Casella di controllo Boolean Boolean
Elenco di controllo String[] (array di elementi dell'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 su 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.
Aggiornamento String Questo campo non può essere modificato.
Ora aggiornamento Object {
“seconds”: Number,
“nanos”: Number
}		 Questo campo non può essere modificato.

Il servizio Tables tenta di 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

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

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 da una tabella, puoi utilizzare l'attributo name per ogni riga, che include gli ID tabella e riga.

Recuperare l'ID riga dall'interfaccia utente 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 da qualche parte in modo da poter copiare l'ID.
  5. All'interno dell'URL, l'ID è successivo a /row/.

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

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

Ripristina righe eliminate

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

  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 .

Recupero di un elenco di aree di lavoro

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