Gatilhos para complementos do Google Workspace

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 Google Workspace que estende o Gmail, é possível definir um gatilho que cria uma nova interface de cartão quando o usuário abre uma linha de execução de mensagens. Nesse caso, implemente uma função de callback contextual para criar os cartões que compõem a nova IU usando os dados transmitidos no objeto de evento.

Nesta página, você encontra diretrizes sobre o uso de gatilhos em projetos de complementos do Google Workspace.

Gatilhos do manifesto

Ao contrário dos complementos do Editor, os complementos do Google Workspace atualmente não podem usar gatilhos simples do Apps Script. Em vez disso, eles usam acionadores projetados especificamente para complementos do Google Workspace: acionadores de manifesto.

Os acionadores de manifesto são definidos completamente no manifesto do complemento do Google Workspace. Confira alguns exemplos de acionadores de manifesto:

  • Acionadores da página inicial que criam e exibem a página inicial do complemento.
  • Acionadores eventOpen da Agenda que exibem um novo card ou realizam outras ações quando um evento do Google Agenda é aberto.
  • Acionadores eventUpdate da Agenda que exibem um novo card ou realizam outras ações quando um usuário edita e salva um evento do Agenda.
  • acionadores onItemsSelected do Drive que exibem um novo card ou realizam outras ações quando um usuário seleciona um ou mais arquivos ou pastas no Drive.
  • Acionadores de escrita do Gmail que exibem um card de complemento quando o usuário abre o complemento na janela de texto do Gmail.
  • Acionadores contextuais do Gmail que exibem um novo card ou realizam outras ações quando o usuário abre uma mensagem do Gmail.
  • Acionadores onFileScopegranted do Editor que exibem um novo cartão quando os usuários concedem autorização para o escopo do OAuth drive.file no documento atual do Editor.

Na lista acima, apenas os acionadores da página inicial não são contextuais. O restante são acionadores contextuais. Consulte Manifesto para mais informações sobre as definições de acionadores do manifesto.

Além dos acionadores do manifesto, os complementos do Google Workspace também podem usar acionadores instaláveis do Apps Script.

Restrições

Os acionadores do manifesto têm algumas restrições de uso.

  • Esses gatilhos são usados apenas em projetos de complementos do Google Workspace e não têm finalidade em nenhum outro aplicativo.
  • Como eles são definidos no manifesto do complemento, e não no código, não é possível usar o serviço Script do Apps Script para criar ou modificar esses gatilhos.
  • No momento, os acionadores contextuais do Gmail só podem ter um critério unconditional. Isso significa que acionadores contextuais são disparados para cada mensagem de e-mail, independentemente do conteúdo.
  • Cada complemento pode ter apenas um acionador de cada tipo, por usuário e por documento.