Gatilhos instaláveis

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Assim como os acionadores simples, os acionadores instaláveis permitem que o Apps Script execute uma função automaticamente quando ocorre um determinado evento, como abrir um documento. Os gatilhos instaláveis, no entanto, oferecem mais flexibilidade do que os acionadores simples: eles podem chamar serviços que exigem autorização, oferecem vários tipos adicionais de eventos, incluindo acionadores baseados em tempo (relógio), e podem ser controlados de maneira programática. Para acionadores 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

Os gatilhos instaláveis oferecem mais flexibilidade do que os acionadores simples, mas ainda estão sujeitos a várias restrições:

  • Eles não serão executados 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 visualização ao arquivo de script para que os acionadores sejam executados corretamente.
  • Execuções de script e solicitações de API não fazem com que acionadores sejam executados. Por exemplo, chamar FormResponse.submit() para enviar uma nova resposta de formulário não faz com que o gatilho de envio de 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 o colega tiver acesso para editar), mas ele será executado como sua conta. Isso significa que, se você criar um gatilho para enviar um e-mail quando um documento for aberto, esse e-mail será sempre enviado da sua conta, não necessariamente da conta que abriu o documento. No entanto, é possível criar um acionador instalável para cada conta, o que resultaria em um e-mail enviado de cada conta.

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

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

Gatilhos orientados por tempo

Um gatilho com base no tempo (também chamado de gatilho do relógio) é semelhante a um cron job no Unix. Os acionadores com base no tempo permitem que os scripts sejam executados em um momento específico ou em um intervalo recorrente, com uma frequência maior a cada minuto ou com uma frequência menor que uma vez por mês. Observe que um complemento pode usar um acionador com base no tempo uma vez por hora, no máximo. O horário pode ser aleatório, por exemplo, se você criar um gatilho recorrente às 9h, o Apps Script escolherá um horário entre 9h e 10h e manterá esse tempo consistente de um dia para outro, de 24 horas antes do disparo do acionador novamente.

Gatilhos orientados por eventos

Conceitualmente, os gatilhos orientados a eventos são semelhantes aos gatilhos simples, como onOpen(), mas podem responder a outros eventos e se comportam de maneira diferente.

Por exemplo, o acionador de instalação instalável do Planilhas Google é ativado sempre que a planilha é aberta por qualquer usuário que tenha acesso para edição, assim como o acionador onOpen() simples. 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 acionador, mesmo se outro usuário com acesso de edição abrir a planilha.

Há vários gatilhos instaláveis para Google Workspace aplicativos:

  • Um acionador instalável de aberto é executado quando um usuário abre uma planilha, um documento ou um formulário que ele tem permissão para editar.
  • Um acionador de edição instalável é executado quando um usuário modifica um valor em uma planilha.
  • Um acionador 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 acionador instalável de envio de formulário é executado quando um usuário responde a um formulário. Existem duas versões do acionador de envio de formulário: uma para o próprio Formulários Google e uma para o Planilhas se o formulário for enviado para uma planilha.
  • Um acionador de evento da agenda instalável é executado quando um evento da agenda do usuário é atualizado, criado, editado ou excluído.

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

Como gerenciar gatilhos manualmente

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

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

Como gerenciar gatilhos de maneira programática

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

O exemplo a seguir mostra como criar dois acionadores orientados por tempo: um que é disparado a cada seis horas e outro que é acionado a cada segunda-feira às 9h (no fuso horário definido para o script).

trigger/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 aberto instalável para uma planilha. Ao contrário de um gatilho onOpen() simples, o script do acionador instalável não precisa estar vinculado à planilha. Para criar esse gatilho usando um script autônomo, basta substituir SpreadsheetApp.getActive() por uma chamada para SpreadsheetApp.openById(id).

trigger/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 acionador instalável atual de forma programática, é necessário excluí-lo e criar um novo. Se você já armazenou o ID de um gatilho, é possível excluí-lo passando o ID como um argumento para a função abaixo.

trigger/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;
    }
  }
}

Erros em gatilhos

Quando um acionador instalável é disparado, mas a função gera uma exceção ou caso não seja executado com sucesso, você não vê uma mensagem de erro na tela. Afinal, quando um acionador baseado em tempo é executado ou outro usuário ativa o acionador de envio de formulário, talvez você nem esteja no seu computador.

Em vez disso, ele envia um e-mail como o seguinte:

From: 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 Planilhas, do Documentos ou do Formulários Google, o e-mail também incluirá um link para esse arquivo. Esses links permitem desativar o acionador ou editar o script para corrigir o bug.

Para analisar todos os acionadores associados à sua Conta do Google e desativar os acionadores de que você não precisa mais, siga estas etapas:

  1. Acesse script.google.com.
  2. À esquerda, clique em Meus acionadores.
  3. Para excluir um gatilho, à direita dele, clique em Mais > Excluir acionador.

Acionadores instaláveis em complementos

Para mais informações sobre o uso de gatilhos instaláveis em complementos, consulte Acionadores de complemento.