Servicio de tablas

El servicio Tables permite que las secuencias de comandos lean y editen filas de manera programática en Google Tables.

Nota: Este es un servicio avanzado que se debe habilitar antes de usarlo.

Reference

Si deseas obtener más información sobre este servicio, consulta la documentación de la API de Tables. Como todos los servicios avanzados de Apps Script, el servicio Tables usa los mismos objetos, métodos y parámetros que la API pública. Si deseas obtener más información, consulta Cómo se determinan las firmas de métodos.

Para informar problemas y encontrar otro tipo de asistencia, consulta la guía de asistencia de tablas.

Código de muestra

Obtén una lista de tablas

En el siguiente ejemplo, se muestra cómo obtener una lista de todas las tablas que posee el usuario.

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

A continuación, se muestra un ejemplo de la respuesta, que incluye información sobre la tabla y sus definiciones:

{
  “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 respuesta incluye hasta 20 tablas de forma predeterminada. Para recuperar más tablas, pagina las respuestas con los parámetros page_token y page_size, que se muestran a continuación:

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

El valor máximo del parámetro page_size para enumerar tablas es 100.

Cómo obtener la información de una tabla y las definiciones de columnas

En el siguiente ejemplo, se muestra cómo obtener la información de una tabla específica y la definición de columnas.

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

Busca el ID de la tabla

Para encontrar el ID de una tabla, ábrela en la app web de Tables. En la URL de la parte superior, el ID de la tabla se encuentra justo después de /table/.

En el siguiente ejemplo, se muestra dónde encontrar el ID de tabla en varias URLs 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

Leer filas de una tabla

En el siguiente ejemplo, se muestra cómo obtener una lista de las filas de una tabla y leer los valores de los campos.

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

A continuación, se muestra una respuesta de ejemplo. La respuesta incluye una lista de las filas de la tabla y los valores de cada 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
  ],
}

La respuesta incluye hasta 50 filas de forma predeterminada. Para recuperar más filas, pagina las respuestas con los parámetros page_token y page_size, que se muestran a continuación:

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 hay más páginas disponibles, la respuesta ofrece un nextPageToken. De lo contrario, la respuesta no está definida. Para recuperar la siguiente página de resultados, pasa nextPageToken a la siguiente llamada a la lista.

El valor máximo del parámetro page_size es 1,000.

Obtén una fila de una tabla

En el siguiente ejemplo, se muestra cómo leer los valores de campo de una fila de una tabla.

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

Cómo filtrar la lista de filas

Si deseas filtrar la lista de filas para obtener solo los resultados que te interesan, usa el parámetro filter. Para obtener más detalles sobre la sintaxis y los tipos de columnas que admite el filtro, consulta la documentación de la API de filtrado.

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 respuesta incluye las filas con la columna “Punto de contacto” configurada como “[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
  ],
}

Crea una fila en una tabla

En el siguiente ejemplo, se muestra cómo agregar una fila a una tabla.

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

Cuando especificas los valores que se deben configurar para la nueva fila, las claves de los pares clave-valor de objetos deben coincidir exactamente con los títulos que distinguen mayúsculas de minúsculas de las columnas de la tabla, a menos que el tipo de columna que admite escritura sea una columna lookup o summary. Debes establecer valores para las columnas lookup y summary con el valor de la relación. Debes actualizar el valor de la relación usando el nombre de relación que se encuentra en el diálogo Relaciones.

Nota: Cuando crees títulos de columnas, asegúrate de que no tengan espacios finales para evitar confusiones.

Los valores aceptables para una columna dependen del tipo de datos de la columna:

Tipo de columna	Tipo de datos (lectura)	Tipos de entrada aceptables (escritura)
Datos estándar
Texto	String	String
Número	Number	Number
Fecha	Date Object { "year": Number, "month": Number, "day": Number }	Date, String (en la mayoría de los formatos de fecha)
Gran cantidad de datos
Persona	String (dirección de correo electrónico)	String (debe coincidir con el usuario de Google)
Archivo adjunto	Object[] { "id": String, "name": String, "mimeType": String, "url": String }	Este campo no se puede modificar con la API.
Ubicación	Object { "latitude": Number, "longitude": Number, "address": String }	Object { "latitude": Number (required), "longitude": Number (required), "address": String }
Entrada enriquecida
Menú desplegable	String	String (debe coincidir con las opciones del menú desplegable)
Etiquetas	String[] (matriz de opciones de etiqueta)	String[] (debe coincidir con las opciones de etiqueta)
Checkbox	Boolean	Boolean
Lista de tareas	String[] (matriz de elementos de la lista)	String[] (debe coincidir con los elementos de la lista)
Datos vinculados
Relación	String	String: "tables/[LINKED_TABLE_ID]/rows/[LINKED_ROW_ID]"
Búsqueda	Depende del tipo de columna de origen.	Este campo no se puede modificar y se actualizará con el valor vinculado.
Resumen	Depende del tipo de columna de origen y de la función de resumen: Count: Number Máx. en una columna de tipo de fecha: String Valores de lista: Array	No se puede modificar este campo.
Campo calculado
ID automático	Number	No se puede modificar este campo.
Metadata
Creador	String	No se puede modificar este campo.
Hora de creación	Object { “seconds”: Number, “nanos”: Number }	No se puede modificar este campo.
Programa de actualización	String	No se puede modificar este campo.
Hora de actualización	Object { “seconds”: Number, “nanos”: Number }	No se puede modificar este campo.

El servicio de tablas hace su mejor esfuerzo por convertir valores determinados para que coincidan con el tipo de columna. Si los datos no coinciden, no establecerá el valor y lo dejará en blanco para las filas nuevas.

Agrega varias filas a una tabla

En el siguiente ejemplo, se muestra cómo agregar varias filas a una tabla al mismo tiempo.

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: Las operaciones por lotes pueden incluir hasta 500 filas.

Actualiza una fila en una tabla

En el siguiente ejemplo, se muestra cómo actualizar los valores de una fila existente en una tabla:

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 respuesta muestra la fila actualizada.

Cómo buscar el ID de fila

Puede encontrar el ID de una fila de dos maneras:

Obtén el ID de fila con la API

Cuando lees filas de una tabla, puedes usar el atributo name para cada fila, que incluye los IDs de fila y la tabla.

Obtén el ID de fila de la IU de tablas

1. Abre la tabla en la app web de Tables.
2. Haz clic con el botón derecho en la fila.
3. Haga clic en Obtener vínculo a esta fila.
4. Pega la URL en alguna parte para que puedas copiar el ID.
5. En la URL, el ID es después de /row/.

En el siguiente ejemplo, se muestra dónde encontrar el ID de fila en la URL:

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

Actualiza varias filas en una tabla

En el siguiente ejemplo, se muestra cómo actualizar los valores de varias filas en una tabla:

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: Las operaciones por lotes pueden incluir hasta 500 filas.

Borra una fila en una tabla

En el siguiente ejemplo, se muestra cómo borrar una sola fila de una tabla:

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

Cómo borrar varias filas en una tabla

En el siguiente ejemplo, se muestra cómo borrar varias filas en una tabla:

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

Restablecer filas borradas

Puedes restablecer las filas borradas desde la IU de Tablas. Para restablecer una fila borrada, sigue estos pasos:

1. En tu computadora, abre la app web de Tables.
2. Abre la tabla en la que deseas restablecer filas.
3. En la parte superior, haz clic en Mostrar filas y columnas borradas .
4. Haz clic en Filas borradas.
5. A la derecha de la fila que deseas restablecer, haz clic en Restablecer de la papelera .

Obtén una lista de los lugares de trabajo

En el siguiente ejemplo, se muestra cómo obtener una lista de todos los lugares de trabajo que posee el usuario.

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

A continuación, se muestra un ejemplo de los registros de salida:

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