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 específico ocorre. Apenas determinados eventos podem acionar gatilhos, e cada aplicativo do Google Workspace oferece suporte a um conjunto diferente de eventos.
Quando um acionador é 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 gatilho. A função de gatilho é 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 Google Workspace que estende o Gmail, é possível definir um acionador que cria uma nova interface de cartão quando o usuário abre uma linha de mensagens. 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 atualmente não podem usar gatilhos simples do Apps Script. Em vez disso, eles usam gatilhos criados especificamente para complementos do Google Workspace: gatilhos de manifesto.
Os acionadores de manifesto são definidos completamente no manifesto do complemento do Google Workspace. Exemplos de acionadores de manifesto incluem:
- Gatilhos da página inicial que criam e exibem a página inicial do complemento.
- Acionadores de abertura de evento da agenda que mostram um novo card ou realizam outras ações quando um evento da agenda é aberto.
- Acionadores de atualização de eventos da Agenda que mostram um novo card ou realizam outras ações quando um usuário edita e salva um evento da Agenda.
- Acionadores do Drive onItemsSelected que mostram um novo card ou realizam outras ações quando um usuário seleciona um ou mais arquivos ou pastas no Drive.
- Acionadores de composição do Gmail que mostram um card de complemento quando o usuário abre o complemento na janela de composição do Gmail.
- Gatilhos contextuais do Gmail que exibem um novo card ou realizam outras ações quando o usuário abre uma mensagem do Gmail.
- Acionadores do editor onFileScopeGranted que mostram um novo card quando os usuários
concedem autorização para o escopo OAuth
drive.fileno documento do editor atual.
Na lista acima, apenas os gatilhos da página inicial não são contextuais. Os demais são contextuais. Consulte Manifesto para mais informações sobre as definições de acionador do manifesto.
Além dos acionadores de manifesto, os complementos do Google Workspace também podem usar acionadores instaláveis do Apps Script.
Restrições
Os acionadores de manifesto têm algumas restrições de uso.
- Esses gatilhos são usados apenas em projetos de complementos do Google Workspace. Eles não têm utilidade 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
Scriptdo Apps Script para criar ou modificar esses acionadores. - No momento, os acionadores contextuais do Gmail só podem ter um critério
unconditional. Isso significa que os gatilhos contextuais são acionados para todas as mensagens de e-mail, independentemente do conteúdo. - Cada complemento pode ter apenas um acionador de cada tipo, por usuário, por documento.