Come gli attivatori semplici, gli attivatori installabili consentono a Apps Script di eseguire automaticamente una funzione quando si verifica un determinato evento, ad esempio l'apertura di un documento. Gli attivatori installabili, tuttavia, offrono più flessibilità rispetto ai semplici attivatori: possono chiamare servizi che richiedono autorizzazione, offrono diversi tipi aggiuntivi di eventi, tra cui gli attivatori basati sul tempo (orologio) e possono essere controllati tramite programmazione. Per gli attivatori sia semplici che installabili, Apps Script passa alla funzione attivata un oggetto evento contenente informazioni sul contesto in cui si è verificato l'evento.
Restrizioni
Anche se gli attivatori installabili offrono una maggiore flessibilità rispetto agli attivatori semplici, 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 disporre almeno dell'accesso in visualizzazione al file dello script affinché gli attivatori vengano eseguiti correttamente.
Le esecuzioni di script e le richieste API non causano l'esecuzione degli trigger. Ad esempio, la chiamata a
FormResponse.submit()per inviare una nuova risposta al modulo non comporta l'esecuzione dell'attivatore di invio del modulo.Gli attivatori installabili vengono sempre eseguiti nell'account della persona che li ha creati. Ad esempio, se crei un attivatore di apertura installabile, questo viene eseguito quando il tuo collega apre il documento (se ha accesso in modifica), ma viene eseguito come 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, puoi creare un attivatore installabile per ogni account, con il risultato dell'invio di un'email da ogni account.
Un determinato account non può vedere gli attivatori installati da un secondo account, anche se il primo account può comunque attivarli.
Gli attivatori installabili sono soggetti ai limiti di quota degli attivatori di Apps Script.
Trigger basati sul tempo
Un attivatore basato sul tempo (chiamato anche attivatore dell'orologio) è simile a un cron job in Unix. Gli attivatori basati sul tempo consentono di eseguire gli script a un'ora specifica o a un intervallo ricorrente, con una frequenza che può variare da ogni minuto a una volta al mese. Tieni presente che un componente aggiuntivo può utilizzare un attivatore basato sul tempo al massimo una volta all'ora. L'ora potrebbe essere leggermente randomizzata: ad esempio, se crei un attivatore ricorrente alle 9:00, Apps Script sceglie un'ora tra le 9:00 e le 10:00, quindi mantiene questo orario coerente da un giorno all'altro in modo che trascorrano 24 ore prima che l'attivatore venga attivato 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
Gli attivatori basati su eventi installabili sono concettualmente simili ai
trigger semplici 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 qualsiasi utente con 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 l'attivatore, anche se un altro utente con accesso in modifica apre il foglio di lavoro.
Esistono diversi attivatori installabili per le applicazioni :
- Un attivatore open installabile viene eseguito quando un utente apre un foglio di lavoro, un documento o un modulo di cui ha l'autorizzazione di modifica.
- Un trigger di modifica installabile viene eseguito quando un utente modifica un valore in un foglio di lavoro.
- Un attivatore di modifica installabile viene eseguito quando un utente modifica la struttura stessa del foglio di lavoro, ad esempio aggiungendo un nuovo foglio o rimuovendo una colonna.
- Un trigger di invio del modulo installabile viene eseguito quando un utente risponde a un modulo. Esistono due versioni dell'attivatore di invio del modulo: una per Google Moduli e una per Fogli se il modulo viene inviato a un foglio di lavoro.
- Un attivatore di eventi di calendario installabile viene eseguito quando gli eventi di calendario di un utente vengono aggiornati, creati, modificati o eliminati.
Puoi utilizzare gli attivatori installabili negli 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 manualmente gli attivatori
Per creare manualmente un attivatore installabile nell'editor di script:
- 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 attivatore che vuoi creare.
- Fai clic su Salva.
Gestire gli trigger in modo programmatico
Puoi anche creare ed eliminare gli attivatori 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 uno che si attiva ogni lunedì alle 9:00 (nel fuso orario impostato per lo script).
L'esempio seguente mostra come creare un attivatore di apertura installabile per un
foglio di lavoro. Tieni presente che, a differenza di un semplice attivatore onOpen(), lo script per
l'attivatore installabile non deve essere associato al foglio di lavoro. Per creare questo trigger da uno script autonomo, sostituisci semplicemente SpreadsheetApp.getActive() con una chiamata a SpreadsheetApp.openById(id).
Per modificare tramite programmazione un attivatore installabile esistente, devi eliminarlo e crearne uno nuovo. Se hai già memorizzato l'ID di un attivatore, puoi eliminarlo passando l'ID come argomento alla funzione riportata di seguito.
Prima di creare un attivatore, ti consigliamo di verificare che la funzione associata disponga di tutte le autorizzazioni OAuth necessarie.
Errori negli attivatori
Quando viene attivato un attivatore installabile, ma la funzione genera un'eccezione o non viene eseguita correttamente, sullo schermo non viene visualizzato alcun messaggio di errore. Dopotutto, quando viene eseguito un attivatore basato sul tempo o un altro utente attiva il tuo attivatore di invio del modulo, potresti non essere nemmeno al computer.
Al contrario, Apps Script ti invia 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 è vincolato a un file di Fogli, Documenti o Moduli Google, l'email include anche un link a quel file. Questi link ti consentono di disattivare l'attivatore o modificare lo script per correggere il bug.
Per esaminare tutti gli attivatori associati al tuo Account Google e disattivare quelli che non ti servono più:
- Visita il sito
script.google.com. - A sinistra, fai clic su I miei attivatori.
Per eliminare un attivatore, fai clic su Altro > Elimina attivatore a destra dell'attivatore.
Trigger nei componenti aggiuntivi
Oltre agli attivatori installabili, puoi utilizzare gli attivatori manifest nei plug-in. Per saperne di più, consulta Scatenatori per i componenti aggiuntivi di Google Workspace.