Gatilhos para complementos do editor

Os acionadores do Apps Script fazem com que uma função de script especificada (a função de acionador) seja executada sempre que um evento especificado ocorrer. Somente alguns eventos podem acionar acionadores, e cada aplicativo do Google Workspace oferece suporte a 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 acionador. A função de acionador é uma função de callback que você precisa implementar para realizar as ações adequadas 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, você implementa a função de acionador onOpen(e) para criar os itens de menu necessários para o complemento, possivelmente usando os dados no objeto de evento.

Esta página fornece diretrizes sobre como usar acionadores em projetos de complementos do editor.

Tipos de acionadores de complementos do editor

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

Ao contrário dos complementos do editor, os complementos do Google Workspace não podem usar acionadores simples ou instaláveis genéricos do Apps Script. Em vez disso, eles usam acionadores projetados especificamente para complementos do Google Workspace. Para mais informações, consulte Acionadores de complementos do Google Workspace.

A tabela a seguir mostra os tipos de acionadores simples e instaláveis que os complementos do editor podem usar e fornece links para os objetos de evento correspondentes:

Evento	Objeto de evento	Acionadores simples	Acionadores instaláveis
Abrir Um arquivo do editor é aberto.	Objeto de evento onOpen do Documentos Objeto de evento onOpen do Formulários Objeto de evento onOpen do Planilhas Objeto de evento onOpen do Apresentações	Documentos Formulários* Planilhas Apresentações function onOpen(e)	Documentos Formulários Planilhas
Instalar O complemento é instalado.	Objeto de evento onInstall	Documentos Formulários Planilhas Apresentações function onInstall(e)
Editar O conteúdo da célula da planilha é alterado.	Objeto de evento onEdit do Planilhas	Planilhas function onEdit(e)	Planilhas
Alterar O conteúdo de uma planilha é editado ou formatado.	Objeto de evento onChange do Planilhas		Planilhas
Envio de formulário Um formulário Google é enviado.	Objeto de evento form-submit do Formulários Objeto de evento form-submit do Planilhas		Formulários Planilhas
Acionado por tempo (relógio) O acionador é disparado em um horário ou intervalo especificado.	Objeto de evento acionado 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.

Acionadores simples em complementos

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

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

• onOpen é executado quando um usuário abre um documento, uma planilha ou uma apresentação. onOpen também pode ser executado quando um formulário é aberto no editor (mas não ao responder ao formulário). Ele só é executado se o usuário tiver permissão para editar o arquivo em questão e é usado com mais frequência para criar itens de menu.
• onInstall é executado quando um usuário instala um complemento. Normalmente, onInstall é usado apenas para chamar onOpen. 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 é executado quando um usuário muda o valor de uma célula em uma planilha. Esse 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

Os acionadores simples em complementos estão sujeitos às mesmas restrições que regem acionadores simples em outros tipos de projetos do Apps Script. Preste atenção especial a essas restrições ao projetar complementos:

• Os acionadores simples não sã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 algumas circunstâncias, os complementos do editor executam os acionadores simples onOpen e onEdit em um modo sem autorização. Esse modo apresenta complicações, conforme descrito no modelo de autorização de complementos.
• Os acionadores simples não podem usar serviços ou realizar outras ações que exigem autorização, exceto conforme descrito no modelo de autorização de complementos.
• Os acionadores simples não podem ser executados por mais de 30 segundos. Minimize a quantidade de processamento feito em uma função de acionador simples.
• Os acionadores simples estão sujeitos aos limites de cota de acionadores do Apps Script .

Acionadores instaláveis em complementos

Os complementos podem criar e modificar acionadores instaláveis de maneira programática com o serviço Script do Apps Script. Os acionadores instaláveis de complementos não podem ser criados manualmente. Ao contrário dos acionadores simples, os acionadores 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, um usuário não consegue resolver o problema. Por isso, projete seu complemento para processar erros normalmente em nome do usuário sempre que possível.

Os complementos podem usar os seguintes acionadores instaláveis:

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

• Os acionadores instaláveis de envio de formulário são executados quando uma resposta do Formulários Google é enviada.

  Há duas versões de acionadores de envio de formulário: uma para o Planilhas (onde as respostas do formulário são coletadas) e outra para o Formulários Google. O objeto de evento transmitido para uma função de acionador de envio de formulário do Planilhas é mais simples e retorna os valores de resposta em matrizes simples. O objeto de evento transmitido para uma função de acionador de envio de formulário do Formulários fornece mais informações, contidas em um FormResponse objeto.

• Os **acionadores acionados por tempo** (também chamados de acionadores de relógio) são disparados em um horário específico ou repetidamente em um intervalo de tempo regular.

Autorizar acionadores instaláveis

Normalmente, se um desenvolvedor atualiza um complemento para usar novos serviços que exigem autorização adicional, os usuários são solicitados a autorizar novamente o complemento na próxima vez que o usarem.

No entanto, os complementos que usam acionadores encontram desafios especiais de autorização. Imagine um complemento que usa um acionador para monitorar envios de formulários: um criador de formulários pode autorizar o complemento na primeira vez que o usa e, em seguida, deixá-lo em execução por meses ou anos sem reabrir o formulário. Se o desenvolvedor do complemento atualizasse o complemento para usar novos serviços que exigem autorização adicional, o criador do formulário nunca veria a caixa de diálogo de reautorização porque nunca reabriu o formulário, e o complemento pararia de funcionar.

Ao contrário dos acionadores em projetos normais do Apps Script, os acionadores em complementos continuam sendo disparados mesmo que precisem de reautorização. No entanto, o script ainda falha se atingir uma linha de código que exige uma autorização que não tem. Para evitar isso, use ScriptApp.getAuthorizationInfo para restringir o acesso a partes do código que foram alteradas entre as versões de complemento.

Os exemplos a seguir mostram a estrutura recomendada para uso em funções de acionador para evitar problemas de autorização. A função de acionador de exemplo responde a um evento de envio de formulário em um complemento do Planilhas Google e, se a reautorização for necessária, envia ao usuário do complemento um e-mail de alerta usando HTML com modelo.

Code.gs

triggers/form/Code.gs

Ver no GitHub

/**
 * 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.
  }
}

authorizationemail.html

triggers/form/AuthorizationEmail.html

Ver no GitHub

<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 acionadores instaláveis em outros tipos de projetos do Apps Script.

Além dessas restrições, várias restrições se aplicam especificamente a acionadores instaláveis em complementos:

• Cada complemento só pode ter um acionador de cada tipo, por usuário, por documento. Por exemplo, em uma determinada planilha, um usuário só pode ter um acionador de edição, embora também possa ter um acionador de envio de formulário ou um acionador acionado por tempo na mesma planilha. Um usuário diferente com acesso à mesma planilha pode ter um conjunto separado de acionadores.
• Os complementos só podem criar acionadores para o arquivo em que o complemento é usado. Ou seja, um complemento usado no Documentos Google A não pode criar um acionador para monitorar quando o Documentos Google B é aberto.
• Os acionadores acionados por tempo não podem ser executados com mais frequência 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. É responsabilidade do desenvolvedor verificar e processar casos de falha normalmente.
• Os acionadores de complementos param de ser disparados em qualquer uma das seguintes situações:
  • Se o complemento for desinstalado pelo usuário,
  • Se o complemento estiver desativado em um documento (se ele for reativado, o acionador voltará a funcionar) ou
  • Se o desenvolvedor cancelar a publicação do complemento ou enviar uma versão corrompida para a loja de complementos.
• As funções de acionador de complementos são executadas até atingirem um código que usa um serviço não autorizado, momento em que param. Isso só é verdadeiro 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 qualquer parte do script precisar de autorização.
• Os acionadores instaláveis estão sujeitos aos limites de cota de acionadores do Apps Script .