Come i trigger semplici, quelli installabili consentono a Apps Script di eseguire una funzione automaticamente quando si verifica un determinato evento, ad esempio l'apertura di un documento. Tuttavia, i trigger installabili offrono più flessibilità rispetto ai semplici trigger: possono chiamare servizi che richiedono l'autorizzazione, offrono diversi tipi di eventi, inclusi gli attivatori a tempo (orologio), e possono essere controllati in modo programmatico. Sia per i trigger semplici che per quelli installabili, Apps Script passa la funzione attivata a un oggetto evento contenente 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 gli script autonomi, gli utenti devono almeno disporre dell'accesso in visualizzazione al file di script affinché i trigger vengano eseguiti correttamente.
Le esecuzioni degli script e le richieste API non causano l'esecuzione di trigger. Ad esempio, chiamare
FormResponse.submit()per inviare una nuova risposta al modulo non causa l'esecuzione dell'attivatore di invio del modulo.I trigger installabili vengono sempre eseguiti nell'account della persona che li ha creati. Ad esempio, se crei un attivatore aperto installabile, questo viene eseguito quando il tuo collega apre il documento (se il collega dispone dell'accesso in modifica), ma viene eseguito con il tuo account. Ciò significa che se crei un attivatore per inviare un'email quando un documento viene aperto, l'email viene sempre inviata dal tuo account, non necessariamente da quello che ha aperto il documento. Tuttavia, puoi creare un trigger installabile per ogni account, in modo da inviare un'email da ciascun account.
Un determinato account non può vedere gli attivatori installati da un secondo account, anche se il primo account può comunque attivarli.
I trigger installabili sono soggetti ai limiti di quota dei trigger di Apps Script.
Trigger basati sul tempo
Un trigger a tempo (chiamato anche trigger orologio) è simile a un cron job in Unix. I trigger a tempo consentono l'esecuzione degli script in un determinato momento o in un intervallo ricorrente, ogni minuto o con una frequenza non frequente come una volta al mese. Tieni presente che un componente aggiuntivo può utilizzare un trigger a tempo al massimo una volta all'ora. L'orario potrebbe essere leggermente casuale. Ad esempio, se crei un trigger ricorrente delle 9:00, Apps Script sceglie un orario compreso tra le 9:00 e le 10:00, quindi mantiene questa tempistica coerente di giorno in giorno, in modo che trascorrano 24 ore prima che l'attivatore si attivi 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 trigger come onOpen(), ma possono rispondere a eventi aggiuntivi e si comportano in modo diverso.
Ad esempio, l'attivatore di apertura 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 attivatore onOpen(). Tuttavia, la versione installabile può
chiamare servizi che richiedono
autorizzazione. La versione installabile
viene eseguita con l'autorizzazione dell'utente che ha creato il trigger, anche
se un altro utente con accesso in modifica apre il foglio di lavoro.
Esistono diversi trigger installabili per le applicazioniGoogle Workspace :
- Un attivatore open installabile viene eseguito quando un utente apre un foglio di lavoro, un documento o un modulo che è autorizzato a modificare.
- Un attivatore edit installabile viene eseguito quando un utente modifica un valore in un foglio di lavoro.
- Un attivatore modifica installabile viene eseguito quando un utente modifica la struttura di un foglio di lavoro stesso, ad esempio aggiungendo un nuovo foglio o rimuovendo una colonna.
- Un attivatore di invio modulo installabile viene eseguito quando un utente risponde a un modulo. Esistono due versioni dell'attivatore di invio del modulo: una 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, uno script autonomo può creare in modo programmatico un trigger installabile per un file di Fogli Google arbitrario chiamando TriggerBuilder.forSpreadsheet(key) e trasmettendo 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 Script. Per iniziare, chiama 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 uno che si attiva ogni lunedì alle 09:00 (nel fuso orario impostato sullo script).
L'esempio seguente mostra come creare un trigger aperto installabile per un foglio di lavoro. Tieni presente che, a differenza di un semplice trigger onOpen(), lo script per
il trigger installabile non deve essere associato 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à archiviato l'ID di un trigger, puoi eliminarlo passando l'ID come argomento alla funzione 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 un messaggio di errore sullo schermo. Dopo tutto, quando viene eseguito un trigger a tempo o un altro utente attiva il trigger di invio del modulo, potresti non essere 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 a un file di Fogli, Documenti o Moduli Google, l'email include anche un link al file. Questi link ti consentono di disattivare il trigger o modificare lo script per correggere il bug.
Per esaminare tutti gli attivatori associati al tuo Account Google e disattivare quelli non più necessari, 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 > Elimina trigger a destra dell'attivatore.
Trigger nei componenti aggiuntivi
Oltre ai trigger installabili, puoi utilizzare i trigger del manifest nei componenti aggiuntivi. Per maggiori informazioni, consulta la pagina Attivatori per i componenti aggiuntivi di Google Workspace.