Agendas et événements

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

Agendas

Un agenda est un ensemble d'événements associés accompagnés de métadonnées supplémentaires telles qu'un résumé, le fuseau horaire par défaut, le lieu, etc. Chaque agenda est identifié par un ID correspondant à une adresse e-mail. Un agenda peut avoir plusieurs propriétaires.

Événements

Un événement est un objet associé à une date ou une période spécifique. Les événements sont identifiés par un identifiant unique. Outre les dates et heures de début et de fin, les événements contiennent d'autres données telles qu'un résumé, une description, un lieu, un état, des rappels, des pièces jointes, etc.

Types d'événements

Google Agenda accepte les événements uniques 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 chronométrés ou contre toute la journée:

  • Un événement chronométré se produit entre deux moments précis. Les événements temporisés utilisent les champs start.dateTime et end.dateTime pour spécifier le moment où ils se produisent.
  • Un événement toute la journée s'étend sur une journée entière ou une série de jours consécutifs. Les événements d'une journée entière utilisent les champs start.date et end.date pour spécifier le moment où ils se produisent. Notez que le champ "fuseau horaire" n'a aucune signification pour les événements d'une journée entière.

Organisateurs

Les événements ont un seul organisateur : l'agenda contenant la copie principale de l'événement. Les événements peuvent également avoir plusieurs participants. Un participant est généralement l'agenda principal d'un utilisateur invité.

Le schéma 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 particulier d'agenda associé à un seul compte utilisateur. Cet agenda est créé automatiquement pour chaque nouveau compte utilisateur, et son ID correspond généralement à l'adresse e-mail principale de l'utilisateur. Tant que le compte existe, l'agenda principal ne peut jamais être supprimé ni détenu par l'utilisateur. Toutefois, il peut toujours être partagé avec d'autres utilisateurs.

En plus de l'agenda principal, vous pouvez créer autant d'agendas que vous le souhaitez, mais vous pouvez modifier, supprimer et partager ces agendas avec plusieurs utilisateurs.

Agenda et liste d'agendas

La collection Agendas représente tous les agendas existants. Elle permet de créer et de supprimer des agendas. Vous pouvez également récupérer ou définir des propriétés générales partagées entre tous les utilisateurs ayant accès à un agenda. Par exemple, le titre d'un agenda et le fuseau horaire par défaut 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ées dans le panneau de gauche de l'interface utilisateur Web). Elle permet d'ajouter et de supprimer des agendas dans la liste des utilisateurs, ou d'en supprimer. Elle vous permet également de récupérer et de définir les valeurs des propriétés d'agenda propres à l'utilisateur, telles que les rappels par défaut. La couleur de premier plan constitue un autre exemple, car différents utilisateurs peuvent avoir des couleurs différentes définies 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 d'agenda, telles que le titre ou le fuseau horaire. Récupère les métadonnées et des personnalisations spécifiques à l'utilisateur, telles que 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 propres à l'utilisateur.

Événements périodiques

Certains événements ont lieu plusieurs fois selon un horaire régulier, comme des réunions hebdomadaires, des anniversaires ou des jours fériés. Outre les heures de début et de fin différentes, ces événements répétés 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

Le calendrier d'un événement périodique est défini 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) et

  • Son champ de récurrence (qui définit la manière dont l'événement doit être répété au fil du temps)

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

La propriété RRULE est la plus importante, car elle définit une règle standard pour la répétition de l'événement. Il est composé de plusieurs composants. En voici quelques-unes:

  • FREQ : fréquence à laquelle l'événement doit être répété (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 heure jusqu'à laquelle l'événement doit être répété (inclus).

  • BYDAY : jours de la semaine pendant lesquels l'événement doit être répété (SU, MO, TU, etc.). D'autres composants similaires incluent BYMONTH, BYYEARDAY et BYHOUR.

La propriété RDATE spécifie des dates ou des heures supplémentaires où les événements doivent se produire. 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 heures auxquelles l'événement ne doit pas se produire. Autrement dit, ces occurrences doivent être exclues. Elle doit pointer vers une instance valide générée par la règle de récurrence.

EXDATE et RDATE peuvent avoir un fuseau horaire et doivent correspondre à des dates (et non à des dates et à des 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 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 d'une journée entière qui commence le 1er juin 2015 et se répète tous les trois jours tout au long du mois, à l'exclusion du 10 juin, mais comprenant 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 est constitué de plusieurs instances: il s'agit de ses occurrences particulières à différents moments. Ces instances agissent comme des événements eux-mêmes.

Les modifications d'événements périodiques peuvent affecter l'ensemble de l'événement récurrent (et toutes ses instances) ou seulement des instances individuelles. Les instances qui diffèrent de l'événement récurrent parent sont appelées exceptions.

Par exemple, une exception peut présenter un résumé différent, une heure de début différente ou des participants supplémentaires invités uniquement à cette instance. Vous pouvez également annuler complètement une instance sans supprimer l'événement récurrent (les annulations d'instance sont reflétées dans l'événement status).

Pour découvrir comment utiliser des événements et des instances récurrents via l'API Google Agenda, cliquez ici.

Fuseaux horaires

Un fuseau horaire désigne une région qui observe une heure standard uniforme. Dans l'API Google Calendar, spécifiez les fuseaux horaires à l'aide d'identifiants de fuseau horaire IANA.

Vous pouvez définir un fuseau horaire à la fois 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 du calendrier est également appelé fuseau horaire par défaut en raison de ses conséquences sur les résultats de requête. Le fuseau horaire du calendrier affecte la façon dont les valeurs d'heure sont interprétées ou présentées par les méthodes events.get(), events.list() et events.instances().

Conversion du fuseau horaire du résultat de la 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.
Mettre en correspondance des événements d'une journée entière avec des requêtes segmentées dans le temps
Les méthodes list() et instances() vous permettent de spécifier des filtres d'heure de début et de fin, en renvoyant les instances situées dans la plage spécifiée. Le fuseau horaire du calendrier 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 sont conformes à 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. La spécification de ces heures peut inclure le fuseau horaire. Vous pouvez spécifier le fuseau horaire de plusieurs manières. Les suivantes indiquent toutes la même heure:

  • Incluez un décalage de fuseau horaire dans le champ dateTime (par exemple, 2017-01-25T09:00:00-0500).
  • Spécifiez une heure sans décalage, par exemple 2017-01-25T09:00:00, en laissant le champ timeZone vide (cela utilise implicitement le fuseau horaire par défaut).
  • 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.

Si vous préférez, vous pouvez également spécifier les heures des événements au format UTC:

  • Indiquez l'heure au format 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 permet d'associer un fuseau horaire à l'événement, tout comme lorsque vous définissez un fuseau horaire d'é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 périodiques, vous devez toujours spécifier un seul fuseau horaire. Elle est nécessaire pour étendre les récurrences de l'événement.