Acionadores instaláveis

Assim como os gatilhos simples, os instaláveis permitem que o Apps Script execute uma função automaticamente quando um determinado evento, como a abertura de um documento, ocorre. No entanto, os acionáveis oferecem mais flexibilidade do que os simples: eles podem chamar serviços que exigem autorização, oferecem vários outros tipos de eventos, incluindo gatilhos por tempo (relógio), e podem ser controlados programaticamente. 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 do script para que os acionadores sejam executados corretamente.

  • As execuções de script 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 de formulário não faz com que o gatilho de envio do formulário seja executado.

  • Os gatilhos instaláveis são sempre executados na conta da pessoa que os criou. Por exemplo, se você criar um gatilho de abertura 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 acionador para enviar um e-mail quando um documento for aberto, o e-mail será sempre enviado da sua conta, não necessariamente da conta que abriu o documento. No entanto, você pode criar um acionador instalável para cada conta, o que resultaria em um e-mail enviado de cada conta.

  • Uma conta não pode ver os acionadores instalados em uma segunda conta, mesmo que a primeira ainda possa ativar esses acionadores.

  • Os gatilhos instaláveis estão sujeitos aos limites de cota do acionador 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 acionadores baseados em tempo permitem que os scripts sejam executados em um horário específico ou em um intervalo recorrente, com a frequência de um minuto ou uma vez por mês. Um complemento pode usar um acionador 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 acionador recorrente às 9h, o Apps Script vai escolher um horário entre 9h e 10h e manter esse tempo consistente de um dia para o outro, de modo que 24 horas se passem antes que o acionador seja acionado novamente.

Confira abaixo um exemplo de um app do Google Chat que envia uma mensagem a cada minuto para todos os espaços em que está:

// Example app for Google Chat that demonstrates app-initiated messages
// by spamming the user every minute.
//
// This app makes use of the Apps Script OAuth2 library at:
//     https://github.com/googlesamples/apps-script-oauth2
//
// Follow the instructions there to add the library to your script.

// When added to a space, we store the space's ID in ScriptProperties.
function onAddToSpace(e) {
  PropertiesService.getScriptProperties()
      .setProperty(e.space.name, '');
  return {
    'text': 'Hi! I\'ll post a message here every minute. ' +
            'Please remove me after testing or I\'ll keep spamming you!'
  };
}

// When removed from a space, we remove the space's ID from ScriptProperties.
function onRemoveFromSpace(e) {
  PropertiesService.getScriptProperties()
      .deleteProperty(e.space.name);
}

// Add a trigger that invokes this function every minute in the
// "Edit > Current Project's Triggers" menu. When it runs, it
// posts in each space the app was added to.
function onTrigger() {
  var spaceIds = PropertiesService.getScriptProperties()
      .getKeys();
  var message = { 'text': 'Hi! It\'s now ' + (new Date()) };
  for (var i = 0; i < spaceIds.length; ++i) {
    postMessage(spaceIds[i], message);
  }
}
var SCOPE = 'https://www.googleapis.com/auth/chat.bot';
// The values below are copied from the JSON file downloaded upon
// service account creation.
// For SERVICE_ACCOUNT_PRIVATE_KEY, remember to include the BEGIN and END lines
// of the private key
var SERVICE_ACCOUNT_PRIVATE_KEY = '...';
var SERVICE_ACCOUNT_EMAIL = 'service-account@project-id.iam.gserviceaccount.com';

// Posts a message into the given space ID via the API, using
// service account authentication.
function postMessage(spaceId, message) {
  var service = OAuth2.createService('chat')
      .setTokenUrl('https://accounts.google.com/o/oauth2/token')
      .setPrivateKey(SERVICE_ACCOUNT_PRIVATE_KEY)
      .setClientId(SERVICE_ACCOUNT_EMAIL)
      .setPropertyStore(PropertiesService.getUserProperties())
      .setScope(SCOPE);
  if (!service.hasAccess()) {
    Logger.log('Authentication error: %s', service.getLastError());
    return;
  }
  var url = 'https://chat.googleapis.com/v1/' + spaceId + '/messages';
  UrlFetchApp.fetch(url, {
    method: 'post',
    headers: { 'Authorization': 'Bearer ' + service.getAccessToken() },
    contentType: 'application/json',
    payload: JSON.stringify(message),
  });
}

Acionadores orientados a 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 comportar de maneira diferente.

Por exemplo, o acionador de abertura instalável para as Planilhas Google é ativado sempre que a planilha é aberta por qualquer usuário que tenha acesso de 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 que outro usuário com acesso de edição abra a planilha.

Há vários acionadores instaláveis para aplicativos :

  • Um acionador open instalável é executado quando um usuário abre uma planilha, um documento ou um formulário que tem permissão para editar.
  • Um acionador editar 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 planilha ou removendo uma coluna.
  • Um gatilho instalável de envio de formulário é executado quando um usuário responde a um formulário. Há duas versões do acionador de envio de formulários: uma para o Google Forms e outra para as Planilhas Google, se o formulário for enviado para uma planilha.
  • Um acionador 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 um acionador instalável para um arquivo arbitrário das 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 acionador 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 baseados em tempo: um que é acionado a cada 6 horas e outro que é acionado todas as segundas-feiras às 9h (no fuso horário definido para o script).

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 acionador onOpen() simples, o script do acionador instalável não precisa ser vinculado à planilha. Para criar esse acionador 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, exclua-o e crie um novo. Se você armazenou o ID de um gatilho, é possível 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;
    }
  }
}

Erros em acionadores

Quando um acionador instalável é acionado, mas a função gera uma exceção ou não é executada, não aparece 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 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 acionador. Se o script estiver vinculado a um arquivo do Google Planilhas, Documentos ou Formulários, o e-mail também incluirá um link para esse arquivo. Esses links permitem que você desative o acionador ou edite o script para corrigir o bug.

Para analisar todos os acionadores 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 acionador, clique em Mais > Excluir acionador.

Acionadores em complementos

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