Google Apps Script, Parte 2: Google Docs, triggers e envio de emails

Este artigo continua e completa uma introdução à automação de serviços do Google com o Google Apps Script. Na primeira parte foram mostrados conceitos e passos básicos para criar e executar scripts em documentos do Google Docs e outros serviços. Tendo apresentado os elementos básicas, podemos passar a funcionalidades e exemplos mais substanciais. Aqui mostramos como adicionar menus a planilhas, criar triggers, interagir com documentos e enviar emails baseados em templates.

Menus e triggers

Na primeira parte, vimos como executar scripts criando uma interface gráfica ou diretamente de dentro do editor. Outra forma de executar scripts é criando um item de menu personalizado e adicionando-o à planilha. Para isso, é preciso criar uma nova função no script (ou alterá-la caso já exista) chamada onOpen, que será executada todas as vezes que a planilha for aberta.

Para inserir um item de menu no primeiro exemplo da primeira parte (que buscava as datas de um calendário específico e preenchia uma planilha), o código é o seguinte:

function onOpen() {
  // recupera a planilha ativa
  var ss = SpreadsheetApp.getActiveSpreadsheet();
  // cria um array com 2 itens que serão os itens do menu
  // cada item deve apontar para uma função, que será chamada quando o item de menu for clicado
  var menuEntries = [ {name: "Load", functionName: "menuItem1"},
                      {name: "Show Message", functionName: "menuItem2"} ];

  // adiciona o menu com o nome "Load Calendar"
  ss.addMenu("Load Calendar", menuEntries);
}

// função que será executada quando clicar no item 'Load'
function menuItem1() {
  // chama função principal do script
  myFunction();
}

// função que será executada quando clicar no item 'Show Message'
function menuItem2() {
  // exibe um alerta
  Browser.msgBox("Surprise! Surprise!")
}

Após adicionar essas três novas funções, é necessário salvar o script e a planilha, e fechar e abrir a planilha novamente. Após a planilha ser totalmente carregada, o menu irá aparecer como na imagem abaixo. Agora basta clicar nas opções disponíveis para executar o script.

Para adicionar o menu, foi utilizado um trigger que é executado automaticamente no momento que a planilha é aberta. Esses triggers são ações executadas em resposta a algum evento, como por exemplo abrir uma planilha, enviar um formulário, ou quando um horário específico é atingido. O Google Apps Script possui dois tipos de triggers: Simple Event Handler e Installable Event Handler.

Os Simple Event Handlers são definidos pela equipe do Google Apps Script, e podem ser utilizados apenas criando uma função no script para o evento pré-existente. São eles: onOpen, onInstall e onEdit. Quando presentes no script, esses triggers serão executados de acordo com o evento correspondente, respeitando as permissões do usuário que abriu a planilha. Por isso, têm algumas restrições:

• Não são capazes de determinar qual usuário está editando a planilha;
• Não podem acessar nenhum serviço que precise de autenticação. Por exemplo, o serviço do Google Translate é anônimo e pode ser acessado; porém o Calendar, GMail e Google Sites exigem login, portanto não estão acessíveis aos Simple Event Handlers;
• A planilha que contém o script deve estar aberta para edição;
• Os Simple Event Handlers só podem modificar a planilha atual; o acesso a outras planilhas é proibido.

Os Installable Event Handlers são parecidos com os Simple Event Handlers e podem ser usados com os seguintes eventos:

• Em uma data específica, podendo-se escolher dia, mês, ano, hora, minutos e segundos;
• Quando um formulário é submetido;
• Quando uma planilha é editada. Mas, diferentemente do evento onEdit (por exemplo), um Installable Event Handler vai ser executado com as permissões do usuário que criou o trigger;
• Quando a planilha é aberta, também com as permissões do usuário criador do trigger.

Os Installable Event Handlers têm algumas diferenças importantes em relação aos Simple Event Handlers:

• Rodam com as permissões do usuário que criou o trigger, não como o usuário que disparou o evento;
• Podem acessar praticamente qualquer serviço disponível ao usuário que criou o trigger;
• Não possuem qualquer limitação de acesso dos Simple Event Handlers;
• Podem não ser capazes de determinar o usuário que disparou um evento (no caso de um evento disparado por uma data, por exemplo); mas em um evento que altera o documento, o usuário que está alterando o documento às vezes não pode ser identificado;
• O documento que contém o script não precisa estar aberto para que o evento seja disparado e o script, executado.

Um trigger (de qualquer tipo) pode ser associado a várias funções, e uma função pode ser chamada por vários triggers. Lembrando que, por razões de segurança, quando um script é executado através de um trigger, ele é executado usando as credenciais de quem instalou o trigger, não as credenciais de quem disparou o evento.

Por exemplo, se um usuário (digamos, usuário_1) criar um trigger na planilha 1 e um outro usuário (usuário_2) ao editar a planilha, disparar um trigger, o script associado a esse trigger será executado utilizando as credenciais e as permissões do usuário_1 que foi o criador da planilha.

Por isso, uma janela de autorização pode ser exibida no momento da instalação de um script, alertando quais serviços serão utilizados pelo script.

GMail e envio de emails

Com a API de acesso ao GMail, é possível realizar buscas e manipular as mensagens e threads do GMail. A sintaxe da busca é idêntica à que é suportada utilizando a própria página do GMail. Para recuperar em uma variável todas as mensagens da caixa de entrada (Inbox) que ainda não foram lidas, pode-se utilizar o seguinte trecho de código:

var threads = GmailApp.search('in:inbox is:unread');

O envio de emails também é simples. É possível, inclusive, anexar arquivos; para isso é necessário saber o ID do arquivo que será anexado. Existe um limite (quota) de mensagens que podem ser enviadas para endereços distintos, por dia. Portanto é uma boa prática verificar esse limite diário antes de enviar novos emails (no momento de escrita, o limite era de 500 mensagens).

Veja abaixo um exemplo de como verificar o limite de envio diário e enviar um email:

// verifica a quota de mensagens
var emailDailyQuota = MailApp.getRemainingDailyQuota();
if ( 0 < emailDailyQuota ) {
    MailApp.sendEmail(emailAddress, subject, message);
}

A sintaxe da função sendEmail suporta ainda um quarto parâmetro, chamado Advanced Args, que na verdade é um array de argumentos, dando suporte às opções bcc, cc, htmlBody, name, noReply, replyTo, attachments, inlineImages. Abaixo, veja um exemplo que utiliza algumas dessas funções:

function testeSendEmail() {
  // cria um array com um arquivo HTML que será enviado como anexo, é obrigatório informar um nome e o conteúdo do arquivo
  var meusArquivos = [{fileName:"meu_documento.html", content:"<html><body><center><strong>Google App Script - HTML EMAIL</strong></center></body></html>"}];

  // envia o email para o destinatário no primeiro parâmetro, com assunto no segundo, corpo no terceiro e arquivo(s) no último parâmetro
  MailApp.sendEmail("xxxxx@gmail.com", "Enviando arquivo Atachado", "Segue arquivo anexo", {attachments: meusArquivos});
}

function inlineImage() {
  // busca imagens da internet
  var googleLogoBlob = UrlFetchApp.fetch("http://www.google.com/intl/en_com/images/srpr/logo3w.png").getBlob().setName("googleLogoBlob");
  var youtTubeLogoBlob = UrlFetchApp.fetch("http://s.ytimg.com/yt/img/logos/youtube_logo_standard_againstwhite-vflKoO81_.png").getBlob().setName("youtTubeLogoBlob");

  // cria um htmlBody, anexa as imagens ao html e envia o email
  MailApp.sendEmail("xxxxx@gmail.com", "Logos", "", {
  htmlBody:
     "inline Google Logo<img src='cid:googleLogo'> imagens! <br/> inline YouTube Logo <img src='cid:youTubeLogo'>",
      inlineImages: {
        googleLogo: googleLogoBlob,
   	youTubeLogo:youtTubeLogoBlob
      }
   }
   );
}

Ainda é possível, como descrito na primeira parte, utilizar elementos de uma planilha (buscar os endereços de email por exemplo), ou ainda buscar elementos da internet (utilizando um serviço da Google API, ou ainda um Web Service).

Veja a seguir um exemplo de como utilizar um documento como template, onde uma variável NOME será substituída por um dado (que pode ser recuperado de qualquer fonte disponível, seja ela uma planilha, web service etc.). O documento será convertido para PDF e então enviado por email como anexo.

function sendEmailTemplate() {
  // ID do documento no Google Docs
  var templateId = "xxxxxxxxxxxxxxxxxxxx"
  var tempDoc = "teste_template";

  // informações do remetente e destinatario fixas para este exemplo, mas poderia ser recuperado de uma planilha por exemplo
  var nome_completo = "Alex Eduardo Chiaranda";
  var destinatario = "xxxxx@gmail.com";
  var subject = "envio pdf";
  var body = "Segue anexo arquivo solicitado";
  var remetente = "Artigo InfoQ GOOGLE APP SCRIPT <google_app_script@google.com>";

  // Cria um documento temporário, recupera o ID e o abre
  var idCopia = DocsList.getFileById(templateId).makeCopy(tempDoc + '_para_' + nome_completo).getId();
  var docCopia = DocumentApp.openById(idCopia);

  // recupera o corpo do documento
  var bodyCopia = docCopia.getActiveSection();

  // faz o replace das variáveis do template, salva e fecha o documento temporario
  bodyCopia.replaceText("NOME", nome_completo);
  docCopia.saveAndClose();

  // abre o documento temporario como PDF utilizando o seu ID
  var pdf = DocsList.getFileById(idCopia).getAs("application/pdf");

  // envia o email
  MailApp.sendEmail(destinatario, subject, body, {name: remetente, attachments: pdf});

  // apaga o documento temporário
  DocsList.getFileById(idCopia).setTrashed(true);  
}

O template ficou assim:

Após executar o script, o email é enviado:

A mensagem possui o arquivo anexado:

E no arquivo anexado a variável NOME foi substituída, como esperado.

Conclusões e próximos passos

Neste artigo vimos como criar triggers e menus para planilhas, manipular os documentos armazenados no Google Docs para criar templates, converter documentos e enviar emails.

Muito mais pode ser feito utilizando as APIs que o Google disponibiliza gratuitamente para todos os usuários e empresas que utilizam sua plataforma. Um bom lugar para explora além do que vimos é o site do Google Apps Script onde é possível encontrar tutoriais, a documentação da API e até um fórum para tirar dúvidas.

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 jogos e tecnologia, mantém um blog pessoal sobre tecnologia, filmes e jogos.