Os acionadores do Apps Script fazem com que uma função de script especificada (a função de acionamento) 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 é um callback que você precisa 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 Apps Script no momento. Em vez disso, eles usam acionadores projetados especificamente para complementos do Google Workspace: acionadores de manifesto.
Os gatilhos de manifesto são definidos completamente no manifesto do complemento do Google Workspace. Exemplos de gatilhos de manifesto incluem o seguinte:
- Acionadores da página inicial que criam e mostram a página inicial do complemento.
- Eventos 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.
- Os acionadores onItemsSelected do Drive mostram um novo card ou realizam outras ações quando um usuário seleciona um ou mais arquivos ou pastas no Drive.
- Acionadores de texto do Gmail que mostram um card de complemento quando o usuário abre o complemento na janela de texto do Gmail.
- Acionadores contextuais do Gmail que mostram um novo card ou realizam outras ações quando o usuário abre uma mensagem do Gmail.
- O Editor onFileScopeGranted aciona a exibição de um novo card quando os usuários
concedem autorização para o escopo OAuth
drive.fileno documento atual do Editor.
Na lista acima, apenas os gatilhos da página inicial não são contextuais. Os demais são gatilhos contextuais. Consulte Manifesto para mais informações sobre definições de acionadores de manifesto.
Além dos gatilhos de manifesto, os complementos do Google Workspace também podem usar gatilhos 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 e não têm utilidade 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
Scriptdo 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 os acionadores contextuais são ativados 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.