Objets d'événement

Les déclencheurs simples et les déclencheurs installables permettent à Apps Script d'exécuter automatiquement une fonction si un événement particulier se produit. Lorsqu'un déclencheur se déclenche, Apps Script transmet à la fonction un objet d'événement en tant qu'argument, généralement appelé e. L'objet d'événement contient des informations sur le contexte ayant déclenché le déclencheur. Par exemple, l'exemple de code ci-dessous montre un déclencheur onEdit(e) simple pour un script Google Sheets qui utilise l'objet d'événement pour déterminer quelle cellule a été modifiée.

function onEdit(e){
  // Set a comment on the edited cell to indicate when it was changed.
  var range = e.range;
  range.setNote('Last modified: ' + new Date());
}

Cette page décrit les champs de l'objet événement pour différents types de déclencheurs.

Les événements générés par des déclencheurs installables contiennent un triggerUid qui identifie le déclencheur ayant généré l'événement. Cela est utile pour les scripts qui comportent plusieurs déclencheurs installables.

Événements Google Sheets

Les différents déclencheurs spécifiques à Google Sheets permettent aux scripts de répondre aux actions d'un utilisateur dans une feuille de calcul.

Ouvrir (simple et installable)
authMode	Valeur de l'énumération ScriptApp.AuthMode. LIMITED
source	Objet Spreadsheet représentant le fichier Google Sheets auquel le script est lié. Spreadsheet
triggerUid	ID du déclencheur ayant généré cet événement (déclencheurs installables uniquement). 4034124084959907503
user	Objet User représentant l'utilisateur actif, le cas échéant (selon un ensemble complexe de restrictions de sécurité). [e-mail]

Modifier (installable)
authMode	Valeur de l'énumération ScriptApp.AuthMode. FULL
changeType	Le type de modification (EDIT, INSERT_ROW, INSERT_COLUMN, REMOVE_ROW, REMOVE_COLUMN, INSERT_GRID, REMOVE_GRID, FORMAT ou OTHER) INSERT_ROW
source	Objet Spreadsheet représentant le fichier Google Sheets auquel le script est lié. Spreadsheet
triggerUid	ID du déclencheur ayant généré cet événement. 4034124084959907503
user	Objet User représentant l'utilisateur actif, le cas échéant (selon un ensemble complexe de restrictions de sécurité). [e-mail]

Modifier (simple et installable)
authMode	Valeur de l'énumération ScriptApp.AuthMode. LIMITED
oldValue	Valeur de la cellule avant la modification, le cas échéant. Disponible uniquement si la plage modifiée est une seule cellule. Valeur non définie si la cellule ne contenait pas de contenu précédent. 1234
range	Un objet Range, représentant la cellule ou la plage de cellules modifiées. Range
source	Objet Spreadsheet représentant le fichier Google Sheets auquel le script est lié. Spreadsheet
triggerUid	ID du déclencheur ayant généré cet événement (déclencheurs installables uniquement). 4034124084959907503
user	Objet User représentant l'utilisateur actif, le cas échéant (selon un ensemble complexe de restrictions de sécurité). [e-mail]
value	Nouvelle valeur de la cellule après la modification. Disponible uniquement si la plage modifiée est une seule cellule. 10

Envoi du formulaire (installable)
Attention:Veillez à utiliser ce déclencheur d'envoi de formulaire avec SpreadsheetTriggerBuilder.
authMode	Valeur de l'énumération ScriptApp.AuthMode. FULL
namedValues	Objet contenant les noms et valeurs des questions de l'envoi du formulaire. { 'First Name': ['Jane'], 'Timestamp': ['6/7/2015 20:54:13'], 'Last Name': ['Doe'] }
range	Un objet Range, représentant la cellule ou la plage de cellules modifiées. Range
triggerUid	ID du déclencheur ayant généré cet événement. 4034124084959907503
values	Tableau contenant les valeurs dans l'ordre dans lequel elles apparaissent dans la feuille de calcul. ['2015/05/04 15:00', '[e-mail]', 'Bob', '27', 'Bill', '28', 'Susan', '25']

Événements Google Docs

Les déclencheurs permettent à Google Docs de répondre lorsqu'un utilisateur ouvre un document.

Ouvrir (simple et installable)
authMode	Valeur de l'énumération ScriptApp.AuthMode. LIMITED
source	Objet Document représentant le fichier Google Docs auquel le script est lié. Document
triggerUid	ID du déclencheur ayant généré cet événement (déclencheurs installables uniquement). 4034124084959907503
user	Objet User représentant l'utilisateur actif, le cas échéant (selon un ensemble complexe de restrictions de sécurité). [e-mail]

Événements Google Slides

Les déclencheurs permettent à Google Slides de répondre lorsqu'un utilisateur ouvre une présentation.

Ouvrir (simple)
authMode	Valeur de l'énumération ScriptApp.AuthMode. LIMITED
source	Objet Presentation représentant le fichier Google Slides auquel le script est lié. Presentation
user	Objet User représentant l'utilisateur actif, le cas échéant (selon un ensemble complexe de restrictions de sécurité). [e-mail]

Événements Google Forms

Les déclencheurs spécifiques à Google Forms permettent aux scripts de répondre lorsqu'un utilisateur modifie un formulaire ou envoie une réponse.

Ouvrir * (simple et installable)
authMode	Valeur de l'énumération ScriptApp.AuthMode. LIMITED
source	Objet Form représentant le fichier Google Forms auquel le script est lié. Form
triggerUid	ID du déclencheur ayant généré cet événement (déclencheurs installables uniquement). 4034124084959907503
user	Objet User représentant l'utilisateur actif, le cas échéant (selon un ensemble complexe de restrictions de sécurité). [e-mail]

* Cet événement ne se produit pas lorsqu'un utilisateur ouvre un formulaire pour y répondre, mais lorsqu'un éditeur ouvre le formulaire pour le modifier.

Envoi du formulaire (installable)
Attention:Veillez à utiliser ce déclencheur d'envoi de formulaire avec FormTriggerBuilder.
authMode	Valeur de l'énumération ScriptApp.AuthMode. FULL
response	Objet FormResponse, représentant la réponse de l'utilisateur au formulaire dans son ensemble. FormResponse
source	Objet Form représentant le fichier Google Forms auquel le script est lié. Form
triggerUid	ID du déclencheur ayant généré cet événement. 4034124084959907503

Événements Google Agenda

Les déclencheurs Agenda se déclenchent lorsque les événements d'agenda d'un utilisateur sont mis à jour (créés, modifiés ou supprimés).

Ces déclencheurs ne vous indiquent pas quel événement a changé ni comment. Elles indiquent plutôt que votre code doit effectuer une opération de synchronisation incrémentielle pour récupérer les modifications récentes apportées au calendrier. Pour une description complète de cette procédure, consultez le guide de synchronisation des ressources de l'API Agenda.

Pour synchroniser avec Agenda dans Apps Script, procédez comme suit:

1. Activez le service avancé Agenda pour le projet de script. Le service Agenda intégré n'est pas suffisant pour ce workflow.
2. Déterminez les agendas à synchroniser. Pour chacun de ces agendas, effectuez une opération de synchronisation initiale à l'aide de la méthode Events.list() du service avancé Agenda.
3. Le résultat de la synchronisation initiale renvoie un nextSyncToken pour cet agenda. Stockez ce jeton pour une utilisation ultérieure.
4. Lorsque le déclencheur EventUpdated d'Apps Script se déclenche, indiquant une modification d'événement d'agenda, effectuez une synchronisation incrémentielle pour l'agenda concerné à l'aide de l'nextSyncToken stocké. Il s'agit essentiellement d'une autre requête Events.list(), mais la fourniture de nextSyncToken limite la réponse aux événements qui ont changé depuis la dernière synchronisation.
5. Examinez la réponse de la synchronisation pour savoir quels événements ont été mis à jour et demandez à votre code de répondre de manière appropriée. Par exemple, vous pouvez consigner la modification, mettre à jour une feuille de calcul, envoyer des notifications par e-mail ou effectuer d'autres actions.
6. Mettez à jour le nextSyncToken que vous avez stocké pour ce calendrier avec celui renvoyé par la requête de synchronisation incrémentielle. Cela force la prochaine opération de synchronisation à ne renvoyer que les modifications les plus récentes.

Attention :Il arrive que le serveur invalide les jetons de synchronisation, ce qui entraîne une erreur 410. Dans ce cas, votre code doit effectuer une synchronisation complète et remplacer toutes les données et tous les jetons synchronisés stockés pour cet agenda.

EventUpdated (installable)
authMode	Valeur de l'énumération ScriptApp.AuthMode. FULL
calendarId	ID de chaîne de l'agenda dans lequel la mise à jour de l'événement a eu lieu. [e-mail]
triggerUid	ID du déclencheur ayant généré cet événement. 4034124084959907503

Événements des modules complémentaires Google Workspace

Le déclencheur onInstall() s'exécute automatiquement lorsqu'un utilisateur installe un module complémentaire.

Installer (simple)
authMode	Valeur de l'énumération ScriptApp.AuthMode. FULL

Événements de l'application Google Chat

Pour en savoir plus sur les objets d'événement dans Google Chat, consultez Recevoir et répondre aux interactions avec votre application Google Chat.

Événements basés sur le temps

Les déclencheurs basés sur le temps (également appelés déclencheurs de l'horloge) permettent d'exécuter des scripts à une heure précise ou à un intervalle récurrent.

Déclencheur horaire (installable)
authMode	Valeur de l'énumération ScriptApp.AuthMode. FULL
day-of-month	Entre 1 et 31. Étant donné que ce nom de propriété contient des tirets, vous devez y accéder via e['day-of-month'] plutôt que via la notation par points. 31
day-of-week	Entre 1 (lundi) et 7 (dimanche). Étant donné que ce nom de propriété contient des tirets, vous devez y accéder via e['day-of-week'] plutôt que via la notation par points. 7
hour	Entre 0 et 23. 23
minute	Entre 0 et 59. 59
month	Entre 1 et 12. 12
second	Entre 0 et 59. 59
timezone	Fuseau horaire UTC
triggerUid	ID du déclencheur ayant généré cet événement. 4034124084959907503
week-of-year	Entre 1 et 52. Étant donné que ce nom de propriété contient des tirets, vous devez y accéder via e['week-of-year'] plutôt que via la notation par points. 52
year	L'année 2015