Trigger installabili

Come i trigger semplici, i trigger installabili consentono ad Apps Script di eseguire automaticamente una funzione quando si verifica un determinato evento, ad esempio 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.

Nota: per saperne di più su come utilizzare i trigger nei componenti aggiuntivi, consulta la pagina 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 affinché i trigger vengano eseguiti correttamente.

• 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 comporta l'esecuzione del trigger di invio del modulo.

  Nota: 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, potresti creare un trigger installabile per ogni account, il che comporterebbe 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 trigger basato sul tempo (chiamato anche trigger 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. Tieni presente che un componente aggiuntivo può utilizzare un trigger basato sul tempo al massimo una volta all'ora. L'ora potrebbe essere leggermente randomizzata. Ad esempio, se crei un trigger ricorrente alle 9:00, Apps Script sceglie un orario tra le 9:00 e le 10:00, quindi mantiene questo orario costante 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 Fogli si attiva ogni volta che il foglio di lavoro viene aperto da qualsiasi utente con accesso in modifica, proprio come il trigger semplice 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 trigger open 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.

Puoi utilizzare i trigger installabili negli script autonomi e associati. Ad esempio, uno script autonomo può creare in modo programmatico 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:

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

Puoi anche creare ed eliminare 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 si attiva ogni 6 ore e uno che si attiva ogni lunedì alle 9:00 (nel fuso orario impostato per lo script).

triggers/triggers.gs

Visualizza su GitHub

/**
 * 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. 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, sostituisci SpreadsheetApp.getActive() con una chiamata a SpreadsheetApp.openById(id).

triggers/triggers.gs

Visualizza su GitHub

/**
 * 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 hai memorizzato in precedenza l'ID di un trigger, puoi eliminarlo passando l'ID come argomento alla funzione riportata di seguito.

triggers/triggers.gs

Visualizza su GitHub

/**
 * 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, ti consigliamo di verificare 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, non viene visualizzato un messaggio di errore sullo schermo. 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 ti invia invece un'email come la seguente:

From: [e-mail]
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 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.

Nota: i trigger installabili creati dai componenti aggiuntivi non inviano agli utenti queste notifiche via email.

Per rivedere 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.

   Nota: gli attivatori semplici come onOpen() non possono essere disattivati da questa pagina. Devi invece modificare lo script appropriato e rimuovere o rinominare la funzione onOpen().

Trigger nei componenti aggiuntivi

Oltre ai trigger installabili, puoi utilizzare i trigger manifest nei componenti aggiuntivi. Per saperne di più, vedi Trigger per i componenti aggiuntivi Google Workspace.