Comme les déclencheurs simples, les déclencheurs installables permettent à Apps Script d'exécuter une fonction automatiquement lorsqu'un certain événement, 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 nécessitant une autorisation, ils proposent plusieurs types d'événements supplémentaires, tels que des déclencheurs basés sur l'heure, et ils peuvent être contrôlés de manière programmatique. Pour les déclencheurs simples et installables, Apps Script transmet à la fonction déclenchée un objet d'événement contenant des informations sur le contexte dans lequel l'événement s'est produit.
Restrictions
Bien que les déclencheurs installables offrent plus de flexibilité que les déclencheurs simples, ils sont toujours soumis à plusieurs restrictions:
- Elles ne sont pas exécutées si un fichier est ouvert en lecture seule (lecture ou commentaire). Pour les scripts autonomes, les utilisateurs doivent au moins disposer 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 des déclencheurs. Par exemple, l'appel de
FormResponse.submit()pour envoyer une nouvelle réponse à un 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 les a créés. Par exemple, si vous créez un déclencheur d'ouverture installable, il s'exécute lorsque votre collègue ouvre le document (si votre collègue dispose d'un accès en modification), mais il 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, 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, ce qui entraînerait l'envoi d'un e-mail depuis chaque compte.
Un compte donné ne peut pas voir les déclencheurs installés à partir d'un deuxième compte, même si le premier peut toujours les activer.
Les déclencheurs installables sont soumis aux limites de quota des déclencheurs Apps Script.
Déclencheurs temporels
Un déclencheur basé sur le temps (également appelé déclencheur d'horloge) est semblable à une tâche Cron dans Unix. Les déclencheurs basés sur le temps permettent aux scripts de s'exécuter à un moment donné ou à un intervalle récurrent, autant de fois que toutes les minutes ou une fois par mois. Notez qu'un module complémentaire peut utiliser un déclencheur basé sur l'heure au maximum une fois par heure. L'heure peut être légèrement aléatoire. Par exemple, si vous créez un déclencheur récurrent à 9h, Apps Script choisit une heure comprise entre 9h et 10h, puis s'assure que cette heure est cohérente d'un jour à l'autre afin que 24 heures s'écoulent avant que le déclencheur ne s'active à nouveau.
Voici un exemple d'application Google Chat qui publie un message toutes les minutes dans chaque espace où 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 les événements
Les déclencheurs installables basés sur des événements sont conceptuellement semblables aux déclencheurs simples comme onOpen(), mais ils peuvent répondre à des événements supplémentaires et se comportent différemment.
Par exemple, le déclencheur d'ouverture 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(). Cependant, la version installable 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 de droits de modification ouvre la feuille de calcul.
Il existe plusieurs déclencheurs installables pour les applicationsGoogle Workspace :
- 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 de modification installable s'exécute lorsqu'un utilisateur modifie la structure d'une feuille de calcul elle-même, par exemple en ajoutant une nouvelle feuille ou en supprimant une colonne.
- Un déclencheur installable envoi de formulaire 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 autre pour Sheets si le formulaire est envoyé via 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, c'est-à-dire 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 de manière programmatique 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 script, 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 de manière programmatique
Vous pouvez également créer et supprimer des déclencheurs de manière automatisée avec le service Script. Commencez par appeler ScriptApp.newTrigger(functionName), qui renvoie un TriggerBuilder.
L'exemple suivant montre comment créer deux déclencheurs basés sur l'heure : un qui se déclenche toutes les six heures et un autre tous les lundis à 9h (dans le fuseau horaire défini pour votre script).
L'exemple suivant montre comment créer un déclencheur d'ouverture installable pour une feuille de calcul. Notez que, contrairement à un déclencheur onOpen() simple, 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, remplacez simplement SpreadsheetApp.getActive() par un appel à SpreadsheetApp.openById(id).
Pour modifier un déclencheur installable de manière programmatique, 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 transmettant l'ID en tant qu'argument à la fonction ci-dessous.
Erreurs dans les déclencheurs
Lorsqu'un déclencheur installable s'exécute, mais que la fonction génère une exception ou échoue à s'exécuter correctement, aucun message d'erreur ne s'affiche à l'écran. Après tout, lorsqu'un déclencheur basé sur l'heure s'exécute ou qu'un autre utilisateur active votre déclencheur d'envoi de formulaire, il se peut que vous ne soyez même pas devant votre ordinateur.
Apps Script vous envoie à la place 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 script est lié à un fichier Google Sheets, Docs ou Forms, l'e-mail contient é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, à droite du déclencheur, cliquez sur Plus > Supprimer le déclencheur.
Déclencheurs à installer dans les modules complémentaires
Pour en savoir plus sur l'utilisation de déclencheurs installables dans les modules complémentaires, consultez la section Déclencheurs de modules complémentaires.