Cette page a été traduite par l'API Cloud Translation.

Déclencheurs installables

Comme les déclencheurs simples, les déclencheurs installables permettent à Apps Script d'exécuter automatiquement une fonction lorsqu'un événement spécifique, tel que l'ouverture d'un document, se produit. Les déclencheurs installables offrent toutefois plus de flexibilité que les déclencheurs simples: ils peuvent appeler des services qui nécessitent une autorisation, offrent plusieurs types d'événements supplémentaires, y compris des déclencheurs basés sur l'heure (horloge), et peuvent être contrôlés de manière automatisée. Pour les déclencheurs simples et installables, Apps Script transmet à la fonction déclenchée un objet événement contenant des informations sur le contexte de l'événement.

Restrictions

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

Elles ne s'exécutent pas si un fichier est ouvert en lecture seule (lecture ou commentaire). Pour les scripts autonomes, les utilisateurs doivent disposer au minimum d'un accès en lecture au fichier de script pour que les déclencheurs s'exécutent correctement.
Les exécutions de script et les requêtes API n'entraînent pas l'exécution de déclencheurs. Par exemple, appeler FormResponse.submit() pour envoyer une nouvelle réponse de formulaire n'entraîne pas l'exécution du déclencheur d'envoi du formulaire.

Remarque :Form.submitGrades() fait exception à cette règle. Si votre code utilise un déclencheur onFormSubmit, l'appel de Form.submitGrades() déclenche la condition onFormSubmit et provoque une boucle infinie. Pour éviter la boucle infinie, ajoutez un code qui vérifie si les notes existent déjà avant d'appeler submitGrades().
Les déclencheurs installables s'exécutent toujours sous le compte de la personne qui les a créés. Par exemple, si vous créez un déclencheur ouvert installable, il s'exécute lorsque votre collègue ouvre le document (si votre collègue dispose d'un accès en écriture), mais s'exécute en tant que compte. Cela signifie que si vous créez un déclencheur pour envoyer un e-mail lorsqu'un document est ouvert, celui-ci est toujours envoyé à partir de votre compte, et pas nécessairement du compte qui a ouvert le document. Toutefois, vous pouvez créer un déclencheur installable pour chaque compte, ce qui entraînerait l'envoi d'un e-mail par compte.
Un compte donné ne peut pas voir les déclencheurs installés à partir d'un second compte, même si le premier compte peut toujours les activer.
Les déclencheurs installables sont soumis aux limites de quota d'Apps Script.

Déclencheurs temporels

Un déclencheur temporel (également appelé déclencheur d'horloge) est semblable à une tâche Cron dans Unix. Les déclencheurs temporels permettent aux scripts de s'exécuter à un moment précis ou à intervalles réguliers, toutes les minutes ou seulement une fois par mois. (Notez qu'un module complémentaire peut utiliser un déclencheur basé sur le temps une fois par heure tout au plus.) L'heure peut être légèrement aléatoire. Par exemple, si vous créez un déclencheur récurrent de 9h, Apps Script choisit une heure comprise entre 9h et 10h, puis maintient cette heure cohérente d'un jour à l'autre. Ainsi, 24 heures se sont écoulées avant que le déclencheur ne s'exécute à nouveau.

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

D'un point de vue conceptuel, les déclencheurs basés sur des événements sont semblables aux déclencheurs simples tels que onOpen(), mais ils peuvent répondre à des événements supplémentaires et se comportent 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 disposant d'un accès en modification, tout comme le simple déclencheur onOpen(). Toutefois, la version à installer peut appeler des services nécessitant une autorisation. La version installable s'exécute avec l'autorisation de l'utilisateur qui a créé le déclencheur, même si un autre utilisateur disposant d'un accès en modification ouvre la feuille de calcul.

Vous pouvez installer plusieurs déclencheurs Google Workspace pour les applications:

Un déclencheur open installable s'exécute lorsqu'un utilisateur ouvre une feuille de calcul, un document ou un formulaire qu'il est autorisé à modifier.
Un déclencheur edit installable s'exécute lorsqu'un utilisateur modifie une valeur dans une feuille de calcul.
Un déclencheur change installable s'exécute lorsqu'un utilisateur modifie la structure d'une feuille de calcul, par exemple en ajoutant une feuille ou en supprimant une colonne.
Un déclencheur soumettez un formulaire installable s'exécute lorsqu'un utilisateur répond à un formulaire. Il existe deux versions du déclencheur d'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 mis à jour, créés, modifiés ou supprimés.

Vous pouvez utiliser des déclencheurs installables dans des scripts autonomes et liés. Par exemple, un script autonome peut créer par programmation un déclencheur installable pour 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 scripts, procédez comme suit:

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

Gérer les déclencheurs par programmation

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

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

déclencheurs/déclencheurs.gs

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

déclencheurs/déclencheurs.gs

Afficher sur 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();
}

Pour modifier automatiquement un déclencheur installable existant, vous devez le supprimer et en créer un autre. Si vous avez déjà stocké l'ID d'un déclencheur, vous pouvez le supprimer en le transmettant en tant qu'argument à la fonction ci-dessous.

déclencheurs/déclencheurs.gs

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

Erreurs dans les déclencheurs

Lorsqu'un déclencheur installable s'exécute, mais que la fonction génère une exception ou ne parvient pas à s'exécuter correctement, aucun message d'erreur ne s'affiche à l'écran. En effet, lorsqu'un déclencheur temporel s'exécute ou qu'un autre utilisateur active votre déclencheur d'envoi de formulaire, vous ne vous trouvez peut-être pas sur votre ordinateur.

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

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

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

Accédez à script.google.com.
À gauche, cliquez sur Mes déclencheurs.
Pour supprimer un déclencheur, cliquez sur Plus > Supprimer le déclencheur à droite du déclencheur.

Remarque :Les déclencheurs simples comme onOpen() ne peuvent pas être désactivés depuis cette page. Vous devez modifier le script approprié et supprimer ou renommer la fonction onOpen().

Déclencheurs installables dans les modules complémentaires

Pour en savoir plus sur l'utilisation de déclencheurs installables dans les modules complémentaires, consultez Déclencheurs de module complémentaire.