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

Pour signaler des problèmes et obtenir d'autres informations d'assistance, consultez le guide d'assistance pour les tables.

Exemple de code

Obtenir une liste de 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 le tableau et les définitions des colonnes du tableau:

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

Par défaut, la réponse inclut jusqu'à 20 tableaux. Pour récupérer d'autres 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 100.

Obtenir les informations et les définitions des colonnes d'une table

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'un tableau, ouvrez-le dans l'application Web Tables. Dans l'URL en haut de l'écran, l'ID du tableau se trouve juste après /table/.

L'exemple ci-dessous montre où trouver l'ID de table 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'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 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": "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
  ],
}

Par défaut, la réponse comprend jusqu'à 50 lignes. 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 est indéfinie. Pour récupérer la page de résultats suivante, transmettez le nextPageToken au prochain appel de liste.

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

Obtenir une ligne d'une table

L'exemple suivant montre comment lire les valeurs de champ d'une ligne à partir 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 compatibles avec 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 "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 en écriture est une colonne de recherche ou de récapitulatif. Vous définissez les valeurs des colonnes recherche et récapitulatif à l'aide de la valeur de la relation. Vous devez mettre à jour la valeur de la relation à l'aide du nom de la relation figurant 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 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 }`
Saisie enrichie
Menu déroulant	`String`	`String` (doit correspondre aux options du menu déroulant)
Tags	`String[]` (tableau d'options de balise)	`String[]` (doit correspondre aux options de balise)
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é	Cela dépend du type de colonne source et de la fonction récapitulative: Nombre: `Number` Valeur maximale dans une colonne de type "Date": `String` Valeurs de liste: `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 données pour qu'elles correspondent au type de colonne. Si les données ne correspondent pas, la valeur n'est pas définie et reste 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 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 à partir 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 Tables

Ouvrez le tableau 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 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'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 depuis 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 de l'écran, cliquez sur Afficher les lignes et colonnes supprimées .
Cliquez sur Lignes supprimées.
À 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