Os acionadores do Apps Script fazem com que uma função de script especificada (a função de gatilho) seja executada sempre que um evento ocorre. Apenas determinados eventos podem acionar disparos, 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 forma diferente com base no tipo de acionador.
Depois que o objeto de evento é criado, o Apps Script o transmite como um parâmetro à 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 card quando o usuário abre uma conversa em mensagens. Nesse caso, você implementa uma função de callback contextual para criar os cards que compõem a nova IU usando os dados transmitidos no objeto de evento.
Nesta página, você encontra diretrizes sobre como usar gatilhos em projetos complementares 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 Apps Script. Em vez disso, eles usam acionadores projetados especificamente para os complementos do Google Workspace: acionadores de manifesto.
Os acionadores de manifesto são definidos completamente no manifesto do complemento do Google Workspace. Veja alguns exemplos de acionadores de manifesto:
- Acionadores da página inicial que criam e exibem a página inicial do complemento.
- Acionadores de evento eventCalendar que exibem um novo cartão ou realizam outras ações quando um evento do Google Agenda é aberto.
- Acionadores de eventUpdate do Google Agenda que exibem um novo cartão ou realizam outras ações quando um usuário edita e salva um evento do Agenda.
- Acionadores onItemsSelected do Drive que mostram um novo cartão ou realizam outras ações quando um usuário seleciona um ou mais arquivos ou pastas no Drive.
- Acionadores 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 cartão ou 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
drive.file
do OAuth no documento atual.
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 definições de acionadores de manifesto.
Além dos acionadores de manifesto, os complementos do Google Workspace também podem usar os gatilhos instaláveis do Apps Script.
Restrições
Os acionadores de manifesto têm algumas restrições de uso.
- Esses acionadores são usados apenas em projetos de complementos do Google Workspace. Eles não têm finalidade em outros aplicativos.
- 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. - Atualmente, os acionadores contextuais do Gmail só podem ter um critério
unconditional
. Isso significa que os acionadores contextuais são disparados para cada mensagem de e-mail, independentemente do conteúdo. - Cada complemento só pode ter um acionador de cada tipo, por usuário e documento.