Gatilhos para complementos do Editor

Os acionadores do Apps Script causam um script especificado. (a função de gatilho) para ser executada sempre que um evento especificado de segurança. Somente determinados eventos podem acionar gatilhos, e cada O 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 no evento a estrutura de objetos é organizada de maneira diferente com base no tipo de gatilho.

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

Esta página fornece diretrizes sobre como usar acionadores no editor em projetos complementares.

Tipos de gatilhos de complementos do editor

Você pode usar a maioria dos tipos de gatilhos genéricos disponíveis para projetos do Google Apps Script em complementos do Editor, incluindo acionadores simples e a maioria dos gatilhos instaláveis. A 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 e fornecem links para os objetos de evento correspondentes:

Evento	Objeto de evento	Acionadores simples	Acionadores instaláveis
Abrir Um arquivo do editor será aberto.	Objeto de evento do Docs onOpen 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
Instalação 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 do Planilhas	Planilhas function onEdit(e)	Planilhas
Alterar O conteúdo de uma página é editado ou formatado.	Objeto de evento onChange do Planilhas		Planilhas
Envio do formulário Um arquivo do Formulários Google é enviado.	Objeto de evento de envio de formulário dos formulários Objeto de evento de envio de formulário das Planilhas Google		Formulários Planilhas
Baseado no tempo (relógio) O acionador é disparado em um horário ou intervalo especificado.	Objeto de evento baseado em tempo		Documentos Formulários Planilhas Apresentações

* O evento de abertura dos 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 um de rede, não podem usar serviços que exigem autorização e são ativado para uso automaticamente. Em alguns casos, um evento acionador simples ser processada por um acionador instalável.

Você pode adicionar um gatilho simples a um complemento simplesmente implementando uma função por um destes nomes reservados:

• onOpen(e) é executado quando um usuário abre um documento, uma planilha ou apresentação. onOpen(e) também pode ser executado quando um formulário é aberto no editor (mas não ao responder ao formulário). Ela só é executada se o usuário permissão para editar o arquivo em questão e é mais frequentemente usada para criar itens de menu.
• onInstall(e) é executado quando um usuário instala um complemento. Preço normal: onInstall(e) é usado apenas para chamar onOpen(e); isso garante que os menus do complemento apareçam imediatamente após a instalação, sem que o usuário precise atualizar a página.
• onEdit(e) é executado quando um usuário altera o valor de uma célula em uma planilha. Este acionador não é disparado em resposta a movimentação, formatação ou movimentação de células outras mudanças que não alteram os valores das células.

Restrições

Gatilhos simples em complementos estão sujeitos à mesma restrições que regem as ações e acionadores em outros tipos de projetos do Apps Script. Observe especificamente essas restrições ao projetar complementos:

• Acionadores 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 do complemento sejam preenchidos.
• Em determinadas circunstâncias, os complementos do Editor executam onOpen(e) e onEdit(e) gatilhos simples no modo sem autorização. Esse modo apresenta algumas complicações adicionais, conforme descrito nas modelo de autorização de complemento.
• Gatilhos simples não podem usar serviços nem receber outras ações que exigem autorização, exceto quando descritos na modelo de autorização de complementos.
• Acionadores simples não podem ser executados por mais de 30 segundos. Tome cuidado para minimizar a quantidade de processamento feito em uma função de gatilho simples.
• Acionadores simples estão sujeitos ao acionador do Apps Script limites de cota.

Gatilhos instaláveis em complementos

Os complementos podem criar e modificar gatilhos instaláveis de forma programática; com o serviço Script do Apps Script. complemento não podem ser criados manualmente. Ao contrário de gatilhos simples, e gatilhos instaláveis podem usar serviços que exigem autorização.

Acionadores instaláveis em complementos não enviam e-mails de erro para o usuário em caso de erros, já que, na maioria dos casos, ele não consegue para resolver o problema. Por isso, você deve criar seu complemento para e lidar com erros em nome do usuário sempre que possível.

Os complementos podem usar estes gatilhos instaláveis:

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

• Gatilhos instaláveis enviar de formulário são executados quando uma resposta do Formulário Google é enviados.

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

Autorizar gatilhos instaláveis

Normalmente, se um desenvolvedor atualiza um complemento para usar novos serviços que exigem autorização adicional, os usuários precisarão autorizar o complemento novamente no próximo quando o utilizam.

No entanto, os complementos que usam gatilhos apresentam desafios especiais de autorização. Imagine um complemento que usa um gatilho para monitorar envios de formulários: o criador de conteúdo pode autorizar o complemento na primeira vez que usá-lo e deixá-lo para são exibidos por meses ou anos sem nunca reabrir o formulário. Se o desenvolvedor do complemento atualizasse o complemento para usar novos serviços que exigirem autorização adicional, o criador do formulário nunca veria o caixa de diálogo de reautorização porque o formulário nunca foi reaberto, e o complemento deixaria de funcionar.

Ao contrário dos acionadores em projetos comuns do Apps Script, os acionadores complementos continuam a ser acionados mesmo se precisarem de uma nova autorização. No entanto, o script ainda falhará se atingir uma linha de código que requer autorização, 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 do código que foram alteradas entre as versões publicadas o complemento.

Confira abaixo um exemplo da estrutura recomendada para uso em funções de gatilho para evitar as armadilhas da autorização. O exemplo de função de gatilho responde evento de envio de formulário em um complemento do Planilhas Google e, se for necessária uma nova autorização requerido, envia ao usuário do complemento um e-mail de alerta usando HTML 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 gatilhos instaláveis em complementos estão sujeitos aos mesmos restrições que controlam acionadores instaláveis em outros tipos de projetos do Google Apps Script.

Além dessas restrições, várias outras se aplicam a dispositivos gatilhos especificamente 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 só pode ter uma edição embora o usuário também possa ter um acionador de envio de formulário ou um e por tempo na mesma planilha. Outro usuário com acesso à mesma planilha podem 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 Documento A não pode criar um gatilho para monitorar quando o Documento Google B for aberto.
• Os acionadores 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 gatilho instalável gera uma exceção. Cabe ao desenvolvedor verificar e lide com os casos de falha de modo prático.
• Os acionadores de complementos param de ser acionados em qualquer uma das seguintes situações:
  • Se o complemento for desinstalado pelo usuário,
  • Se o complemento estiver desativado em um documento (se for reativado, o acionador voltar a funcionar) ou
  • Se o desenvolvedor cancelar a publicação do complemento ou enviar uma versão corrompida para o loja de complementos.
• As funções do gatilho de complementos são executadas até alcançarem o código que usa um serviço não autorizado, e quando ele é interrompido. Isso é verdadeiro somente se o complemento for publicado. o mesmo gatilho em um projeto normal do Apps Script ou um complemento não publicado não é executado se alguma parte do script precisar autorização.
• Os gatilhos instaláveis estão sujeitos ao gatilho do Apps Script limites de cota.