Agendas et événements

Ce guide décrit les agendas, les événements et leur relation.

Agendas

Un agenda est une collection d'événements associés, ainsi que des métadonnées supplémentaires telles que le récapitulatif, le fuseau horaire par défaut, le lieu, etc. Chaque agenda est identifié par un ID qui est une adresse e-mail. Les agendas peuvent avoir plusieurs propriétaires.

Événements

Un événement est un objet associé à une date ou à une plage horaire spécifiques. Les événements sont identifiés par un ID unique. En plus d'une date et heure de début et de fin, les événements contiennent d'autres données telles que le résumé, la description, le lieu, l'état, les rappels, les pièces jointes, etc.

Types d'événements

Google Agenda est compatible avec les événements ponctuels et récurrents :

  • Un événement unique représente une occurrence unique.
  • Un événement récurrent définit plusieurs occurrences.

Les événements peuvent également être programmés ou toute la journée :

  • Un événement temporisé se produit entre deux points temporels spécifiques. Les événements programmés utilisent les champs start.dateTime et end.dateTime pour spécifier leur date et heure.
  • Un événement toute la journée dure une journée entière ou une série de jours consécutifs. Les événements qui durent toute la journée utilisent les champs start.date et end.date pour spécifier quand ils se produisent. Notez que le champ du fuseau horaire n'a aucune importance pour les événements d'une journée entière.

Organisateurs

Les événements n'ont qu'un seul organisateur, à savoir l'agenda contenant la copie principale de l'événement. Les événements peuvent également comporter plusieurs participants. Un participant correspond généralement à l'agenda principal d'un utilisateur invité.

Le diagramme suivant illustre la relation conceptuelle entre les agendas, les événements et d'autres éléments associés :

Agendas principaux et autres agendas

Un agenda principal est un type d'agenda spécial associé à un seul compte utilisateur. Cet agenda est créé automatiquement pour chaque nouveau compte utilisateur. Son ID correspond généralement à l'adresse e-mail principale de l'utilisateur. Tant que le compte existe, son agenda principal ne peut jamais être supprimé ni "détaché" de l'utilisateur. Toutefois, vous pouvez toujours le partager avec d'autres utilisateurs.

En plus de l'agenda principal, vous pouvez créer explicitement autant d'agendas que vous le souhaitez. Ces agendas peuvent être modifiés, supprimés et partagés entre plusieurs utilisateurs.

Agenda et liste des agendas

La collection Calendars représente tous les agendas existants. Il permet de créer et de supprimer des agendas. Vous pouvez également récupérer ou définir des propriétés globales partagées par tous les utilisateurs ayant accès à un agenda. Par exemple, le titre et le fuseau horaire par défaut d'un agenda sont des propriétés globales.

CalendarList est une collection de toutes les entrées d'agenda qu'un utilisateur a ajoutées à sa liste (affichée dans le panneau de gauche de l'interface utilisateur Web). Vous pouvez l'utiliser pour ajouter et supprimer des agendas existants dans la liste des utilisateurs. Vous l'utilisez également pour récupérer et définir les valeurs des propriétés de calendrier spécifiques à l'utilisateur, telles que les rappels par défaut. Un autre exemple est la couleur de premier plan, car différents utilisateurs peuvent définir des couleurs différentes pour le même agenda.

Le tableau suivant compare la signification des opérations pour les deux collections :

Opération Agendas CalendarList
insert Crée un agenda secondaire. Par défaut, cet agenda est également ajouté à la liste des agendas du créateur. Insère un agenda existant dans la liste de l'utilisateur.
delete Supprime un agenda secondaire. Supprime un agenda de la liste de l'utilisateur.
get Récupère les métadonnées de l'agenda (titre, fuseau horaire, etc.). Récupère les métadonnées ainsi que les personnalisations spécifiques à l'utilisateur, comme la couleur ou les rappels de remplacement.
patch/update Modifie les métadonnées de l'agenda. Modifie les propriétés de l'agenda spécifiques à l'utilisateur.

Événements périodiques

Certains événements se produisent plusieurs fois à intervalles réguliers, comme les réunions hebdomadaires, les anniversaires et les jours fériés. À l'exception de leurs heures de début et de fin, ces événements récurrents sont souvent identiques.

Les événements sont dits récurrents s'ils se répètent selon un calendrier défini. Les événements uniques ne sont pas récurrents et ne se produisent qu'une seule fois.

Règle de récurrence

La programmation d'un événement récurrent est définie en deux parties :

  • ses champs de début et de fin (qui définissent la première occurrence, comme s'il s'agissait d'un événement unique autonome) ;

  • Son champ de récurrence (qui définit la fréquence de répétition de l'événement).

Le champ "recurrence" contient un tableau de chaînes représentant une ou plusieurs propriétés RRULE, RDATE ou EXDATE, telles que définies dans la RFC 5545.

La propriété RRULE est la plus importante, car elle définit une règle régulière pour la répétition de l'événement. Il se compose de plusieurs éléments. En voici quelques-uns :

  • FREQ : fréquence à laquelle l'événement doit se répéter (par exemple, DAILY ou WEEKLY). Obligatoire.

  • INTERVAL : fonctionne avec FREQ pour spécifier la fréquence de répétition de l'événement. Par exemple, FREQ=DAILY;INTERVAL=2 signifie une fois tous les deux jours.

  • COUNT : nombre de fois où cet événement doit être répété.

  • UNTIL : date ou date et heure jusqu'à laquelle l'événement doit être répété (incluses).

  • BYDAY : jours de la semaine où l'événement doit se répéter (SU, MO, TU, etc.). BYMONTH, BYYEARDAY et BYHOUR sont d'autres composants similaires.

La propriété RDATE spécifie des dates ou des dates et heures supplémentaires auxquelles les événements doivent avoir lieu. Exemple :RDATE;VALUE=DATE:19970101,19970120 Utilisez cette option pour ajouter des occurrences supplémentaires non couvertes par RRULE.

La propriété EXDATE est semblable à RDATE, mais elle spécifie les dates ou les dates et heures auxquelles l'événement ne doit pas avoir lieu. Autrement dit, ces occurrences doivent être exclues. Il doit s'agir d'une instance valide générée par la règle de récurrence.

EXDATE et RDATE peuvent avoir un fuseau horaire et doivent être des dates (et non des dates et heures) pour les événements d'une journée entière.

Chacune des propriétés peut apparaître plusieurs fois dans le champ de récurrence. La récurrence est définie comme l'union de toutes les règles RRULE et RDATE, moins celles exclues par toutes les règles EXDATE.

Voici quelques exemples d'événements récurrents :

  1. Un événement qui se produit de 6h à 7h tous les mardis et vendredis à partir du 15 septembre 2015 et qui s'arrête après la cinquième occurrence le 29 septembre :

    ...
"start": {
 "dateTime": "2015-09-15T06:00:00+02:00",
 "timeZone": "Europe/Zurich"
},
"end": {
 "dateTime": "2015-09-15T07:00:00+02:00",
 "timeZone": "Europe/Zurich"
},
"recurrence": [
 "RRULE:FREQ=WEEKLY;COUNT=5;BYDAY=TU,FR"
],
…

  2. Un événement sur toute la journée commençant le 1er juin 2015 et se répétant tous les trois jours pendant tout le mois, à l'exception du 10 juin, mais y compris les 9 et 11 juin :

    ...
"start": {
 "date": "2015-06-01"
},
"end": {
 "date": "2015-06-02"
},
"recurrence": [
 "EXDATE;VALUE=DATE:20150610",
 "RDATE;VALUE=DATE:20150609,20150611",
 "RRULE:FREQ=DAILY;UNTIL=20150628;INTERVAL=3"
],
…

Instances et exceptions

Un événement récurrent se compose de plusieurs instances, c'est-à-dire ses occurrences spécifiques à différents moments. Ces instances agissent elles-mêmes comme des événements.

Les modifications apportées à un événement récurrent peuvent affecter l'ensemble de l'événement récurrent (et toutes ses instances) ou uniquement des instances individuelles. Les instances qui diffèrent de leur événement récurrent parent sont appelées exceptions.

Par exemple, une exception peut avoir un récapitulatif ou une heure de début différents, ou des participants supplémentaires invités uniquement à cette instance. Vous pouvez également annuler une instance sans supprimer l'événement récurrent (les annulations d'instances sont indiquées dans l'événement status).

Vous trouverez des exemples d'utilisation des événements récurrents et des instances avec l'API Google Agenda sur cette page.

Fuseaux horaires

Un fuseau horaire spécifie une région qui observe une heure standard uniforme. Dans l'API Google Agenda, vous spécifiez les fuseaux horaires à l'aide des identifiants IANA.

Vous pouvez définir le fuseau horaire pour les agendas et les événements. Les sections suivantes décrivent les effets de ces paramètres.

Fuseau horaire de l'agenda

Le fuseau horaire de l'agenda est également appelé fuseau horaire par défaut en raison de ses implications pour les résultats des requêtes. Le fuseau horaire de l'agenda affecte la façon dont les valeurs temporelles sont interprétées ou présentées par les méthodes events.get(), events.list() et events.instances().

Conversion du fuseau horaire des résultats de requête
Les résultats des méthodes get(), list() et instances() sont renvoyés dans le fuseau horaire que vous spécifiez dans le paramètre timeZone. Si vous omettez ce paramètre, ces méthodes utilisent toutes le fuseau horaire de l'agenda par défaut.
Faire correspondre les événements d'une journée entière aux requêtes avec des créneaux horaires
Les méthodes list() et instances() vous permettent de spécifier des filtres par heure de début et de fin. La méthode renvoie les instances qui se trouvent dans la plage spécifiée.
Le fuseau horaire de l'agenda est utilisé pour calculer les heures de début et de fin des événements d'une journée entière afin de déterminer s'ils correspondent à la spécification du filtre.

Fuseau horaire de l'événement

Les instances d'événement ont une heure de début et une heure de fin. Le fuseau horaire peut être inclus dans la spécification de ces heures. Vous pouvez spécifier le fuseau horaire de plusieurs manières. Les exemples suivants indiquent tous la même heure :

  • Incluez un décalage horaire dans le champ dateTime, par exemple 2017-01-25T09:00:00-0500.
  • Spécifiez l'heure sans décalage, par exemple 2017-01-25T09:00:00, en laissant le champ timeZone vide (le fuseau horaire par défaut est alors utilisé de manière implicite).
  • Spécifiez l'heure sans décalage, par exemple 2017-01-25T09:00:00, mais utilisez le champ timeZone pour spécifier le fuseau horaire.

Vous pouvez également spécifier les heures des événements en UTC si vous le souhaitez :

  • Spécifiez l'heure en UTC : 2017-01-25T14:00:00Z ou utilisez un décalage nul 2017-01-25T14:00:00+0000.

La représentation interne de l'heure de l'événement est la même dans tous ces cas, mais la définition du champ timeZone associe un fuseau horaire à l'événement, tout comme lorsque vous définissez un fuseau horaire pour un événement à l'aide de l'interface utilisateur d'Agenda :

Fragment de capture d'écran montrant le fuseau horaire d'un événement

Fuseau horaire de l'événement récurrent

Pour les événements récurrents, une seule zone de fuseau horaire doit toujours être spécifiée. Il est nécessaire pour développer les récurrences de l'événement.