Trigger installabili

Come i semplici attivatori, gli attivatori installabili consentono ad Apps Script di eseguire automaticamente una funzione quando si verifica un determinato evento, come l'apertura di un documento. Gli attivatori installabili, tuttavia, offrono maggiore flessibilità rispetto agli attivatori semplici: possono chiamare servizi che richiedono autorizzazione, offrono diversi tipi di eventi, inclusi attivatori basati su tempo (orologio) e possono essere controllati in modo programmatico. Sia per gli attivatori semplici che per quelli installabili, Apps Script trasmette alla funzione attivata un oggetto evento contenente informazioni sul contesto in cui si è verificato l'evento.

Nota: per informazioni su come utilizzare gli attivatori installabili nei progetti dei componenti aggiuntivi, consulta l'articolo Trigger dei componenti aggiuntivi.

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). Affinché gli script autonomi funzionino correttamente, gli utenti devono disporre almeno dell'accesso in visualizzazione al file dello script.

• Le esecuzioni degli script e le richieste API non causano l'esecuzione dei trigger. Ad esempio, chiamare FormResponse.submit() per inviare una nuova risposta non comporta l'esecuzione dell'attivazione dell'invio del modulo.

  Nota: un'eccezione a questa limitazione è Form.submitGrades(). Se il codice utilizza un attivatore onFormSubmit, la chiamata Form.submitGrades() attiva la condizione onFormSubmit e provoca un loop infinito. Per evitare il loop infinito, aggiungi un codice che verifichi se i voti esistono già prima di chiamare submitGrades().

• I trigger installabili vengono sempre eseguiti nell'account della persona che li ha creati. Ad esempio, se crei un trigger aperto installabile, questo viene eseguito quando il collega apre il documento (se il collega dispone dell'accesso in modifica), ma viene eseguito come account. Ciò significa che se crei un trigger per inviare un'email all'apertura di un documento, quest'ultima viene sempre inviata dal tuo account, non necessariamente da quello che ha aperto il documento. Tuttavia, potresti creare un trigger installabile per ogni account, con il conseguente invio di un'email da ogni account.

• Un determinato account non può visualizzare gli attivatori installati da un secondo account, anche se il primo account può comunque attivare tali attivatori.

• I trigger installabili sono soggetti ai limiti di quota dei trigger di Apps Script.

Attivatori basati sul tempo

Un trigger basato sul tempo (chiamato anche trigger dell'orologio) è simile a un cron job in Unix. I trigger basati sul tempo consentono agli script di essere eseguiti in un determinato momento o a intervalli ricorrenti, con la frequenza minima di ogni minuto o una volta al mese. Tieni presente che un componente aggiuntivo può utilizzare un attivatore basato sul tempo una volta all'ora al massimo. L'ora potrebbe essere leggermente casuale: ad esempio, se crei un trigger ricorrente delle 9:00, Apps Script sceglie un orario tra le 9:00 e le 10:00 e mantiene il tempo coerente da un giorno all'altro in modo che trascorrano 24 ore prima che il trigger si riavvii.

Attivatori basati su eventi

Gli attivatori basati su eventi installabili sono concettualmente simili ai semplici attivatori come onOpen(), ma possono rispondere a eventi aggiuntivi e si comportano in modo diverso.

Ad esempio, l'attivatore aperto installabile per Fogli Google si attiva ogni volta che il foglio di lavoro viene aperto da qualsiasi utente che dispone dell'accesso in modifica, proprio come il semplice trigger onOpen(). Tuttavia, la versione installabile può chiamare i 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 attivatori installabili per Google Workspace le applicazioni:

• Un attivatore open installabile viene eseguito quando un utente apre un foglio di lavoro, documento o modulo che è autorizzato a modificare.
• Un attivatore edit installabile viene eseguito quando un utente modifica un valore in un foglio di lavoro.
• Un attivatore di change 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 Invio del modulo installabile viene eseguito quando un utente risponde a un modulo. Esistono due versioni dell'attivatore Invio al modulo, una per Google Forms 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 di calendario di un utente vengono aggiornati, creati, modificati o eliminati.

Puoi utilizzare i trigger installabili negli script autonomi e in quelli associati. Ad esempio, uno script autonomo può creare in modo programmatico un attivatore installabile per un file di Fogli Google arbitrario chiamando TriggerBuilder.forSpreadsheet(key) e trasmettendo l'ID del foglio di lavoro.

Gestione manuale dei trigger

Per creare manualmente un trigger installabile nell'editor di script, procedi nel seguente modo:

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.

Gestione degli attivatori in modo programmatico

Puoi anche creare ed eliminare trigger in modo programmatico con il servizio script. Per iniziare, chiama ScriptApp.newTrigger(functionName), che restituisce un elemento TriggerBuilder.

L'esempio seguente mostra come creare due attivatori basati sul tempo: uno che si attiva ogni 6 ore e uno che si attiva ogni lunedì alle 9.00 (nel fuso orario impostato dallo script).

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

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

trigger/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;
    }
  }
}

Errori negli attivatori

Quando viene attivato un trigger installabile, ma la funzione genera un'eccezione o l'esecuzione non riesce 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 tuo trigger di invio del modulo, potresti anche non essere al computer.

Invece, Apps Script ti invia un'email come questa:

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 l'attivatore. Se lo script è vincolato 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 di modificare lo script per correggere il bug.

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

Per esaminare tutti gli attivatori associati al tuo Account Google e disattivare quelli che non ti servono più:

1. Vai a script.google.com.
2. A sinistra, fai clic su I miei attivatori.

3. Per eliminare un attivatore, a destra dell'attivatore fai clic su Altro > Elimina attivatore.

   Nota: i trigger semplici come onOpen() non possono essere disattivati da questa pagina; devi modificare lo script appropriato e rimuovere o rinominare la funzione onOpen().

Trigger installabili nei componenti aggiuntivi

Per ulteriori informazioni sull'utilizzo degli attivatori installabili nei componenti aggiuntivi, consulta l'articolo Trigger dei componenti aggiuntivi.