Serviço de mesa

O serviço Tables permite que scripts leiam e editem linhas de maneira programática no Google Tables.

Referência

Para mais informações sobre esse serviço, consulte a documentação da API Tables. Assim como todos os serviços avançados no Apps Script, o serviço Tabelas usa os mesmos objetos, métodos e parâmetros que a API pública. Para mais informações, consulte Como as assinaturas de método são determinadas.

Para denunciar problemas e encontrar outras opções de suporte, consulte o guia de suporte do Google Tabela.

Código de amostra

Receber uma lista de tabelas

O exemplo a seguir mostra como receber uma lista de todas as tabelas que o usuário tem.

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

Confira abaixo um exemplo da resposta, que inclui informações sobre a tabela e as definições de coluna dela:

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

A resposta inclui até 20 tabelas por padrão. Para recuperar mais tabelas, pagine as respostas usando os parâmetros page_token e page_size, mostrados abaixo:

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

O valor máximo do parâmetro page_size para tabelas de listagem é 100.

Receber informações e definições de colunas de uma tabela

O exemplo a seguir mostra como receber as informações e a definição de coluna de uma tabela específica.

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

Encontrar o ID da tabela

Para encontrar o ID de uma tabela, abra o app da Web Tabelas. No URL na parte de cima, o ID da tabela fica logo depois de /table/.

O exemplo abaixo mostra onde encontrar o ID da tabela em vários URLs do Google Tabela de dados:

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

Ler linhas de uma tabela

A amostra a seguir mostra como receber uma lista das linhas de uma tabela e ler os valores dos 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"]);   } }

Confira um exemplo de resposta abaixo. A resposta inclui uma lista das linhas na tabela e os 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": "[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   ], }

A resposta inclui até 50 linhas por padrão. Para recuperar mais linhas, pagine as respostas usando os parâmetros page_token e page_size, mostrados abaixo:

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 houver mais páginas disponíveis, a resposta vai oferecer um nextPageToken. Caso contrário, a resposta será indefinida. Para recuperar a próxima página de resultados, transmita o nextPageToken para a próxima chamada de lista.

O valor máximo do parâmetro page_size é 1.000.

Receber uma linha de uma tabela

A amostra a seguir mostra como ler os valores de campo de uma linha de uma tabela.

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

Filtrar a lista de linhas

Para filtrar a lista de linhas e obter apenas os resultados que você quer, use o parâmetro filter. Para mais detalhes sobre a sintaxe e os tipos de coluna aceitos pelo filtro, consulte a documentação da API de filtragem.

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

A resposta inclui as linhas com a coluna "Ponto de contato" definida como "[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   ], }

Criar uma linha em uma tabela

A amostra a seguir mostra como adicionar uma linha a uma tabela.

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

Ao especificar os valores a serem definidos para a nova linha, as chaves dos pares chave-valor do objeto precisam corresponder exatamente aos títulos sensíveis a maiúsculas e minúsculas das colunas da tabela, a menos que o tipo da coluna gravável seja uma coluna de pesquisa ou resumo. Você define valores para as colunas lookup e summary usando o valor da relação. Atualize o valor do relacionamento usando o nome encontrado na caixa de diálogo Relacionamentos.

Os valores aceitáveis para uma coluna dependem do tipo de dados dela:

Tipo de coluna Tipo de dados (leitura) Tipos de entrada aceitos (gravação)
Dados padrão
Texto String String
Número Number Number
Data Date
Object {
"year": Number,
"month": Number,
"day": Number
} 		Date, String (na maioria dos formatos de data)
Dados avançados
Person String (endereço de e-mail) String (precisa corresponder ao usuário do Google)
Anexo de arquivo Object[] {
"id": String,
"name": String,
"mimeType": String,
"url": String
} 		Este campo não pode ser modificado com a API.
Local Object {
"latitude": Number,
"longitude": Number,
"address": String
} 		Object {
"latitude": Number (required),
"longitude": Number (required),
"address": String
}
Entrada avançada
Lista suspensa String String (precisa corresponder às opções do menu suspenso)
Tags String[] (matriz de opções de tag) String[] (precisa corresponder às opções de tag)
Caixa de seleção Boolean Boolean
Lista de verificação String[] (matriz de itens de lista) String[] (precisa corresponder aos itens da lista)
Dados vinculados
Relacionamento String String: "tables/[LINKED_TABLE_ID]/rows/[LINKED_ROW_ID]"
Pesquisa Depende do tipo da coluna de origem. Esse campo não pode ser modificado e será atualizado com o valor vinculado.
Resumo Depende do tipo de coluna de origem e da função de resumo:
Contagem: Number
Máximo em uma coluna do tipo data: String
Listar valores: Array		 Não é possível modificar esse campo.
Campo calculado
ID automático Number Não é possível modificar esse campo.
Metadados
Criador String Não é possível modificar esse campo.
Horário de criação Object {
“seconds”: Number,
“nanos”: Number
} 		Não é possível modificar esse campo.
Google Updater String Não é possível modificar esse campo.
Horário de atualização Object {
“seconds”: Number,
“nanos”: Number
}		 Não é possível modificar esse campo.

O serviço de tabelas faz uma tentativa de conversão dos valores fornecidos para corresponder ao tipo de coluna. Se os dados não corresponderem, o valor não será definido e ficará em branco para novas linhas.

Adicionar várias linhas a uma tabela

A amostra a seguir mostra como adicionar várias linhas a uma tabela ao mesmo tempo. 

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)

Atualizar uma linha em uma tabela

O exemplo a seguir mostra como atualizar os valores de uma linha em uma tabela: 

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));
 A resposta retorna a linha atualizada.

Encontrar o ID da linha

É possível encontrar o ID de uma linha de duas maneiras:

Receber o ID da linha com a API

Ao ler linhas de uma tabela, você pode usar o atributo name para cada linha, que inclui os IDs da tabela e da linha.

Receber o ID da linha na interface do usuário "Tabelas"
  1. Abra a tabela no web app Tabelas.
  2. Clique com o botão direito do mouse na linha.
  3. Clique em Gerar link para esta linha.
  4. Cole o URL em algum lugar para copiar o ID.
  5. No URL, o ID está depois de /row/.

O exemplo abaixo mostra onde encontrar o ID da linha no URL:

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

Atualizar várias linhas em uma tabela

O exemplo a seguir mostra como atualizar os valores de várias linhas em uma tabela: 

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

Excluir uma linha de uma tabela

O exemplo a seguir mostra como excluir uma única linha de uma tabela: 

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

Excluir várias linhas em uma tabela

Confira na amostra a seguir como excluir várias linhas em uma tabela: 

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

Restaurar linhas excluídas

É possível restaurar linhas excluídas na interface do usuário do Tables. Para restaurar uma linha excluída, siga as etapas abaixo:

  1. No computador, abra o web app Tabela.
  2. Abra a tabela em que você quer restaurar as linhas.
  3. Na parte de cima, clique em Mostrar linhas e colunas excluídas .
  4. Clique em Linhas excluídas.
  5. À direita da linha que você quer restaurar, clique em Restaurar da lixeira .

Receber uma lista de espaços de trabalho

O exemplo a seguir mostra como receber uma lista de todos os espaços de trabalho de propriedade do usuário.

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

Confira abaixo um exemplo dos registros de saída: 

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