Google Apps Script, Parte 1: Conceitos, Google Spreadsheet e Google Calendar

O Google Apps Script é uma linguagem utilizada em desenvolvimento de aplicações integrando serviços da plataforma Google Apps. Além de permitir acesso a praticamente todas as APIs de serviços do Google, o Apps Script possibilita o acesso a serviços de terceiros ea automação de tarefas. Nesta série de dois artigos, será mostrado como usar o ambiente e a linguagem de script do Google para acessar e integrar os principais serviços do Google Apps, incluindo planilhas, calendários, contatos e documentos.

Nesta primeira parte, é apresentado o ambiente e os passos necessários para criar e executar um Google Apps Script. Na próxima parte, será demostrado como integrar vários serviços do Google para criar serviços personalizados, de forma simples e rápida.

A linguagem Google Apps Script é baseada em JavaScript, o que torna o aprendizado mais fácil. Além de oferecer suporte a serviços como emai e calendário, possibilita a criação de interfaces, diretamente em código ou utilizando o GUI Interface Builder, uma ferramenta visual no estilo RAD.

Para começar a utilizar a linguagem, é necessário possuir uma conta do Google por exemplo do GMail, ou de qualquer domínio que utilize a suíte do Google Apps. A seguir, são apresentados os passos para criar um script e escrever uma função utilizando uma planilha no Google Docs.

Acesso a planilhas

Crie uma nova planilha e execute Tools>Script Editor. Uma nova janela será exibida, como na figura a seguir (se necessário, permita que o navegador abra uma nova janela).

Note que todos os itens de menus e telas mostradas neste artigo estarão em inglês. Se preferir outro idioma, basta alterar as configurações do Google Docs (ou qualquer outro serviço que esteja utilizando, como Calendar, Google Sites etc).

O ambiente mostrado permite a criação, edição e visualização de scripts, além ae execução e depuração de funções. Há também a verificação de sintaxe em tempo real e o suporte a autocompletar de código.

Como o script é criado dentro de uma planilha, ele será capaz de manipular todos os seus dados. É possível, por exemplo, ler e escrever valores de células, alterar a formatação etc. É importante saber que um script criado para uma planilha existe apenas naquela planilha. No entanto, pode-se fazer uma cópia da planilha e os scripts também serão copiados.

Pode-se ainda publicar o script para a "Galeria de Scripts" (acessada pelo menu Tools>Script Galery). Os scripts são publicados via o editor de scripts, usando Share>Publish Project. Será exibida uma tela onde deve ser informado o nome do projeto, uma categoria e uma descrição. Após preencher todos os dados é só clicar no botão Publish e os scripts ficarão disponíveis para utilização.

Note que não é possível, a partir de um script, criar ou executar outros scripts, nem executar scripts de outras planilhas. Além disso, as variáveis criadas e executadas durante a execução do script são apagadas após o final da execução. Para armazenar valores utilizados durante a execução, uma sugestão é salvar os valores na própria planilha.

Como exemplo, abaixo é mostrado como alterar o script para adicionar um texto na coluna A da planilha. No editor de scripts, adicione o conteúdo desta listagem ao corpo da função:

function myFunction() {
  // recupera a planilha e depois a aba atual
  var planilha = SpreadsheetApp.getActiveSpreadsheet();
  var sheet = planilha.getActiveSheet();
  // retorna a última linha com dados e escreve texto na coluna 1
  var row = sheet.getLastRow()+1;
  sheet.getRange(row, 1).setValue("primeiro script");
}

O script é executado clicando no botão Play ou usando o comando Run. O editor avisa se o arquivo não foi salvo e pede um nome para o projeto. Se tudo estiver correto, ao executar aparecerá um texto na célula A1.

Todas as vezes em que é executado o script, um novo item será adicionado à coluna A da planilha. Isso porque sempre é obtida a última linha e adicionado 1. A função getRange(), também aceita outros valores como em sheet.getRange("A1").

Integração ao Calendar

O que foi feito até este ponto não parece muito, mas as coisas ficam mais interessantes quando agregamos novos serviços do Google Apps.

Vamos alterar o script para consultar o Google Calendar, procurar por um calendário e listar todas as datas do ano para aquele calendário. O script lerá da célula A1 o nome do calendário, e o intervalo de datas das células B1 e C1.

Primeiro é necessário colocar os valores na planilha, conforme a seguinte figura.

Para o meu usuário no Google Calendar existe um calendário chamado "Brazilian Holidays" que será utilizado para este exemplo. Você precisará alterar a célula A1 planilha para refletir um calendário existente (ou criado) para a sua conta. O código do próximo script é o seguinte, que deve ser adicionado abaixo do script anterior:

function myFunction() {
  // recupera a planilha/aba corrente
  var planilha = SpreadsheetApp.getActiveSpreadsheet();
  var sh = planilha.getActiveSheet();
  // recupera os valores das células
  var calName = sh.getRange("A1").getValue();
  var date_deb = sh.getRange("B1").getValue();
  var date_fin = sh.getRange("C1").getValue();
  // acessa a API do Google Calendar utilizando o nome do calendário
  var cal = CalendarApp.openByName(calName);
  // procura os eventos do calendário utilizando as datas recuperadas da planilha
  var events = cal.getEvents(new Date(date_deb), new Date(date_fin));

  // percorre o array events
  for (var i = 1 ; i < events.length ; ++i) {
    // para cada evento
    var event = events[i];
    var row = sh.getLastRow()+1;
    // escreve o título na coluna A
    sh.getRange("A"+row).setValue(event.getTitle());
    // a data de início na coluna B
    sh.getRange("B"+row).setValue(event.getStartTime());
    // a data do final do evento na Coluna C
    sh.getRange("C"+row).setValue(event.getEndTime());
  }
}

Neste exemplo, são utilizados os valores das céluas A1, B1 e C1 respectivamente, para buscar um calendário específico, e listar todos os eventos para um intervalo de data específico.

A opção View>Execution Transcript exibe, passo a passo, a execução de cada linha do script, incluindo valores com que as funções foram chamadas, objetos criados etc. Trata-de de uma ótima ferramenta para analisar o fluxo de execução de um script.

Como o exemplo utiliza a API do Calendar, e não apenas a planilha atual, o engine do Google Apps Script solicitará permissão para executar o script. A janela de solicitação exibe o usuário logado e todas as APIs que estão solicitando permissão. Após permitir o uso da API do Calendar, a execução do script terá o retorno mostrado a seguir (os dados mostrados, é claro, dependerão do calendário escolhido):

Observe que todos os eventos existentes do calendário no intervalo de 01 de janeiro até 31 de dezembro de 2011 foram listados e adicionados à planilha.

Criação de interfaces

Outra funcionalidade importante oferecida pelo Google Apps Script é a criação de interfaces com o usuário. Veremos agora um exemplo de script que cria um interface simples, com dois labels e um campo de texto, onde o usuário informa um número, que é elevado ao quadra. Note que a funcionalidade extremamente simples ajuda a focar nos funcionamento do Apps Script. Exemplos posteriores aumentarão em complexidade.

A interface utilizada neste exemplo foi criada no Interface GUI Builder (comando File> Build a User Interface), é exibida abaixo.

Todos os componentes visuais criados para o Google Apps Script devem ter valores para seu ID (e quando aplicável, no seu campo Name), para que os componentes possam ser utilizados em scripts. Note no canto superior direito da janela, que a parte Component Tree exibe todos os componentes que foram criados na tela, e que o componente pai é "Component1". Após salvar a interface (usamos o nome "MyGui 1"), ela pode ser carregada utilizando a instrução loadComponent() e adicionada à aplicação. O código abaixo mostra como utilizar o loadComponent() para carregar a nova tela:

function doGet() {
  // cria a aplicação e seta o título
  var app = UiApp.createApplication().setTitle("teste");
  // carrega o componente
  app.add(app.loadComponent("MyGui 1"));
  // cria um handler apontando para a função que deve ser chamada
  var handler = app.createServerClickHandler("elevaAoQuadrado");
  // adiciona o handler ao botão
  app.getElementById("btb_compute").addClickHandler(handler);
  // adiciona a árvore de componentes ao handler
  handler.addCallbackElement(app.getElementById("Component1"));
  // retorna a aplicação, necessário para publicar como serviço
  return app;
}

function exibeGuiNaPlanilha() {
  // cria a aplicação e seta o título, e carrega o componente
  var app = UiApp.createApplication().setTitle("teste");
  app.add(app.loadComponent("MyGui 1"));
  // cria um handler apontando para a função a ser chamada
  var handler = app.createServerClickHandler("elevaAoQuadrado");
  // adiciona o handler ao botão
  app.getElementById("btb_compute").addClickHandler(handler);
  // adiciona a árvore de componentes ao handler
  handler.addCallbackElement(app.getElementById("Component1"));
  // exibe a GUI da aplicação dentro de uma planilha (necessário caso
  // caso queira chamar a interface usando um botão ou item de menu)

  SpreadsheetApp.getActiveSpreadsheet().show(app);
}

function elevaAoQuadrado(e) {
  // recupera a aplicação
  var app = UiApp.getActiveApplication();
  var numero = 0;
 
  try  {
    // recupera campo texto da tela, recebido como parâmetro
    // e tenta converter o número para inteiro
    numero = parseInt(e.parameter.txt_number);
  }
  catch(ex) {
    app.getElementById('lbl_resultado').setText(ex);
  }
 
  var resultado = numero * numero;
  // referência para label na tela onde será exibido o resultado
  var lbl = app.getElementById('lbl_resultado');
  try {
    // escreve o valor no label
    lbl.setText(String(resultado));
  }
  catch(prob) {
    lbl.setText("erro: " + prob);
  }
  return app;
}

Esse novo script tem três métodos elevaAoQuadrado(), doGet() e exibeGuiNaPlanilha(). O método doGet() é invocado quando a aplicação é compartilhada e precisa retornar a aplicação; já o método exibeGuiNaPlanilha() é utilizado para exibir a GUI de dentro da planilha, que pode ser após pressionar um botão ou acionando um item de menu. Ao invés de retornar a aplicação, ele executa a função show(). A função elevaAoQuadrado recebe um parâmetro, recupera o valor passado pela interface, faz o cálculo e escreve o resultado em um label. Para que o script tenha acesso aos componentes, é necessário criar callbacks como feito nas linhas abaixo:

var handler = app.createServerClickHandler("elevaAoQuadrado");
app.getElementById("btb_compute").addClickHandler(handler);
handler.addCallbackElement(app.getElementById("Component1"));

Primeiro é criado um ServerClickHandler, que aponta para a função que será executada com o clique do botão; depois o handler é atribuído ao botão (btb_compute foi o ID dado no momento da criação do botão no Interface Builder). Por último, para que o script possa ler e alterar os valores dos componentes, é adicionado um CallBackElement, passando como parâmetro toda a árvore de objetos.

Disponibilização como serviço

É possível compartilhar o script ou disponibilizá-lo como serviço com o comando Share>Publish as a Service. Uma mensagem é exibida informando os tipos de publicação possíveis, por exemplo, acesso apenas ao dono da planilha, qualquer pessoa do domínio ou acesso público via URL. Neste último caso, as alterações feitas pelo script ocorrem como se o dono da planilha as estivesse fazendo, então esse nível de acesso deve ser utilizado com cautela.

Feita a publicação, o serviço pode ser acessado pela URL. E se a opção "Permitir Acesso Anônimo" for selecionada, qualquer pessoa poderá acessar; caso contrário o usuário será redirecionado para a tela de login do Google para informar o usuário e senha de sua conta do Google, para acesso a aplicação. O exemplo está disponível como serviço.

Conclusões e próximos passos

Neste artigo foram mostrados conceitos e passos básicos para criar e executar scripts em aplicações do Google Docs e outros serviços do Google. Vistos os elementos fundamentais, podemos passar a funcionalidades e exemplos mais substanciais. Na segunda parte, será apresentado como adicionar scripts ao Google Sites, criar triggers, interagir com documentos e enviar emails.

Sobre o autor

Alex Eduardo Chiaranda (@aechiara) é Bacharel em Ciência da Computação pela Escola de Engenharia de Piracicaba. Especialista em porte e integração de sistemas nas linguagens C/C++ e Java, já prestou consultoria para órgãos do Governo e empresas como Borland e Ericsson. Apaixonado por games e tecnologia, mantém um blog pessoal sobre tecnologia, filmes e jogos.