Gatilhos para complementos do Editor

Os acionadores do Apps Script fazem com que uma função de script especificada (a função de gatilho) seja executada sempre que ocorrer um evento especificado. Apenas determinados eventos podem disparar gatilhos, e cada aplicativo do Google Workspace é compatível com um conjunto diferente de eventos.

Quando um acionador é disparado, um objeto de evento é criado. Essa estrutura JSON contém detalhes sobre o evento que ocorreu. As informações na estrutura do objeto de evento são organizadas de maneira diferente com base no tipo de acionador.

Depois que o objeto de evento é criado, o Apps Script o transmite como um parâmetro para a função de acionamento. A função de gatilho é uma função de callback que você precisa implementar por conta própria para realizar as ações apropriadas para responder ao evento. Por exemplo, em um complemento do Editor, um acionador é usado para criar itens de menu do complemento quando um documento é aberto. Nesse caso, implemente na função de gatilho onOpen(e) para criar os itens de menu de que o complemento precisa, possivelmente usando os dados no objeto de evento.

Nesta página, fornecemos diretrizes sobre o uso de gatilhos em projetos complementares do editor.

Tipos de acionadores de complementos do editor

É possível usar a maioria dos tipos genéricos de gatilhos disponíveis para projetos do Apps Script nos complementos do Editor, incluindo acionadores simples e a maioria dos gatilhos instaláveis. O conjunto exato de tipos de gatilho disponíveis depende do aplicativo que está sendo estendido.

A tabela a seguir mostra os tipos de gatilhos simples e instaláveis que os complementos do Editor podem usar, além de fornecer links para os objetos de evento correspondentes:

Evento	Objeto de evento	Acionadores simples	Acionadores instaláveis
Abrir Um arquivo de editor será aberto.	Objeto de evento onOpen do Documentos Objeto de evento onOpen Objeto de evento onOpen das Planilhas Objeto de evento onOpen das Apresentações	Documentos Formulários* Planilhas Apresentações function onOpen(e)	Documentos Formulários Planilhas
Instalar O complemento está instalado.	Objeto de evento onInstall	Documentos Formulários Planilhas Apresentações function onInstall(e)
Editar O conteúdo da célula da planilha foi alterado.	Objeto de evento onEdit das Planilhas	Planilhas function onEdit(e)	Planilhas
Alteração O conteúdo de uma página é editado ou formatado.	Objeto de evento onChange das Planilhas		Planilhas
Envio de formulário Um arquivo do Formulários Google é enviado.	Objeto de evento de envio de formulário Objeto de evento de envio de formulário do Planilhas		Formulários Planilhas
Baseado em tempo (relógio) O acionador é disparado em um horário ou intervalo especificado.	Objeto de evento orientado por tempo		Documentos Formulários Planilhas Apresentações

* O evento de abertura do Formulários Google não ocorre quando um usuário abre um formulário para responder, mas quando um editor abre o formulário para modificá-lo.

Gatilhos simples em complementos

Acionadores simples usam um conjunto de nomes de função reservados, não podem usar serviços que exigem autorização e são ativados automaticamente para uso. Em alguns casos, um evento acionador simples pode ser processado por um acionador instalável.

É possível adicionar um gatilho simples a um complemento simplesmente implementando uma função com um dos seguintes nomes reservados:

• onOpen(e) é executado quando um usuário abre um documento, uma planilha ou uma apresentação. onOpen(e) também pode ser executado quando um formulário é aberto no editor, mas não ao responder ao formulário. Essa função só é executada se o usuário tem permissão para editar o arquivo em questão e é usada com mais frequência para criar itens de menu.
• onInstall(e) é executado quando um usuário instala um complemento. Normalmente, onInstall(e) é usado apenas para chamar onOpen(e). Isso garante que os menus de complementos apareçam imediatamente após a instalação, sem exigir que o usuário atualize a página.
• onEdit(e) é executado quando um usuário muda o valor de uma célula em uma planilha. Este acionador não é disparado em resposta a movimentos de células, formatação ou outras mudanças que não alteram os valores das células.

Restrições

Gatilhos simples em complementos estão sujeitos às mesmas restrições que regem acionadores simples em outros tipos de projetos do Apps Script. Observe com atenção essas restrições ao criar complementos:

• Gatilhos simples não serão executados se um arquivo for aberto no modo somente leitura (visualização ou comentário). Esse comportamento impede que os menus de complementos sejam preenchidos.
• Em determinadas circunstâncias, os complementos do Editor executam os gatilhos simples onOpen(e) e onEdit(e) no modo sem autorização. Esse modo apresenta algumas outras complicações, conforme descrito no modelo de autorização de complementos.
• Gatilhos simples não podem usar serviços nem realizar outras ações que exigem autorização, exceto conforme descrito no modelo de autorização de complementos.
• Gatilhos simples não podem ser executados por mais de 30 segundos. Tenha cuidado para minimizar a quantidade de processamento feito em uma função de gatilho simples.
• Gatilhos simples estão sujeitos aos limites de cota de acionadores do Apps Script.

Acionadores instaláveis em complementos

Os complementos podem criar e modificar de maneira programática gatilhos instaláveis com o serviço Script do Apps Script. Não é possível criar manualmente os gatilhos instaláveis dos complementos. Ao contrário de gatilhos simples, os gatilhos instaláveis podem usar serviços que exigem autorização.

Os acionadores instaláveis em complementos não enviam e-mails de erro ao usuário quando encontram erros, já que, na maioria dos casos, o usuário não consegue resolver o problema. Por isso, crie seu complemento para lidar com erros em nome do usuário sempre que possível.

Os complementos podem usar os seguintes gatilhos instaláveis:

• Os acionadores instaláveis Abrir são executados quando um usuário abre um documento ou uma planilha ou quando um formulário é aberto no editor (mas não ao responder ao formulário).
• Os acionadores instaláveis Editar são executados quando um usuário altera um valor de célula em uma planilha. Esse acionador não é disparado em resposta à formatação ou a outras mudanças que não alteram os valores da célula.
• Os acionadores instaláveis de mudança são executados quando um usuário faz qualquer alteração em uma planilha, incluindo edições de formatação e modificações na própria planilha (como adicionar uma linha).

• Os acionadores instaláveis do Form-submit são executados quando uma resposta do Formulários Google é enviada.

• Gatilhos baseados em tempo (também chamados de gatilhos do relógio) são disparados em um horário específico ou repetidamente em um intervalo de tempo regular.

Como autorizar acionadores instaláveis

Normalmente, quando um desenvolvedor atualiza um complemento para usar novos serviços que exigem autorização extra, os usuários precisam autorizar o complemento novamente na próxima vez que o utilizarem.

No entanto, os complementos que usam acionadores enfrentam desafios de autorização especiais. Imagine um complemento que use um acionador para monitorar o envio de formulários: um criador de formulários autoriza o uso do complemento na primeira vez que ele é usado e o deixa em execução por meses ou anos, sem precisar reabrir o formulário. Se o desenvolvedor do complemento atualizar o complemento para usar novos serviços que exigem autorização extra, o criador do formulário nunca verá a caixa de diálogo de nova autorização, porque o formulário não foi reaberto, e o complemento parará de funcionar.

Ao contrário dos acionadores em projetos regulares do Apps Script, os acionadores em complementos continuam sendo disparados mesmo que precisem de uma nova autorização. No entanto, o script ainda falhará se atingir uma linha de código que requer autorização que o script não tem. Para evitar essa situação, os desenvolvedores podem usar o método ScriptApp.getAuthorizationInfo() para limitar o acesso a partes de código que mudaram entre as versões publicadas do complemento.

Confira abaixo um exemplo da estrutura recomendada para usar em funções de acionamento para evitar armadilhas de autorização. A função de gatilho de exemplo responde a um evento de envio de formulário em um complemento do Planilhas Google e, se uma nova autorização for necessária, envia ao usuário do complemento um e-mail de alerta usando HTML de modelo.

/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = 'My Add-on Title';
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (authInfo.getAuthorizationStatus() ===
    ScriptApp.AuthorizationStatus.REQUIRED) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty('lastAuthEmailDate');
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile('AuthorizationEmail');
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(Session.getEffectiveUser().getEmail(),
            'Authorization Required',
            message.getContent(), {
              name: addonTitle,
              htmlBody: message.getContent()
            }
        );
      }
      props.setProperty('lastAuthEmailDate', today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

Restrições

Os acionadores instaláveis em complementos estão sujeitos às mesmas restrições que regem os acionadores instaláveis em outros tipos de projetos do Apps Script.

Além dessas restrições, diversas restrições se aplicam especificamente aos gatilhos instaláveis em complementos:

• Cada complemento pode ter apenas um acionador de cada tipo, por usuário e por documento. Por exemplo, em uma determinada planilha, um determinado usuário pode ter apenas um acionador de edição, embora o usuário também possa ter um acionador de envio de formulário ou um acionador por tempo na mesma planilha. Um usuário diferente com acesso à mesma planilha pode ter seu próprio conjunto separado de acionadores.
• Os complementos só podem criar gatilhos para o arquivo em que o complemento é usado. Ou seja, um complemento usado no arquivo do Documentos Google não pode criar um acionador para monitorar quando o documento B é aberto.
• Gatilhos baseados em tempo não podem ser executados mais do que uma vez por hora.
• Os complementos não enviam automaticamente um e-mail ao usuário quando o código executado por um acionador instalável gera uma exceção. Cabe ao desenvolvedor verificar e lidar com os casos de falha normalmente.
• Os acionadores de complementos são interrompidos nas seguintes situações:
  • Se o usuário desinstalar o complemento,
  • Se o complemento estiver desativado em um documento e, se for reativado, o gatilho ficará operacional novamente.
  • Se o desenvolvedor cancelar a publicação do complemento ou enviar uma versão corrompida para a loja de complementos.
• As funções de acionamento de complementos são executadas até chegarem ao código que usa um serviço não autorizado. Nesse momento, elas são interrompidas. Isso só ocorrerá se o complemento for publicado. O mesmo acionador em um projeto normal do Apps Script ou um complemento não publicado não será executado se alguma parte do script precisar de autorização.
• Os acionadores instaláveis estão sujeitos aos limites de cota de acionadores do Apps Script.