Assim como os acionadores simples, os acionadores instaláveis permitem O Apps Script executa uma função automaticamente quando um determinado evento, como ao abrir um documento. No entanto, os gatilhos instaláveis oferecem mais flexibilidade do que gatilhos simples: eles podem chamar serviços que exigem autorização, Eles oferecem vários outros tipos de eventos, incluindo eventos com base no tempo (relógio) e podem ser controlados de forma programática. Para gatilhos simples e instaláveis, o Apps Script transmite à função acionada um objeto de evento que contém informações sobre o contexto em que o evento ocorreu.
Restrições
Embora os gatilhos instaláveis ofereçam mais flexibilidade do que os gatilhos simples, eles ainda estão sujeitos a várias restrições:
- Eles não serão executados se um arquivo for aberto no modo somente leitura (visualização ou comentário). Para scripts autônomos, os usuários precisam ter, no mínimo, acesso de leitura ao arquivo de script para que os gatilhos funcionem corretamente.
As execuções de script e as solicitações da API não fazem com que os gatilhos sejam executados. Por exemplo: chamar
FormResponse.submit()para enviar uma nova resposta de formulário não faz com que o acionador de envio do formulário seja executado.Os acionadores instaláveis sempre são executados na conta da pessoa que criou para resolvê-los com rapidez. Por exemplo, se você criar um gatilho aberto instalável, ele será executado quando seu colega abrir o documento (se ele tiver acesso para edição), mas é executado como sua conta. Isso significa que, se você criar um gatilho para enviar um e-mail quando um documento for aberto, o e-mail será sempre enviado de sua conta, não necessariamente a conta que abriu o documento. No entanto, você pode criar um acionador instalável para cada conta, o que resultaria em um e-mail enviado de cada conta.
Uma determinada conta não pode ver os acionadores instalados de outra conta, mesmo que embora a primeira conta ainda possa ativar esses acionadores.
Os gatilhos instaláveis estão sujeitos ao gatilho do Apps Script limites de cota.
Gatilhos orientados por tempo
Um gatilho baseado em tempo (também chamado de gatilho de relógio) é semelhante a um cron job no Unix. Acionadores baseados em tempo permitem scripts são executados em um determinado momento ou em um intervalo recorrente, com a mesma frequência a cada minuto ou com menos frequência, como uma vez por mês. Observe que um complemento pode usar um gatilho baseado em tempo no máximo uma vez por hora. O tempo pode ser um pouco randomizado, por exemplo, se você criar um acionador recorrente às 9h, O Apps Script escolhe um horário entre 9h e 10h e mantém que é consistente de um dia para o outro, de modo que as 24 horas decorreram antes da o acionador dispara novamente.
Veja a seguir um exemplo App Google Chat que publica uma mensagem a cada minuto em cada espaço em que o app está:
// Example app for Google Chat that demonstrates app-initiated messages
// by spamming the user every minute.
//
// This app makes use of the Apps Script OAuth2 library at:
// https://github.com/googlesamples/apps-script-oauth2
//
// Follow the instructions there to add the library to your script.
// When added to a space, we store the space's ID in ScriptProperties.
function onAddToSpace(e) {
PropertiesService.getScriptProperties()
.setProperty(e.space.name, '');
return {
'text': 'Hi! I\'ll post a message here every minute. ' +
'Please remove me after testing or I\'ll keep spamming you!'
};
}
// When removed from a space, we remove the space's ID from ScriptProperties.
function onRemoveFromSpace(e) {
PropertiesService.getScriptProperties()
.deleteProperty(e.space.name);
}
// Add a trigger that invokes this function every minute in the
// "Edit > Current Project's Triggers" menu. When it runs, it
// posts in each space the app was added to.
function onTrigger() {
var spaceIds = PropertiesService.getScriptProperties()
.getKeys();
var message = { 'text': 'Hi! It\'s now ' + (new Date()) };
for (var i = 0; i < spaceIds.length; ++i) {
postMessage(spaceIds[i], message);
}
}
var SCOPE = 'https://www.googleapis.com/auth/chat.bot';
// The values below are copied from the JSON file downloaded upon
// service account creation.
// For SERVICE_ACCOUNT_PRIVATE_KEY, remember to include the BEGIN and END lines
// of the private key
var SERVICE_ACCOUNT_PRIVATE_KEY = '...';
var SERVICE_ACCOUNT_EMAIL = 'service-account@project-id.iam.gserviceaccount.com';
// Posts a message into the given space ID via the API, using
// service account authentication.
function postMessage(spaceId, message) {
var service = OAuth2.createService('chat')
.setTokenUrl('https://accounts.google.com/o/oauth2/token')
.setPrivateKey(SERVICE_ACCOUNT_PRIVATE_KEY)
.setClientId(SERVICE_ACCOUNT_EMAIL)
.setPropertyStore(PropertiesService.getUserProperties())
.setScope(SCOPE);
if (!service.hasAccess()) {
Logger.log('Authentication error: %s', service.getLastError());
return;
}
var url = 'https://chat.googleapis.com/v1/' + spaceId + '/messages';
UrlFetchApp.fetch(url, {
method: 'post',
headers: { 'Authorization': 'Bearer ' + service.getAccessToken() },
contentType: 'application/json',
payload: JSON.stringify(message),
});
}
Gatilhos orientados por eventos
Gatilhos orientados por eventos instaláveis são conceitualmente semelhantes aos
acionadores simples
como onOpen(), mas eles podem responder a eventos adicionais e se comportam
de maneiras diferentes.
Por exemplo, o acionador de abertura instalável para as Planilhas Google
é ativado sempre que a planilha é aberta por qualquer usuário que tenha acesso de edição,
assim como o acionador onOpen() simples. No entanto, a versão instalável pode
chamar serviços que exigem
autorização. O instalável
versão é executada com a autorização do usuário que criou o acionador, mesmo
se outro usuário com acesso para editar abrir a planilha.
Há vários gatilhos instaláveis para Google Workspace aplicativos:
- Um acionador aberto instalável é executado quando um usuário abre uma planilha. documento ou formulário que eles têm permissão para editar.
- Um acionador edit instalável é executado quando um usuário modifica um valor em um planilha.
- Um acionador de alteração instalável é executado quando um usuário modifica a estrutura de um planilha em si, por exemplo, adicionando uma nova página ou removendo uma .
- Um acionador de envio de formulário instalável é executado quando um usuário responde a um formulário. Há duas versões do acionador "form-submit", um para o app Formulários Google e uma para o Planilhas Google, se o formulário for enviado para uma planilha.
- Um acionador de eventos da agenda instalável é executado quando os eventos da agenda de um usuário são atualizados (criados, editados ou excluídos).
É possível usar gatilhos instaláveis em scripts independentes e vinculados. Por exemplo:
um script autônomo pode criar programaticamente um gatilho instalável para um
arquivo arbitrário do Planilhas Google chamando
TriggerBuilder.forSpreadsheet(key)
e passando o ID da planilha.
Gerenciar acionadores manualmente
Para criar manualmente um gatilho instalável no editor de script, siga estas etapas:
- Abra seu projeto do Apps Script.
- À esquerda, clique em Gatilhos .
- No canto inferior direito, clique em Adicionar gatilho.
- Selecione e configure o tipo de acionador que você quer criar.
- Clique em Salvar.
Gerenciar acionadores de maneira programática
Também é possível criar e excluir gatilhos programaticamente com o
Serviço de script. Comece chamando
ScriptApp.newTrigger(functionName),
que retorna um
TriggerBuilder
O exemplo a seguir mostra como criar dois gatilhos orientados por tempo, um que dispara a cada 6 horas e outro que é disparado toda segunda-feira às 9h (no fuso horário) está definido para o script).
O próximo exemplo mostra como criar um gatilho aberto instalável para um
planilha. Ao contrário de um acionador onOpen() simples, o script de
o acionador instalável não precisa estar vinculado à planilha. Para criar
esse gatilho a partir de um script autônomo, basta substituir
SpreadsheetApp.getActive() com uma chamada para
SpreadsheetApp.openById(id).
Para modificar programaticamente um gatilho instalável, ele precisa ser excluído. e criar um novo. Se você já armazenou o ID de um acionador, poderá excluí-la passando o ID como um argumento para a função abaixo.
Erros em acionadores
Quando um acionador instalável é disparado, mas a função gera uma exceção ou caso contrário, não vai aparecer uma mensagem de erro na tela. Afinal, quando um acionador baseado em tempo é executado ou outro usuário o ativa seu acionador de envio de formulário, talvez você nem esteja em seu computador.
Em vez disso, o Apps Script envia um e-mail como este:
From: noreply-apps-scripts-notifications@google.com Subject: Summary of failures for Google Apps Script Your script has recently failed to finish successfully. A summary of the failure(s) is shown below.
O e-mail inclui um link para desativar ou reconfigurar o acionador. Se o o script é limitado a um arquivo do Planilhas, Documentos ou Formulários Google o e-mail também incluirá um link para esse arquivo. Esses links permitem que você desative o gatilho ou edite o script para corrigir o bug.
Para analisar todos os acionadores associados à sua Conta do Google e: desativar os acionadores desnecessários, siga estas etapas:
- Acesse
script.google.com. - À esquerda, clique em Meus gatilhos.
Para excluir um acionador, clique em "Mais" à direita dele. > Excluir gatilho.
Gatilhos em complementos
Além dos acionadores instaláveis, você pode usar acionadores de manifesto em complementos. Para mais informações, consulte Acionadores para complementos do Google Workspace.