Serviço de mesa

O serviço de tabelas permite que os scripts leiam e editem linhas programaticamente no Google Tables.

Observação: esse é um serviço avançado que precisa ser ativado antes do uso.

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 de 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 relatar problemas e encontrar ajuda, consulte o guia de suporte a tabelas.

Exemplo de código

Acessar uma lista de tabelas

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

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

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

{
  “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, faça a paginação das 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 listar tabelas é 100.

Receber as informações de uma tabela e definições de coluna

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

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 a tabela no app da Web Tabelas. No URL na parte de cima, o ID está logo após /table/.

O exemplo abaixo mostra onde encontrar o ID da tabela em vários URLs de tabelas:

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

O exemplo a seguir mostra como acessar 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"]);
  }
}

Veja abaixo um exemplo de resposta. 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": "[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
  ],
}

A resposta inclui até 50 linhas por padrão. Para recuperar mais linhas, paginar 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 oferecerá um nextPageToken. Caso contrário, a resposta é 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.

Obter 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 receber apenas os resultados do seu interesse, use o parâmetro filter. Para mais detalhes sobre a sintaxe e os tipos de colunas compatíveis com o filtro, confira 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\"=\"[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"]);
  }
}

A resposta inclui as linhas com a coluna "Point of Contact" definida 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
  ],
}

Criar uma linha em uma tabela

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

Quando você especifica os valores a serem definidos para a nova linha, as chaves dos pares de chave-valor do objeto precisam corresponder exatamente aos títulos que diferenciam maiúsculas de minúsculas das colunas da tabela, a menos que o tipo da coluna gravável seja lookup ou summary. Você define valores para as colunas lookup e summary usando o valor do relacionamento. Você precisa atualizar o valor do relacionamento usando o nome que aparece na caixa de diálogo Relacionamentos.

Observação :ao criar títulos de coluna, verifique se eles não têm espaços à direita para evitar confusão.

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

Tipo de coluna	Tipo de dados (leitura)	Tipos de entrada aceitáveis (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 }	Não é possível modificar este campo 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 da lista)	String[] (precisa corresponder aos itens da lista)
Dados vinculados
Relação	String	String: "tables/[LINKED_TABLE_ID]/rows/[LINKED_ROW_ID]"
Pesquisa	Depende do tipo de coluna de origem.	Esse campo não pode ser modificado e vai ser atualizado com o valor vinculado.
Resumo	Depende do tipo de coluna de origem e da função de resumo: Contagem: Number Máx. em uma coluna de tipo de data: String Listar valores: Array	Não é possível modificar esse campo.
Campo calculado
ID automático	Number	Não é possível modificar este campo.
Metadados
Criador	String	Não é possível modificar este campo.
Horário da criação	Object { “seconds”: Number, “nanos”: Number }	Não é possível modificar este campo.
Google Updater	String	Não é possível modificar este campo.
Horário da atualização	Object { “seconds”: Number, “nanos”: Number }	Não é possível modificar este campo.

O serviço de tabelas tenta converter os valores fornecidos para que correspondam ao tipo de coluna. Se os dados não corresponderem, ele não definirá o valor e o deixará em branco para novas linhas.

Adicionar várias linhas a uma tabela

O exemplo 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)

Observação :as operações em lote podem incluir até 500 linhas.

Atualizar uma linha em uma tabela

O exemplo a seguir mostra como atualizar os valores de uma linha atual 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

Há duas maneiras de encontrar o ID de uma linha:

Conseguir 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 Tables

1. Abra a tabela no app da Web 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 poder copiar o ID.
5. No URL, o ID vem 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));

Observação :as operações em lote podem incluir até 500 linhas.

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

O exemplo a seguir mostra 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 Tables. Para restaurar uma linha excluída, siga as etapas abaixo:

1. No computador, abra o app da Web Tabelas.
2. Abra a tabela em que você quer restaurar as linhas.
3. Na parte superior, 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 .

Acessar uma lista de espaços de trabalho

O exemplo a seguir mostra como conseguir uma lista de todos os espaços de trabalho 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);
    }
  }
}

Veja abaixo um exemplo dos registros de saída:

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