Agendas et événements

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Ce guide décrit les agendas, les événements et leurs relations.

Calendriers

Un agenda est un ensemble d'événements associés, ainsi que des 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, qui correspond à 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 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 uniques et récurrents:

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

Les événements peuvent également être horaires ou 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 surviennent.
  • Un événement d'une journée entière dure toute une journée ou une série de jours consécutifs. Les événements "Toute la journée" 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 pas d'importance pour les événements d'une journée entière.

Organisateurs

Les événements ont un seul organisateur, à savoir l'agenda contenant la copie principale de l'événement. Les événements peuvent également comporter 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 spécial 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, son agenda principal ne peut jamais être supprimé ni "indépendant" par l'utilisateur. Cependant, il peut toujours être partagé avec d'autres utilisateurs.

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

Agenda et liste d'agendas

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

La liste 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). Vous pouvez l'utiliser pour ajouter ou supprimer des agendas existants dans la liste des utilisateurs. Vous pouvez également l'utiliser pour récupérer et définir les valeurs des propriétés d'agenda spécifiques à l'utilisateur, telles que les rappels par défaut. Un autre exemple concerne la couleur de premier plan, car différentes couleurs peuvent être définies pour un même agenda.

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

Operations Calendriers Liste des agendas
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 des utilisateurs.
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, telles que le titre ou le fuseau horaire. Récupère les métadonnées et des paramètres de personnalisation propres à l'utilisateur (comme des rappels de couleur ou de remplacement).
patch/update Modifie les métadonnées de l'agenda. Modifie les propriétés d'agenda spécifiques à l'utilisateur.

Événements périodiques

Certains événements ont lieu à plusieurs reprises, comme des réunions hebdomadaires, des anniversaires et des jours fériés. Hormis les heures de début et de fin, ces événements répétés sont souvent identiques.

Les événements sont appelés 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 autonome)

  • Son champ de récurrence (qui définit la façon 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 la 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 constitué de plusieurs composants. En voici quelques-uns:

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

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

  • COUNT : nombre de répétitions de l'événement.

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

  • BYDAY : jours de la semaine où l'événement doit être répété (SU, MO, TU, etc.). Parmi les autres composants similaires figurent BYMONTH, BYYEARDAY et BYHOUR.

La propriété RDATE spécifie des dates ou des heures supplémentaires auxquelles les occurrences d'événement doivent se produire. Exemple : RDATE;VALUE=DATE:19970101,19970120. Utilisez cette option pour ajouter des occurrences supplémentaires qui ne sont pas couvertes par le RRULE.

La propriété EXDATE est semblable à RDATE, mais spécifie des dates ou des heures auxquelles l'événement ne doit pas se produire. Autrement dit, ces occurrences doivent être exclues. Il doit pointer vers une instance valide générée par la règle de récurrence.

EXDATE et RDATE peuvent être associés à un fuseau horaire et doivent correspondre à 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 une règle exclue par toutes les règles EXDATE.

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

  1. Un événement qui a lieu de 6 h à 7 h tous les mardis et vendredis à partir du 15 septembre 2015, et qui s'arrête après la cinquième occurrence du 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. Événement d'une journée à partir du 1er juin 2015, qui se répète tous les trois jours du mois (hors 10 juin, mais 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 périodique se compose de plusieurs instances : ses occurrences particulières à différents moments. Ces instances agissent elles-mêmes comme des événements.

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 autres que l'événement parent parent sont appelées exceptions.

Par exemple, une exception peut avoir 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 une instance sans supprimer l'événement récurrent (les annulations d'instance sont répercutées dans l'événement status).

Pour découvrir des exemples d'utilisation des instances et des événements périodiques via l'API Calendar, cliquez ici.

Fuseaux horaires

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

Vous pouvez définir le fuseau horaire des événements et des agendas. 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 de requête. Le fuseau horaire du calendrier affecte la manière 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 des résultats de la requête
Les résultats des méthodes get(), list() et instances() sont renvoyés dans le fuseau horaire que vous avez spécifié dans le paramètre timeZone. Si vous omettez ce paramètre, toutes ces méthodes utilisent 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 avec bris de temps
Les méthodes list() et instances() vous permettent de spécifier des filtres de début et de fin, la méthode renvoyant des instances comprises dans la plage spécifiée. Le fuseau horaire du calendrier permet de 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 aux spécifications du filtre.

Fuseau horaire de l'événement

Les instances d'événement ont des heures de début et 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 éléments suivants spécifient tous 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 l'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.

Vous pouvez également indiquer les heures de l'événement au format UTC si vous préférez:

  • Indiquez l'heure au format UTC : 2017-01-25T14:00:00Z ou utilisez un décalage de zéro (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, 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 périodique

Pour les événements périodiques, un seul fuseau horaire doit toujours être spécifié. Il est nécessaire pour développer les répétitions de l'événement.