Acionadores no Apps Script: Guia completo

Automatizar tarefas é para todos e traz um potencial muito recompensador não só para o seu trabalho, mas também para a sua carreira. Quem trabalha com planilhas no Google Sheets pode usar o Apps Script para criar automações que eliminem todo aquele trabalho repetitivo – como enviar e-mail para clientes toda vez que o pagamento vence.

Uma etapa tão importante quanto desenvolver os scripts é agendar a execução das tarefas com os acionadores ou triggers do Apps Script, que é com o que vamos te ajudar nesse passo a passo.

• Apps Script: O que é e como funciona o VBA do Google Sheets

O que são acionadores no Google Apps Script?

No menu lateral do Apps Script, existe um ícone de relógio com o nome Acionadores, que são eventos que vão executar seus scripts de forma 100% automática. Pense nos acionadores como o alarme do seu celular, só que ao invés de te acordar às 03h para fazer um trabalho, o Apps Script fará tudo por você.

Esses eventos de acionamento podem ser úteis para:

• enviar um e-mail quando alguém responde o seu formulário no Google Forms.
• atualizar uma planilha todos os dias às 8 da manhã.
• notificar um colega de trabalho quando uma edição for feita no Google Sheets.
• importar dados .csv de um site automaticamente.

Os acionadores serão sempre úteis quando você quiser automatizar uma tarefa, sem precisar executar um script manualmente – o que otimizará seu trabalho, aumentará sua produtividade e, muito provavelmente, proporcionará progressões na sua carreira.

Tipos de acionadores no Apps Script

Basicamente, existem dois tipos:

Acionadores Simples

Esses são configurados diretamente no script e farão com que o seu código seja executado toda vez que tal evento ocorrer. Alguns desses eventos são:

• onOpen(e): fará com que o seu código seja executado toda vez que a planilha ou formulário forem abertos.
• onEdit(e): quando uma célula da planilha for editada, o script será executado.

Os dois eventos acima são os mais comuns, mas você pode conferir outros na documentação do GAS. Mais abaixo vamos mostrar um exemplo com o evento onOpen().

Acionadores Instaláveis

Os instaláveis são os quais são configurados dentro da página Acionadores do menu lateral. Esses oferecem maior flexibilidade, já que permitem automatizações mais robustas, como:

• Baseado no tempo: executar scripts em intervalos diários, semanais, mensais, em data e hora específicos, a cada hora ou minuto, a cada dia da semana, no 1º dia de cada mês, etc.
• Envio de formulário: quando uma resposta for enviada no Google Forms.

Os acionadores instaláveis ficam localizados em: Apps Script em Editor > Acionadores > Adicionar acionador.

Como configurar um acionador no Apps Script?

Para utilizar um acionador simples, basta implementá-lo diretamente no código do seu script, como esse exemplo abaixo:

function onOpen() {
    SpreadsheetApp.getUi().alert("Bem-vindo à planilha!");
}

Ao abrir a planilha, será emitido um alerta visual com os dizeres: Bem-vindo à planilha!

Esse é um exemplo muito simples, mas o seu script poderia executar infinitas outras ações.

Nós temos uma publicação aqui no blog onde falamos especificamente sobre automatizar envio de e-mail para clientes quando o pagamento está atrasado – que é um exemplo real de uso dos acionadores instaláveis.

Nessa automação dos e-mails, nós criamos a função enviarEmails() e para não precisar executar manualmente, podemos usar um acionador instalável baseado no tempo:

1. Clique no ícone do relógio no menu lateral > Acionadores
2. Agora clique no botão + Adicionar acionador

Como nossa função enviarEmails() foi preparada para não fazer nada quando uma condição não for atendida, podemos fazer com que ela seja executada diariamente.

Como pode verificar na demonstração acima, configuramos para a função enviarEmails ser executada todos os dias entre 7 a 8h da manhã. Lembre-se de manter a configuração correta do fuso horário; no nosso caso, GMT-3. Você pode alterar isso no ícone de engrenagem do Apps Script, em configurações do projeto.

Outro ponto importante são as notificações de falha, eu gosto sempre de manter a notificação imediata quando uma falha ocorre. Com isso, quando uma automação passar por algum erro, sou notificado imediatamente por e-mail.

Casos de uso mais comuns

É bem provável que você utilizará muito mais os acionadores instaláveis baseados no tempo. Então, é preciso considerar que, por exemplo, quando você precisa que uma automação seja executada diariamente, ao configurar a execução para o intervalo das 7h às 8h, ela não ocorrerá em um horário exato.

A execução se dará entre esses horários, embora geralmente execute logo no início da primeira hora definida (7 da manhã nesse caso).

Outra possibilidade é ter uma automação que ao ser executada precise que um novo gatilho seja definido. Isso é completamente possível, pois o Apps Script permite que novos acionadores sejam criados diretamente no código.

Por exemplo: suponha que você tenha uma função relatorioDiario() que execute todos os dias entre 7-8h da manhã e quando determinada condição é atendida, uma outra função notificarSlack() para enviar uma mensagem no Slack tenha que ser executada exatamente às 9h desse mesmo dia.

Você terá que adaptar o seu script para executar a criação de um novo acionador, como no exemplo abaixo:

function criarNovoAcionador() {
  var executeAs = new Date();
  executeAs.setHours(9, 0, 0, 0); // Define o horário para 9h do mesmo dia

  ScriptApp.newTrigger('notificarSlack')
    .timeBased()
    .at(executeAs)
    .create();
}

Ao integrar esse script a sua automação, um acionador baseado em tempo, com data e hora fixas, será criado:

Após esse acionador ser ativado e executado, ele ficará como expirado e não executará nunca mais.

Dicas importantes para acionadores do Apps Script

1. Monitore a taxa de erro das suas funções: além da notificação por e-mail quando um erro ocorre, você pode conferir a taxa de erro das suas automações no Editor > Acionadores.
2. Autorizações: antes de agendar um acionador, sempre execute sua automação manualmente para garantir que todas as permissões e autorizações já tenham sido concedidas.
3. Limites de uso: evite excessos de execuções, use os acionadores com sabedoria. A Google impõe limites de uso para contas pessoais e profissionais no uso do Apps Script. Existem limites de execuções simultâneas, de projetos criados no dia, envios de e-mail, entre outros.
4. Faça testes: simule diversas ocorrências com suas automações, só assim você garantirá que suas automações se tornem perenes, funcionem por muito tempo e não dependam de manutenções constantes.

Esperamos que tenha gostado. Os acionadores do Apps Script são um passo importante e uma excelente maneira de automatizar tarefas repetitivas, seja no envio de e-mails, consumir uma API REST ou simplesmente para todos os dias aplicar determinada fórmula em uma planilha.

Se você está começando a se aventurar no Apps Script agora, nosso blog conta com diversas publicações sobre essa ferramenta superpoderosa. Indicamos ainda que você aprenda o básico de JavaScript, que é a linguagem usada no GAS.

Caso tenha ficado com alguma dúvida, use a seção de comentários abaixo e participe da Comunidados, nosso grupo 100% gratuito no WhatsApp.