Acionadores para complementos do Google Workspace

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

Quando um gatilho é acionado, 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 gatilho.

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ê deve implementar para realizar as ações adequadas em resposta 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 card quando o usuário abre uma conversa por e-mail. Nesse caso, você implementa uma função de callback contextual para criar os cards que compõem a nova interface usando os dados transmitidos no objeto de evento.

Esta página fornece diretrizes sobre como usar gatilhos em projetos de complementos do Google Workspace.

Gatilhos de manifesto

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

Os gatilhos de manifesto são definidos no manifesto do complemento do Google Workspace. Por exemplo:

  • Acionadores da página inicial que criam e mostram a página inicial do complemento.
  • Eventos do Google Agenda que mostram um novo card ou realizam outras ações quando um evento é aberto.
  • Gatilhos de eventUpdate da Agenda que mostram um novo card ou realizam outras ações quando um usuário edita e salva um evento.
  • Os gatilhos onItemsSelected do Google Drive mostram um novo card ou realizam outras ações quando um usuário seleciona arquivos ou pastas.
  • Acionadores de texto do Gmail que mostram um card de complemento quando o usuário abre o complemento na janela de texto.
  • Acionadores contextuais do Gmail que mostram um novo card ou realizam outras ações quando o usuário abre uma mensagem.
  • O Editor onFileScopeGranted triggers mostra um novo card quando os usuários concedem autorização para o escopo do OAuth drive.file no documento.

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

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

Restrições

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

  • Esses gatilhos são usados apenas em projetos de complementos do Google Workspace.
  • 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 elementos.
  • Os gatilhos contextuais do Gmail são acionados para todas as mensagens de e-mail, independente do conteúdo.
  • Cada complemento pode ter apenas um gatilho de cada tipo por usuário e por documento.