Trigger installabili

Come i trigger semplici, i trigger installabili consentono a Google Apps Script di eseguire automaticamente una funzione quando si verifica un determinato evento, come l'apertura di un documento. I trigger installabili, tuttavia, offrono maggiore flessibilità rispetto ai trigger semplici: possono chiamare servizi che richiedono autorizzazione, offrono diversi tipi di eventi aggiuntivi, inclusi i trigger basati sul tempo (orologio), e possono essere controllati a livello di programmazione. Per gli attivatori semplici e installabili, Apps Script passa alla funzione attivata un oggetto evento che contiene informazioni sul contesto in cui si è verificato l'evento.

Per saperne di più su come utilizzare i trigger nei componenti aggiuntivi, vedi Trigger per i componenti aggiuntivi di Google Workspace.

Restrizioni

Anche se i trigger installabili offrono maggiore flessibilità rispetto ai trigger 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 di script per l'esecuzione corretta dei trigger.

  • Le esecuzioni di script e le richieste API non causano l'esecuzione dei trigger. Ad esempio, la chiamata FormResponse.submit() per inviare una nuova risposta al modulo non attiva l'esecuzione del trigger di invio del modulo.

    Un'eccezione a questa limitazione è Form.submitGrades(). Se il tuo codice utilizza un trigger onFormSubmit, la chiamata a Form.submitGrades() attiva la condizione onFormSubmit e causa un ciclo infinito. Per evitare il ciclo infinito, aggiungi codice che controlli se i voti esistono già prima di chiamare submitGrades().

  • I trigger installabili vengono sempre eseguiti con l'account della persona che li ha creati. Ad esempio, se crei un trigger aperto 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 trigger 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 trigger installabile per ogni account, il che comporta l'invio di un'email da ogni account.

  • Un determinato account non può visualizzare i trigger 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 attivatore basato sul tempo (chiamato anche attivatore orologio) è simile a un cron job in Unix. I trigger basati sul tempo consentono l'esecuzione degli script a un'ora specifica o a intervalli ricorrenti, con una frequenza che può variare da una volta al minuto a una volta al mese. Un componente aggiuntivo può utilizzare un trigger basato sul tempo al massimo una volta all'ora. L'ora potrebbe essere leggermente casuale. Ad esempio, se crei un trigger ricorrente alle 9:00, Apps Script sceglie un orario compreso tra le 9:00 e le 10:00, quindi mantiene la tempistica coerente di giorno in giorno, in modo che trascorrano 24 ore prima che il trigger venga attivato di nuovo.

Trigger basati su eventi

I trigger 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, il trigger open installabile per Google Sheets si attiva ogni volta che il foglio di lavoro viene aperto da qualsiasi utente con accesso in modifica, proprio come il trigger onOpen() semplice. 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 applicazioni Google Workspace:

  • Un trigger apertura installabile viene eseguito quando un utente apre un foglio di lavoro, un documento o un modulo che ha l'autorizzazione a modificare.
  • Un trigger modifica installabile viene eseguito quando un utente modifica un valore in un foglio di lavoro.
  • Un trigger modifica installabile viene eseguito quando un utente modifica la struttura di un foglio di lavoro, ad esempio aggiungendo un nuovo foglio o rimuovendo una colonna.
  • Un trigger invio modulo installabile viene eseguito quando un utente risponde a un modulo. Esistono due versioni del trigger di invio del modulo, una per Moduli Google e una per Fogli se il modulo viene inviato a un foglio di lavoro.
  • Un trigger evento di calendario installabile viene eseguito quando gli eventi di calendario di un utente vengono aggiornati, creati, modificati o eliminati.

Gli attivatori installabili sono disponibili negli script autonomi e associati. Ad esempio, uno script autonomo può creare a livello di programmazione un trigger installabile per un file Fogli Google arbitrario chiamando TriggerBuilder.forSpreadsheet(key) e passando l'ID del foglio di lavoro.

Gestire manualmente i trigger

Per creare manualmente un trigger installabile nell'editor di script, segui questi passaggi:

  1. Apri il progetto Apps Script.
  2. A sinistra, fai clic su Attivatori .
  3. In basso a destra, fai clic su Aggiungi trigger.
  4. Seleziona e configura il tipo di trigger che vuoi creare.
  5. Fai clic su Salva.

Gestire i trigger in modo programmatico

Crea ed elimina trigger in modo programmatico con il servizio Script. Inizia chiamando ScriptApp.newTrigger(functionName), che restituisce un TriggerBuilder.

L'esempio seguente mostra come creare due trigger basati sul tempo: uno che viene attivato ogni 6 ore e uno che viene attivato ogni lunedì alle 9:00 (nel fuso orario impostato per lo script).

triggers/triggers.gs
/**
 * Creates two time-driven triggers.
 * @see https://developers.google.com/apps-script/guides/triggers/installable#time-driven_triggers
 */
function createTimeDrivenTriggers() {
  // Trigger every 6 hours.
  ScriptApp.newTrigger("myFunction").timeBased().everyHours(6).create();
  // Trigger every Monday at 09:00.
  ScriptApp.newTrigger("myFunction")
    .timeBased()
    .onWeekDay(ScriptApp.WeekDay.MONDAY)
    .atHour(9)
    .create();
}

L'esempio successivo mostra come creare un attivatore open installabile per un foglio di lavoro. 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, sostituisci SpreadsheetApp.getActive() con una chiamata a SpreadsheetApp.openById(id).

triggers/triggers.gs
/**
 * Creates a trigger for when a spreadsheet opens.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function createSpreadsheetOpenTrigger() {
  const ss = SpreadsheetApp.getActive();
  ScriptApp.newTrigger("myFunction").forSpreadsheet(ss).onOpen().create();
}

Per modificare in modo programmatico un trigger installabile esistente, devi eliminarlo e crearne uno nuovo. Se in precedenza hai memorizzato l'ID di un trigger, eliminalo passando l'ID come argomento alla seguente funzione.

triggers/triggers.gs
/**
 * Deletes a trigger.
 * @param {string} triggerId The Trigger ID.
 * @see https://developers.google.com/apps-script/guides/triggers/installable
 */
function deleteTrigger(triggerId) {
  // Loop over all triggers.
  const allTriggers = ScriptApp.getProjectTriggers();
  for (let index = 0; index < allTriggers.length; index++) {
    // If the current trigger is the correct one, delete it.
    if (allTriggers[index].getUniqueId() === triggerId) {
      ScriptApp.deleteTrigger(allTriggers[index]);
      break;
    }
  }
}

Prima di creare un trigger, verifica che la funzione associata disponga di tutte le autorizzazioni OAuth necessarie.

Errori negli attivatori

Quando viene attivato un trigger installabile, ma la funzione genera un'eccezione o non viene eseguita correttamente, sullo schermo non viene visualizzato alcun messaggio di errore. Dopo tutto, quando viene eseguito un trigger basato sul tempo o un altro utente attiva il trigger di invio del modulo, potresti non essere nemmeno al computer.

Apps Script invia invece un'email come la seguente:

From: noreply-apps-scripts-notifications@google.com
Subject: Summary of failures for 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 il trigger. Se lo script è associato a un file Fogli, Documenti o Moduli Google, l'email include anche un link a quel file. Questi link ti consentono di disattivare il trigger o modificare lo script per correggere il bug.

Per risolvere gli errori nello script, fai clic sul link nell'email di notifica per aprire il progetto di script. Una volta aperto il progetto, visualizza i log di esecuzione facendo clic su Esecuzioni nel pannello di navigazione a sinistra. I log mostrano le esecuzioni non riuscite e includono messaggi di errore per aiutarti a diagnosticare e risolvere il problema.

I trigger installabili creati dai componenti aggiuntivi non inviano agli utenti queste notifiche via email.

Per esaminare tutti i trigger associati al tuo Account Google e disattivare quelli che non ti servono più, segui questi passaggi:

  1. Visita il sito script.google.com.
  2. A sinistra, fai clic su I miei attivatori.
  3. Per eliminare un trigger, fai clic su Altro a destra del trigger > Elimina trigger.

Se un trigger viene disattivato, vengono disattivate anche le relative notifiche di errore. Le notifiche di errore sono parte integrante di un trigger attivo. Di conseguenza, per interrompere la ricezione di tutte le notifiche di errore per un trigger specifico, disattiva o elimina il trigger stesso. Mentre un trigger è attivo, puoi regolare solo la frequenza di queste notifiche.

 Simple triggers like `onOpen()` can't be deactivated from this
 page; instead, edit the appropriate script and remove or rename
 the `onOpen()` function.

Trigger nei componenti aggiuntivi

Oltre agli attivatori installabili, utilizza gli attivatori manifest nei componenti aggiuntivi. Per saperne di più, vedi Trigger per i componenti aggiuntivi Google Workspace.