Service de tables

Le service Tables permet aux scripts de lire et de modifier des lignes de manière programmatique dans Google Tables.

Référence

Pour en savoir plus sur ce service, consultez la documentation de l'API Tables. Comme tous les services avancés d'Apps Script, le service Tables utilise les mêmes objets, méthodes et paramètres que l'API publique. Pour en savoir plus, consultez Déterminer les signatures de méthode.

Pour signaler des problèmes et obtenir de l'aide, consultez le guide d'assistance Tables.

Exemple de code

Obtenir la liste des tables

L'exemple suivant montre comment obtenir la liste de toutes les tables appartenant à l'utilisateur.

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

Vous trouverez ci-dessous un exemple de réponse, qui inclut des informations sur la table et les définitions de ses colonnes :

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

La réponse inclut jusqu'à 20 tableaux par défaut. Pour récupérer plus de tableaux, paginez les réponses à l'aide des paramètres page_token et page_size, comme indiqué ci-dessous :

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

La valeur maximale du paramètre page_size pour les tableaux de liste est de 100.

Obtenir des informations sur une table et les définitions de ses colonnes

L'exemple suivant montre comment obtenir des informations et la définition des colonnes d'une table spécifique.

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

Trouver l'ID de la table

Pour trouver l'ID d'un tableau, ouvrez-le dans l'application Web Tables. Dans l'URL en haut de la page, l'ID du tableau se trouve juste après /table/.

L'exemple ci-dessous montre où trouver l'ID de tableau dans différentes URL 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

Lire les lignes d'un tableau

L'exemple suivant montre comment obtenir la liste des lignes d'une table et lire les valeurs des champs.

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

Vous trouverez ci-dessous un exemple de réponse. La réponse inclut une liste des lignes du tableau et les valeurs de chaque champ.

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

La réponse inclut jusqu'à 50 lignes par défaut. Pour récupérer plus de lignes, paginez les réponses à l'aide des paramètres page_token et page_size, comme indiqué ci-dessous :

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

Si d'autres pages sont disponibles, la réponse propose un nextPageToken. Sinon, la réponse n'est pas définie. Pour récupérer la page de résultats suivante, transmettez nextPageToken à l'appel de liste suivant.

La valeur maximale du paramètre page_size est de 1 000.

Obtenir une ligne d'un tableau

L'exemple suivant montre comment lire les valeurs de champ d'une ligne d'une table.

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

Filtrer la liste des lignes

Pour filtrer la liste des lignes afin d'obtenir uniquement les résultats qui vous intéressent, utilisez le paramètre filter. Pour en savoir plus sur la syntaxe et les types de colonnes acceptés par le filtre, consultez la documentation de l'API de filtrage.

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

La réponse inclut les lignes dont la colonne "Point de contact" est définie sur "[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   ], }

Créer une ligne dans un tableau

L'exemple suivant montre comment ajouter une ligne à une table.

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

Lorsque vous spécifiez les valeurs à définir pour la nouvelle ligne, les clés des paires clé-valeur de l'objet doivent correspondre exactement aux titres sensibles à la casse des colonnes du tableau, sauf si le type de la colonne modifiable est une colonne Recherche ou Récapitulatif. Vous définissez les valeurs des colonnes lookup et summary à l'aide de la valeur de la relation. Vous devez mettre à jour la valeur de la relation à l'aide du nom de la relation indiqué dans la boîte de dialogue Relations.

Les valeurs acceptables pour une colonne dépendent du type de données de la colonne :

Type de colonne Type de données (lecture) Types d'entrée acceptés (écriture)
Données standards
Texte String String
Number Number Number
Date Date
Object {
"year": Number,
"month": Number,
"day": Number
} 		Date, String (dans la plupart des formats de date)
Données enrichies
Personne String (adresse e-mail) String (doit correspondre à l'utilisateur Google)
Pièce jointe Object[] {
"id": String,
"name": String,
"mimeType": String,
"url": String
} 		Ce champ ne peut pas être modifié avec l'API.
Emplacement Object {
"latitude": Number,
"longitude": Number,
"address": String
} 		Object {
"latitude": Number (required),
"longitude": Number (required),
"address": String
}
Entrée enrichie
Menu déroulant String String (doit correspondre aux options du menu déroulant)
Tags String[] (tableau d'options de tag) String[] (doit correspondre aux options de tag)
Case à cocher Boolean Boolean
Checklist String[] (tableau d'éléments de liste) String[] (doit correspondre aux éléments de la liste)
Données associées
Relation String String: "tables/[LINKED_TABLE_ID]/rows/[LINKED_ROW_ID]"
Rechercher Dépend du type de colonne source. Ce champ ne peut pas être modifié et sera mis à jour avec la valeur associée.
Résumé Dépend du type de colonne source et de la fonction de récapitulation :
Nombre : Number
Max sur une colonne de type "Date" : String
Lister les valeurs : Array		 Ce champ ne peut pas être modifié.
Champ calculé
ID automatique Number Ce champ ne peut pas être modifié.
Métadonnées
Créateur String Ce champ ne peut pas être modifié.
Heure de création Object {
“seconds”: Number,
“nanos”: Number
} 		Ce champ ne peut pas être modifié.
Outil de mise à jour String Ce champ ne peut pas être modifié.
Heure de mise à jour Object {
“seconds”: Number,
“nanos”: Number
}		 Ce champ ne peut pas être modifié.

Le service Tables s'efforce de convertir les valeurs fournies pour qu'elles correspondent au type de colonne. Si les données ne correspondent pas, la valeur ne sera pas définie et restera vide pour les nouvelles lignes.

Ajouter plusieurs lignes à un tableau

L'exemple suivant montre comment ajouter plusieurs lignes à une table en même temps. 

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)

Mettre à jour une ligne dans une table

L'exemple suivant montre comment mettre à jour les valeurs d'une ligne existante dans une table : 

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 réponse renvoie la ligne mise à jour.

Trouver l'ID de la ligne

Vous pouvez trouver l'ID d'une ligne de deux manières :

Obtenir l'ID de ligne avec l'API

Lorsque vous lisez des lignes d'une table, vous pouvez utiliser l'attribut name pour chaque ligne, qui inclut les ID de table et de ligne.

Obtenir l'ID de ligne depuis l'interface utilisateur Tables
  1. Ouvrez le tableau dans l'application Web Tables.
  2. Effectuez un clic droit sur la ligne.
  3. Cliquez sur Obtenir le lien vers cette ligne.
  4. Collez l'URL quelque part pour pouvoir copier l'ID.
  5. Dans l'URL, l'ID se trouve après /row/.

L'exemple ci-dessous montre où trouver l'ID de ligne dans l'URL :

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

Mettre à jour plusieurs lignes dans un tableau

L'exemple suivant montre comment mettre à jour les valeurs de plusieurs lignes d'une table : 

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

Supprimer une ligne dans une table

L'exemple suivant montre comment supprimer une seule ligne d'un tableau : 

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

Supprimer plusieurs lignes dans un tableau

L'exemple suivant montre comment supprimer plusieurs lignes dans une table : 

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

Restaurer des lignes supprimées

Vous pouvez restaurer des lignes supprimées à partir de l'interface utilisateur Tables. Pour restaurer une ligne supprimée, procédez comme suit :

  1. Sur votre ordinateur, ouvrez l'application Web Tables.
  2. Ouvrez la table dans laquelle vous souhaitez restaurer des lignes.
  3. En haut de l'écran, cliquez sur Afficher les lignes et colonnes supprimées .
  4. Cliquez sur Lignes supprimées.
  5. À droite de la ligne que vous souhaitez restaurer, cliquez sur Restaurer depuis la corbeille .

Obtenir la liste des espaces de travail

L'exemple suivant montre comment obtenir la liste de tous les espaces de travail dont l'utilisateur est propriétaire.

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

Vous trouverez ci-dessous un exemple de journaux de sortie : 

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