Acionadores instaláveis

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 a abertura de um documento. No entanto, os gatilhos instaláveis oferecem mais flexibilidade que os simples: eles podem chamar serviços que exigem autorização, oferecem vários outros tipos de eventos, incluindo gatilhos orientados por 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

Embora os acionadores 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 quando um arquivo é aberto no modo somente leitura (visualização ou comentário). Com scripts independentes, os usuários precisam ter pelo menos acesso de leitura ao arquivo de script para que os acionadores sejam executados corretamente.
  • Execuções de script e solicitações de API não causam a execução de acionadores. Por exemplo, chamar FormResponse.submit() para enviar uma nova resposta de formulário não faz com que o acionador de envio do formulário seja executado.

  • Os acionadores 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 tiver acesso para 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, ele 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 no envio de um e-mail de cada conta.

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

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

Acionadores baseados em tempo

Um gatilho orientado por tempo (também chamado de gatilho de relógio) é semelhante a um cron job no Unix. Os acionadores orientados por tempo permitem que os scripts sejam executados em um momento específico ou em um intervalo recorrente, a cada minuto ou a cada 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 ligeiramente aleatório. Por exemplo, se você criar um acionador recorrente das 9h, o Apps Script escolhe um horário entre 9h e 10h e mantém esse horário consistente de um dia para o outro para que 24 horas se passem antes do acionador novamente.

Confira a seguir o exemplo de um app Google Chat que posta uma mensagem a cada minuto em cada espaço em que o app 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),
  });
}

Gatilhos orientados por eventos

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

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

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

  • Um acionador aberto instalável é executado quando um usuário abre uma planilha, documento ou formulário que ele tem permissão para editar.
  • Um acionador edit instalável é executado quando um usuário modifica um valor em uma planilha.
  • Um acionador de alteração instalável é executado quando um usuário modifica a estrutura da própria planilha, por exemplo, adicionando uma nova página ou removendo uma coluna.
  • Um acionador 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 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 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 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.

Gerenciar acionadores 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 acionador.
  4. Selecione e configure o tipo de gatilho que você quer criar.
  5. Clique em Salvar.

Gerenciar acionadores de maneira programática

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

O exemplo a seguir mostra como criar dois acionadores baseados em tempo, um que é disparado a cada seis horas e outro que é disparado todas as segundas-feiras às 9h (no fuso horário definido para seu 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 aberto instalável para uma planilha. Ao contrário de um acionador onOpen() simples, o script do acionador instalável não precisa estar vinculado à planilha. Para criar esse gatilho com 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 programaticamente um acionador instalável, você precisa excluí-lo e criar um novo. Se você já armazenou o ID de um acionador, ele pode ser excluído passando 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 é disparado, mas a função gera uma exceção ou não é executada com êxito, você não vê uma mensagem de erro na tela. Afinal, quando um acionador baseado em tempo é executado ou outro usuário ativa seu acionador de envio de formulário, você nem está no seu computador.

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

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 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 aqueles 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, à direita dele, clique em Mais > Excluir gatilho.

Acionadores instaláveis em complementos

Para mais informações sobre como usar acionadores instaláveis em complementos, consulte Acionadores de complementos.