Déclencheurs installables

Comme les déclencheurs simples, les déclencheurs installables permettent Apps Script exécutent automatiquement une fonction lorsqu'un événement, comme l'ouverture d'un document, se produit. Les déclencheurs installables, quant à eux, offrent plus plus flexible que de simples déclencheurs: ils peuvent appeler services qui nécessitent autorisation, ils proposent plusieurs types d'événements supplémentaires, y compris les événements à durée déterminée (horloge), et peuvent être contrôlés de façon programmatique. Pour les simples et déclencheurs installables, Apps Script transmet la fonction déclenchée une Un objet événement contenant des informations sur le contexte dans lequel l'événement s'est produit.

Restrictions

Même si les déclencheurs installables offrent plus de flexibilité que les déclencheurs simples, ils sont toujours soumis à plusieurs restrictions:

  • Elles ne s'exécutent pas si un fichier est ouvert en lecture seule (lecture ou commentaire). Pour des scripts autonomes, les utilisateurs ont au moins besoin d'un accès en lecture au fichier de script pour que les déclencheurs s'exécutent correctement.

  • Les exécutions de scripts et les requêtes API n'entraînent pas l'exécution de déclencheurs. Par exemple, Appel en cours FormResponse.submit() pour envoyer une nouvelle réponse au formulaire n'entraîne pas l'exécution du déclencheur d'envoi du formulaire.

  • Les déclencheurs installables s'exécutent toujours sous le compte de la personne qui a créé de l'IA générative. Par exemple, si vous créez un déclencheur ouvert installable, il exécute Lorsque votre collègue ouvre le document (s'il est autorisé à le modifier), mais il fonctionne comme votre compte. Cela signifie que si vous créez un déclencheur envoyer un e-mail lorsqu'un document est ouvert, l'e-mail est toujours envoyé depuis votre compte, et pas nécessairement celui qui a ouvert le document. Toutefois, vous pouvez créer un déclencheur installable pour chaque compte, dans un e-mail envoyé depuis chaque compte.

  • Un compte donné ne peut pas voir les déclencheurs installés à partir d'un second compte, même même si le premier compte peut toujours les activer.

  • Les déclencheurs installables sont soumis aux déclencheurs Apps Script limites de quota.

Déclencheurs basés sur l'heure

Un déclencheur temporel (également appelé déclencheur d'horloge) est semblable à un déclencheur tâche Cron sous Unix. Les déclencheurs temporels permettent scripts exécutés à un moment précis ou à intervalles réguliers, selon la fréquence chaque minute ou une fois par mois, par exemple. Notez qu'un module complémentaire utiliser un déclencheur temporel une fois par heure au maximum.) Le temps peut être un peu de manière aléatoire. Par exemple, si vous créez un déclencheur récurrent à 9h00, Apps Script choisit une heure entre 9 h et 10 h, puis conserve cette synchronisation d'un jour à l'autre, de sorte que 24 heures s'écoulent le déclencheur s'active à nouveau.

Voici un exemple de Application Google Chat qui publie un message toutes les minutes sur chaque espace dans lequel se trouve l'application:

// 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),
  });
}

Déclencheurs basés sur des événements

D'un point de vue conceptuel, les déclencheurs installables basés sur des événements déclencheurs simples comme onOpen(), mais ils peuvent répondre à des événements supplémentaires et se comporter différemment.

Par exemple, le déclencheur ouvert installable pour Google Sheets s'active chaque fois que la feuille de calcul est ouverte par un utilisateur autorisé à la modifier, tout comme le simple déclencheur onOpen(). Toutefois, la version installable peut à appeler des services qui nécessitent autorisation. Le composant installable s'exécute avec l'autorisation de l'utilisateur qui a créé le déclencheur, si un autre utilisateur autorisé à la modifier ouvre la feuille de calcul.

Il existe plusieurs déclencheurs installables pour Google Workspace applications:

  • Un déclencheur open installable s'exécute lorsqu'un utilisateur ouvre une feuille de calcul. document ou formulaire qu'ils sont autorisés à modifier.
  • Un déclencheur edit installable s'exécute lorsqu'un utilisateur modifie une valeur dans un feuille de calcul.
  • Un déclencheur de modification installable s'exécute lorsqu'un utilisateur modifie la structure d'un feuille de calcul proprement dite, par exemple en ajoutant une nouvelle feuille ou en supprimant une .
  • Un déclencheur form submit installable s'exécute lorsqu'un utilisateur répond à un formulaire. Il existe deux versions du déclencheur "Envoi de formulaire" : une pour Google Forms et une pour Sheets si le formulaire est envoyé dans une feuille de calcul.
  • Un déclencheur d'événement d'agenda installable s'exécute lorsque les événements d'agenda d'un utilisateur sont mises à jour, créées, modifiées ou supprimées.

Vous pouvez utiliser des déclencheurs installables dans des scripts autonomes et liés. Par exemple, un script autonome peut créer de manière automatisée un déclencheur installable pour une un fichier Google Sheets arbitraire en appelant TriggerBuilder.forSpreadsheet(key) et en transmettant l'ID de la feuille de calcul.

Gérer les déclencheurs manuellement

Pour créer manuellement un déclencheur installable dans l'éditeur de script, procédez comme suit:

  1. Ouvrez votre projet Apps Script.
  2. À gauche, cliquez sur Déclencheurs .
  3. En bas à droite, cliquez sur Ajouter un déclencheur.
  4. Sélectionnez et configurez le type de déclencheur que vous souhaitez créer.
  5. Cliquez sur Enregistrer.

Gérer les déclencheurs de manière programmatique

Vous pouvez également créer et supprimer des déclencheurs de manière automatisée à l'aide de la commande Service de script. Commencez par appeler ScriptApp.newTrigger(functionName), qui renvoie un TriggerBuilder

L'exemple suivant montre comment créer deux déclencheurs temporels : un déclencheur se déclenche toutes les six heures et une autre se déclenche tous les lundis à 9h (dans le fuseau horaire dans lequel votre script est défini).

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'exemple suivant montre comment créer un déclencheur ouvert installable pour feuille de calcul. Notez que, contrairement à un déclencheur onOpen() simple, le script le déclencheur installable n'a pas besoin d'être lié à la feuille de calcul. Pour créer à partir d'un script autonome, il vous suffit de remplacer SpreadsheetApp.getActive() avec un appel au 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();
}

Pour modifier de manière programmatique un déclencheur installable existant, vous devez le supprimer et créez-en une autre. Si vous avez déjà stocké l'ID d'un déclencheur, vous pouvez supprimez-la en transmettant l'ID en tant qu'argument à la fonction ci-dessous.

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

Erreurs dans les déclencheurs

Lorsqu'un déclencheur installable s'exécute, mais que la fonction génère une exception ou sinon l'exécution échoue, aucun message d'erreur ne s'affiche sur votre l'écran. Après tout, lorsqu'un déclencheur temporel s'exécute ou qu'un autre utilisateur s'active déclencheur d’envoi de formulaire, vous ne serez peut-être même pas devant votre ordinateur.

À la place, Apps Script vous envoie un e-mail semblable à celui-ci:

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'e-mail contient un lien permettant de désactiver ou de reconfigurer le déclencheur. Si le est lié vers Google Sheets, Docs ou Forms l'e-mail contient également un lien vers ce fichier. Ces liens vous permettent désactivez le déclencheur ou modifiez le script pour corriger le bug.

Examiner tous les déclencheurs associés à votre compte Google et désactivez les déclencheurs dont vous n'avez plus besoin, procédez comme suit:

  1. Accédez à script.google.com.
  2. À gauche, cliquez sur Mes déclencheurs.

  3. Pour supprimer un déclencheur, cliquez sur Plus à droite de celui-ci > Supprimer le déclencheur

Déclencheurs dans les modules complémentaires

En plus des déclencheurs installables, vous pouvez utiliser des déclencheurs de manifeste des modules complémentaires. Pour plus d'informations, voir Déclencheurs pour les modules complémentaires Google Workspace