Acionadores instaláveis

Assim como os gatilhos simples, os gatilhos instaláveis permitem que o Apps Script execute uma função automaticamente quando um determinado evento, como abrir um documento, ocorre. No entanto, os gatilhos instaláveis oferecem mais flexibilidade do que os simples: eles podem chamar serviços que exigem autorização, oferecem vários tipos adicionais de eventos, incluindo gatilhos baseados em tempo (relógio), e podem ser controlados de forma programática. Para gatilhos simples e instaláveis, o Apps Script transmite à função acionada um objeto de evento que contém informações sobre o contexto em que o evento ocorreu.

Restrições

Embora os gatilhos instaláveis ofereçam mais flexibilidade do que os simples, eles ainda estão sujeitos a várias restrições:

  • Elas não são executadas se um arquivo for aberto no modo somente leitura (visualização ou comentário). Para scripts independentes, os usuários precisam ter pelo menos acesso de leitura ao arquivo de script para que os gatilhos sejam executados corretamente.

  • As execuções de scripts e as solicitações de API não fazem com que os acionadores sejam executados. Por exemplo, chamar FormResponse.submit() para enviar uma nova resposta do formulário não faz com que o gatilho de envio do formulário seja executado.

  • Os gatilhos instaláveis sempre são executados na conta da pessoa que os criou. Por exemplo, se você criar um gatilho aberto instalável, ele será executado quando seu colega abrir o documento (se ele tiver acesso de edição), mas será executado como sua conta. Isso significa que, se você criar um gatilho para enviar um e-mail quando um documento for aberto, a mensagem será sempre enviada da sua conta, não necessariamente da conta que abriu o documento. No entanto, você pode criar um gatilho instalável para cada conta, o que resultaria em um e-mail enviado de cada uma delas.

  • Uma conta não pode ver os acionadores instalados de outra conta, mesmo que a primeira ainda possa ativá-los.

  • Os gatilhos instaláveis estão sujeitos aos limites de cota de gatilho do Apps Script.

Gatilhos baseados em tempo

Um gatilho baseado em tempo (também chamado de gatilho de relógio) é semelhante a um cron job no Unix. Os gatilhos baseados em tempo permitem que scripts sejam executados em um horário específico ou em um intervalo recorrente, com frequência de uma vez por minuto ou uma vez por mês. Um complemento pode usar um gatilho baseado em tempo uma vez por hora no máximo. O horário pode ser um pouco aleatório. Por exemplo, se você criar um gatilho recorrente às 9h, o Apps Script vai escolher um horário entre 9h e 10h e manter essa consistência de dia para dia para que 24 horas se passem antes que o gatilho seja acionado novamente.

Gatilhos baseados em eventos

Os gatilhos instaláveis orientados a eventos são conceitualmente semelhantes aos gatilhos simples como onOpen(), mas podem responder a outros eventos e se comportam de maneira diferente.

Por exemplo, o acionador de abertura instalável das Planilhas Google é ativado sempre que a planilha é aberta por um usuário com acesso de edição, assim como o acionador simples onOpen(). No entanto, a versão instalável pode chamar serviços que exigem autorização. A versão instalável é executada com a autorização do usuário que criou o gatilho, mesmo que outro usuário com acesso de edição abra a planilha.

Há vários acionadores instaláveis para aplicativosGoogle Workspace :

  • Um gatilho open instalável é executado quando um usuário abre uma planilha, documento ou formulário que ele tem permissão para editar.
  • Um gatilho edit instalável é executado quando um usuário modifica um valor em uma planilha.
  • Um gatilho de mudança instalável é executado quando um usuário modifica a estrutura de uma planilha, por exemplo, adicionando uma nova página ou removendo uma coluna.
  • Um gatilho de envio de formulário instalável é executado quando um usuário responde a um formulário. Há duas versões do acionador de envio de formulário: uma para os Formulários Google e outra para as Planilhas Google, caso o formulário seja enviado para uma planilha.
  • Um gatilho de evento da agenda instalável é executado quando os eventos da agenda de um usuário são atualizados (criados, editados ou excluídos).

É possível usar gatilhos instaláveis em scripts independentes e vinculados. Por exemplo, um script independente pode criar programaticamente um gatilho instalável para um arquivo arbitrário do Planilhas Google chamando TriggerBuilder.forSpreadsheet(key) e transmitindo o ID da planilha.

Gerenciar gatilhos manualmente

Para criar manualmente um gatilho instalável no editor de script, siga estas etapas:

  1. Abra seu projeto do Apps Script.
  2. À esquerda, clique em Acionadores .
  3. No canto inferior direito, clique em Adicionar gatilho.
  4. Selecione e configure o tipo de gatilho que você quer criar.
  5. Clique em Salvar.

Gerenciar gatilhos de maneira programática

Também é possível criar e excluir acionadores de maneira programática com o serviço de script. Comece chamando ScriptApp.newTrigger(functionName), que retorna um TriggerBuilder.

O exemplo a seguir mostra como criar dois gatilhos acionados por tempo: um que é disparado a cada 6 horas e outro que é disparado todas as segundas-feiras às 9h (no fuso horário em que o script está definido).

triggers/triggers.gs
/**
 * Creates two time-driven triggers.
 * @see https://developers.google.com/apps-script/guides/triggers/installable#time-driven_triggers
 */
function createTimeDrivenTriggers() {
  // Trigger every 6 hours.
  ScriptApp.newTrigger('myFunction')
      .timeBased()
      .everyHours(6)
      .create();
  // Trigger every Monday at 09:00.
  ScriptApp.newTrigger('myFunction')
      .timeBased()
      .onWeekDay(ScriptApp.WeekDay.MONDAY)
      .atHour(9)
      .create();
}

O próximo exemplo mostra como criar um gatilho de abertura instalável para uma planilha. Ao contrário de um gatilho onOpen() simples, o script do gatilho instalável não precisa estar vinculado à planilha. Para criar esse gatilho em um script independente, basta substituir SpreadsheetApp.getActive() por uma chamada para SpreadsheetApp.openById(id).

triggers/triggers.gs
/**
 * Creates a trigger for when a spreadsheet opens.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function createSpreadsheetOpenTrigger() {
  const ss = SpreadsheetApp.getActive();
  ScriptApp.newTrigger('myFunction')
      .forSpreadsheet(ss)
      .onOpen()
      .create();
}

Para modificar um gatilho instalável de forma programática, é necessário excluí-lo e criar um novo. Se você já tiver armazenado o ID de um gatilho, poderá excluí-lo transmitindo o ID como um argumento para a função abaixo.

triggers/triggers.gs
/**
 * Deletes a trigger.
 * @param {string} triggerId The Trigger ID.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function deleteTrigger(triggerId) {
  // Loop over all triggers.
  const allTriggers = ScriptApp.getProjectTriggers();
  for (let index = 0; index < allTriggers.length; index++) {
    // If the current trigger is the correct one, delete it.
    if (allTriggers[index].getUniqueId() === triggerId) {
      ScriptApp.deleteTrigger(allTriggers[index]);
      break;
    }
  }
}

Antes de criar um gatilho, recomendamos que você verifique se a função associada tem todas as permissões do OAuth necessárias.

Erros em acionadores

Quando um gatilho instalável é acionado, mas a função gera uma exceção ou não é executada corretamente, nenhuma mensagem de erro aparece na tela. Afinal, quando um gatilho baseado em tempo é executado ou outro usuário ativa seu gatilho de envio de formulário, você pode nem estar no computador.

Em vez disso, o Apps Script envia um e-mail como este:

From: noreply-apps-scripts-notifications@google.com
Subject: Summary of failures for Google Apps Script
Your script has recently failed to finish successfully.
A summary of the failure(s) is shown below.

O e-mail inclui um link para desativar ou reconfigurar o gatilho. Se o script estiver vinculado a um arquivo do Google Planilhas, Documentos ou Formulários, o e-mail também vai incluir um link para esse arquivo. Com eles, você pode desativar o gatilho ou editar o script para corrigir o bug.

Para analisar todos os gatilhos associados à sua Conta do Google e desativar os que não são mais necessários, siga estas etapas:

  1. Acesse script.google.com.
  2. À esquerda, clique em Meus acionadores.

  3. Para excluir um gatilho, clique em Mais > Excluir gatilho à direita dele.

Gatilhos em complementos

Além dos acionadores instaláveis, você pode usar acionadores de manifesto em complementos. Para mais informações, consulte Acionadores para complementos do Google Workspace.