Trigger installabili

Come gli attivatori semplici, quelli 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 una maggiore flessibilità rispetto a trigger semplici: possono chiamare i servizi che richiedono l'autorizzazione, offrono diversi tipi aggiuntivi di eventi, inclusi attivatori a tempo (clock), e possono essere controllati in modo programmatico. Per trigger semplici e installabili, Apps Script trasmette alla funzione attivata un oggetto evento contenente informazioni sul contesto in cui si è verificato l'evento.

Restrizioni

Anche se gli attivatori installabili offrono maggiore flessibilità rispetto ai semplici attivatori, 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, chiamare FormResponse.submit() per inviare una nuova risposta del 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 un collega apre il documento (se dispone dell'accesso in modifica), ma viene eseguito come account del tuo account. Ciò significa che se crei un attivatore per inviare un'email all'apertura di 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 ciascun account, che comporterà l'invio di un'email da ciascun account.

  • Un determinato account non può visualizzare gli attivatori installati da un secondo account, anche se il primo 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 di orologio) è simile a un cron job in Unix. I trigger basati sul tempo consentono l'esecuzione degli script in un momento specifico o in un intervallo ricorrente, con una frequenza di ogni minuto o 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 casuale: ad esempio, se crei un attivatore ricorrente alle 9:00, Apps Script sceglie un orario compreso tra le 09:00 e le 10:00, quindi mantiene l'orario coerente di giorno in giorno in modo che avvengano 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 basati su eventi installabili sono concettualmente simili ai attivatori semplici come onOpen(), ma possono rispondere a eventi aggiuntivi e comportarsi 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 con accesso in modifica, come il semplice attivatore onOpen(). Tuttavia, la versione installabile può chiamare servizi che richiedono l'autorizzazione. La versione installabile viene eseguita con l'autorizzazione dell'utente che ha creato l'attivatore, anche se il foglio di lavoro viene aperto da un altro utente con accesso in modifica.

Esistono diversi trigger installabili per le Google Workspace applicazioni:

  • Un trigger aperto installabile viene eseguito quando un utente apre un foglio di lavoro, un documento o un modulo per il quale è autorizzato a modificare.
  • 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 di un foglio di lavoro, ad esempio aggiungendo un nuovo foglio o rimuovendo una colonna.
  • Un attivatore installabile di invio modulo 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 trigger 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 in script autonomi e 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.

Gestire gli attivatori manualmente

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 attivatore.
  4. Seleziona e configura il tipo di trigger da creare.
  5. Fai clic su Salva.

Gestisci gli attivatori in modo programmatico

Puoi anche creare ed eliminare i trigger a livello di programmazione con il servizio di script. Inizia chiamando ScriptApp.newTrigger(functionName), che restituisce un TriggerBuilder.

L'esempio seguente mostra come creare due attivatori basati sul tempo: uno che si attiva ogni 6 ore e l'altro 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 seguente mostra come creare un trigger aperto installabile per un foglio di lavoro. Tieni presente che, a differenza di un attivatore onOpen() semplice, lo script per l'attivatore 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 hai già archiviato l'ID di un trigger, puoi eliminarlo passandolo come argomento alla funzione seguente.

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

Errori negli attivatori

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. Dopotutto, quando viene eseguito un trigger basato sul tempo o un altro utente attiva l'attivatore Invio modulo, potresti non essere nemmeno al computer.

Apps Script ti invia invece un'email simile alla 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 è associato 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 non più necessari:

  1. Visita il sito script.google.com.
  2. A sinistra, fai clic su I miei attivatori.

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

Attivatori installabili nei componenti aggiuntivi

Per ulteriori informazioni sull'utilizzo dei trigger installabili nei componenti aggiuntivi, consulta la pagina Trigger dei componenti aggiuntivi.