Cette page a été traduite par l'API Cloud Translation.

Service de tables

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

Reference

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 la section Comment les signatures de méthode sont-elles déterminées ?

Pour signaler des problèmes et obtenir de l'aide, consultez le guide d'assistance des 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 des 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 tables par défaut. Pour récupérer plus de tables, 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 répertorier les tables est de 100.

Obtenir les informations d'un tableau et les définitions des colonnes

L'exemple suivant montre comment obtenir les 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'une table, ouvrez-la dans l'application Web Tables. Dans l'URL située en haut de la page, l'ID de la table se trouve juste après /table/.

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

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 un exemple de réponse ci-dessous. La réponse inclut une liste des lignes de la table 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": "liz@gmail.com",  // 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 une 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 à partir d'une table

L'exemple suivant montre comment lire les valeurs des champs d'une ligne dans 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 pour lesquelles la colonne "Point de contact" est définie sur "john.doe@gmail.com".

{
  “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": "john.doe@gmail.com",  // 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 une table

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 de la table, sauf si le type de la colonne accessible en écriture est une colonne lookup ou summary. 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 disponible dans la boîte de dialogue Relations.

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

Type de colonne	Type de données (lecture)	Types de données 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é à l'aide de 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 des 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]"`
Recherche	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ésumé: Nombre: `Number` Utilisation maximale d'une colonne de type date: `String` Valeurs de liste: `Array`	Ce champ ne peut pas être modifié.
Champ calculé
ID automatique	`Number`	Impossible de modifier ce champ.
Métadonnées
Créateur	`String`	Impossible de modifier ce champ.
Date et heure de création	`Object { “seconds”: Number, “nanos”: Number }`	Impossible de modifier ce champ.
Outil de mise à jour	`String`	Impossible de modifier ce champ.
Heure de mise à jour	`Object { “seconds”: Number, “nanos”: Number }`	Impossible de modifier ce champ.

Le service Tables tente au mieux de convertir les valeurs données pour qu'elles correspondent au type de colonne. Si les données ne correspondent pas, la valeur ne sera pas définie et les données seront vides pour les nouvelles lignes.

Ajouter plusieurs lignes à une table

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 façons:

Obtenir l'ID de ligne avec l'API

Lorsque vous lisez les 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 à partir de l'interface utilisateur de Tables

Ouvrez la table dans l'application Web Tables.
Effectuez un clic droit sur la ligne.
Cliquez sur Obtenir le lien vers cette ligne.
Collez l'URL quelque part afin de pouvoir copier l'ID.
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 d'une table

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'une table :

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 d'une table

L'exemple suivant montre comment supprimer plusieurs lignes d'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 les lignes supprimées

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

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

Obtenir la liste des espaces de travail

L'exemple suivant montre comment obtenir la liste de tous les espaces de travail appartenant à l'utilisateur.

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