Come gli attivatori semplici, quelli installabili consentono Apps Script esegue automaticamente una funzione quando si verifica un determinato evento come l'apertura di un documento. Gli attivatori installabili, tuttavia, offrono flessibilità rispetto ai semplici trigger: possono servizi che richiedono autorizzazione, offrono diversi tipi di eventi, inclusi quelli a tempo (orologio) e possono essere controllati in modo programmatico. Sia per le applicazioni semplici installabili, Apps Script passa la funzione attivata un oggetto evento che contiene informazioni sul contesto in cui si è verificato l'evento.
Restrizioni
Anche se i trigger installabili offrono più flessibilità rispetto ai semplici trigger, sono comunque soggetti a diverse limitazioni:
- Non vengono eseguiti se un file viene aperto in modalità di sola lettura (visualizzazione o commento). Per script autonomi, gli utenti devono almeno disporre dell'accesso in visualizzazione al file dello script in per far funzionare correttamente i trigger.
Le esecuzioni degli script e le richieste API non causano l'esecuzione di trigger. Ad esempio: chiamata
FormResponse.submit()l'invio di una nuova risposta del modulo non determina l'esecuzione dell'attivatore di invio del modulo.I trigger installabili vengono sempre eseguiti nell'account della persona che ha creato che li rappresentano. Ad esempio, se crei un trigger di apertura installabile, viene eseguito Quando il tuo collega apre il documento (se dispone dell'accesso in modifica), ma viene eseguito con il tuo account. Ciò significa che se crei un attivatore per inviare un'email quando viene aperto un documento, l'email viene sempre inviata dal tuo account, non necessariamente dall'account che ha aperto il documento. Tuttavia, potresti creare un trigger installabile per ogni account, in un'email inviata da ciascun account.
Un determinato account non può vedere i trigger installati da un secondo account, nemmeno anche se il primo account può comunque attivare questi attivatori.
I trigger installabili sono soggetti all'attivatore di Apps Script limiti di quota.
Trigger basati sul tempo
Un trigger a tempo (chiamato anche trigger orologio) è simile a un cron job in Unix. I trigger a tempo consentono vengono eseguiti in un determinato momento o su un intervallo ricorrente, con la frequenza ogni minuto o con la frequenza minore di una volta al mese. Tieni presente che componente aggiuntivo puoi usare un trigger a tempo al massimo una volta all'ora). L'orario potrebbe essere leggermente in modo casuale: ad esempio, se crei un trigger ricorrente delle 9:00, Apps Script sceglie un orario compreso tra le 09:00 e le 10:00 e poi mantiene la tempistica è coerente da un giorno all'altro, in modo che trascorrano 24 ore prima l'attivatore si attiva di nuovo.
Di seguito è riportato un esempio di App Google Chat che pubblica un messaggio ogni minuto in ogni spazio in cui si trova l'app:
// 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),
});
}
Trigger basati su eventi
I trigger installabili basati su eventi sono concettualmente simili ai
semplici attivatori
come onOpen(), ma può rispondere a eventi aggiuntivi e si comporta
in modo diverso.
Ad esempio, l'attivatore Apri installabile per Fogli Google
si attiva ogni volta che il foglio di lavoro viene aperto da un utente che dispone dell'accesso in modifica,
proprio come il semplice trigger onOpen(). Tuttavia, la versione installabile
chiama servizi che richiedono
autorizzazione. Installabile
con l'autorizzazione dell'utente che ha creato il trigger, persino
se un altro utente con accesso in modifica apre il foglio di lavoro.
Esistono diversi trigger installabili Google Workspace applicazioni:
- Un attivatore open installabile viene eseguito quando un utente apre un foglio di lavoro. documento o modulo di cui dispongono dell'autorizzazione alla modifica.
- Un attivatore edit installabile viene eseguito quando un utente modifica un valore in un in un foglio di lavoro.
- Un attivatore change installabile viene eseguito quando un utente modifica la struttura di un foglio di lavoro stesso, ad esempio aggiungendo un nuovo foglio o rimuovendo colonna.
- Un attivatore di invio modulo installabile viene eseguito quando un utente risponde a un modulo. Esistono due versioni dell'attivatore "Invia modulo", solo per Moduli Google e una per Fogli, se il modulo viene inviato a un foglio di lavoro.
- Un attivatore di evento di calendario installabile viene eseguito quando gli eventi nel calendario di un utente vengono aggiornati, creati, modificati o eliminati.
Puoi usare trigger installabili in script autonomi e associati. Ad esempio, un script autonomo può creare ed eseguire un trigger installabile per un file di Fogli Google arbitrario chiamando TriggerBuilder.forSpreadsheet(key) e passando l'ID del foglio di lavoro.
Gestire gli attivatori manualmente
Per creare manualmente un trigger installabile nell'editor di script, segui questi passaggi:
- Apri il progetto Apps Script.
- A sinistra, fai clic su Attivatori .
- In basso a destra, fai clic su Aggiungi trigger.
- Seleziona e configura il tipo di trigger da creare.
- Fai clic su Salva.
Gestisci i trigger in modo programmatico
Puoi anche creare ed eliminare i trigger in modo programmatico con il
Servizio di script. Inizia chiamando
ScriptApp.newTrigger(functionName),
che restituisce un
TriggerBuilder.
L'esempio seguente mostra come creare due trigger basati sul tempo, uno che si attiva ogni 6 ore e una che si attiva ogni lunedì alle 09:00 (nel fuso orario su cui è impostato lo script).
L'esempio successivo mostra come creare un trigger di apertura installabile per un
in un foglio di lavoro. Tieni presente che, a differenza di un semplice trigger onOpen(), lo script per
non è necessario associare il trigger installabile al foglio di lavoro. Per creare
questo trigger da uno script autonomo, è sufficiente sostituire
SpreadsheetApp.getActive() con una chiamata a
SpreadsheetApp.openById(id)
Per modificare in modo programmatico un trigger installabile esistente, devi eliminarlo e crearne uno nuovo. Se hai già memorizzato l'ID di un trigger, puoi eliminalo passando l'ID come argomento alla funzione riportata di seguito.
Errori nei trigger
Quando si attiva un attivatore installabile, ma la funzione genera un'eccezione o altrimenti non viene eseguita correttamente, non viene visualizzato alcun messaggio di errore schermo. Dopotutto, quando viene eseguito un attivatore a tempo o un altro utente lo attiva come trigger per l'invio del modulo, potresti non trovarti nemmeno al computer.
Apps Script ti invia invece un'email come la seguente:
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.
L'email include un link per disattivare o riconfigurare l'attivatore. Se lo script è legato in un file di Fogli, Documenti o Moduli Google l'email include anche un link al file. Questi link ti consentono disattiva il trigger o modifica lo script per correggere il bug.
Per esaminare tutti gli attivatori associati al tuo Account Google e disattivare quelli che non ti servono più, segui questi passaggi:
- Visita il sito
script.google.com. - A sinistra, fai clic su My Triggers (I miei trigger).
Per eliminare un attivatore, fai clic su Altro a destra dell'attivatore > Elimina trigger:
Trigger nei componenti aggiuntivi
Oltre ai trigger installabili, puoi utilizzare i trigger manifest componenti aggiuntivi. Per saperne di più, consulta Trigger per i componenti aggiuntivi di Google Workspace.