Agendas et événements

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

Agendas

Un agenda est un ensemble d'événements associés, ainsi que des métadonnées supplémentaires telles que le résumé, 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 être partagés avec d'autres personnes. Les agendas principaux appartiennent à leur compte utilisateur associé, tandis que les autres agendas appartiennent à un seul propriétaire des données.

Événements

Un événement est un objet associé à une date ou une plage horaire spécifique. Les événements sont identifiés par un ID unique. Outre une date et une 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 uniques et périodiques :

• Un événement unique représente une occurrence unique.
• Un événement périodique définit plusieurs occurrences.

Les événements peuvent également être ponctuels ou d'une journée entière :

• Un événement ponctuel se produit entre deux points spécifiques dans le temps. Les événements ponctuels utilisent les champs start.dateTime et end.dateTime pour spécifier quand ils se produisent.
• Un événement d'une journée entière s'étend sur une journée entière ou sur 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 quand ils se produisent. Notez que le champ de fuseau horaire n'a aucune importance pour les événements d'une journée entière.

Le début et la fin de l'événement doivent être ponctuels ou d'une journée entière. Par exemple, il n'est pas valide de spécifier start.date et end.dateTime.

Organisateurs

Les événements ont un seul organisateur , qui est 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 spécial d'agenda associé à un seul compte utilisateur. Cet agenda est créé automatiquement pour chaque nouvel 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 "désapproprié" par l'utilisateur. Toutefois, il peut toujours être partagé avec d'autres utilisateurs.

En plus de l'agenda principal, vous pouvez créer explicitement un nombre illimité d'autres agendas. Ces agendas peuvent être modifiés, supprimés et partagés avec d'autres personnes. Ces agendas ont un seul propriétaire des données disposant des privilèges les plus élevés, y compris le droit exclusif de supprimer l'agenda. Le niveau d'accès du propriétaire des données ne peut pas être rétrogradé. Le propriétaire des données est initialement déterminé comme étant l'utilisateur qui a créé l'agenda. Toutefois, la propriété des données peut être transférée dans l'interface utilisateur de Google Agenda.

Important : Lorsque vous créez un agenda, nous vous recommandons que votre application s'authentifie en tant que propriétaire des données prévu pour l'agenda. Vous pouvez utiliser la délégation d'autorité au niveau du domaine pour autoriser les applications à agir au nom d'un utilisateur spécifique. N'utilisez pas de compte de service pour l'authentification. Si vous utilisez un compte de service pour l'authentification, le compte de service est le propriétaire des données, ce qui peut entraîner un comportement inattendu. Par exemple, si un compte de service est le propriétaire des données, la propriété des données ne peut pas être transférée.

Agenda et liste d'agendas

La collection Calendars représente tous les agendas existants. Elle peut être utilisée pour créer et 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.

La collection "CalendarList" est un ensemble 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 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 est la couleur de premier plan, car différents utilisateurs peuvent définir des couleurs différentes pour le même agenda.

Remarque : Le propriétaire des données d'un agenda ne peut pas supprimer cet agenda de sa liste d'agendas.

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

Opération	Calendars	CalendarList
insert	Crée un agenda secondaire. Cet agenda est également ajouté à la liste d'agendas du créateur et ne peut pas être supprimé, sauf s'il est supprimé ou transféré.	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 (par exemple, le titre et le fuseau horaire).	Récupère les métadonnées ainsi que la personnalisation spécifique à l'utilisateur comme la couleur ou les rappels de forçage.
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 se produisent plusieurs fois à intervalles réguliers, comme les réunions hebdomadaires, les anniversaires et les jours fériés. Outre des heures de début et de fin différentes, ces événements répétés sont souvent identiques.

Les événements sont dits périodiques s'ils se répètent selon une programmation définie. 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 périodique 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), et

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

Le champ de récurrence contient un tableau de chaînes représentant une ou plusieurs RRULE, RDATE ou EXDATE propriétés, comme défini dans 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. Elle est composée 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 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é.

  Vous pouvez utiliser COUNT ou UNTIL pour spécifier la fin de la récurrence de l'événement. N'utilisez pas les deux dans la même règle.

• 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.). Les autres composants similaires incluent BYMONTH, BYYEARDAY et BYHOUR.

La propriété RDATE spécifie des dates ou des heures supplémentaires auxquelles les occurrences de l'événement doivent avoir lieu. Par 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 spécifie les dates ou les heures auxquelles l'événement ne doit pas avoir lieu. Autrement dit, ces occurrences doivent être exclues. Cela 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 être des dates (et non 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 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 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'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 périodique se compose de plusieurs instances : ses occurrences particulières à différents moments. Ces instances agissent comme des événements.

Les modifications d'un événement périodique peuvent affecter l'ensemble de l'événement périodique (et toutes ses instances) ou uniquement des instances individuelles. Les instances qui diffèrent de leur événement périodique 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 complètement une instance sans supprimer l'événement périodique (les annulations d'instance sont reflétées dans l'état de l'événement status).

Vous trouverez des exemples d'utilisation des événements et des instances périodiques via l' API Google Agenda ici.

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 d' identifiants de fuseaux horaires 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 de la requête. Le fuseau horaire de l'agenda affecte la façon dont les valeurs temporelles sont interprétées ou présentées par les events.get(), events.list() et events.instances() méthodes.

Conversion du fuseau horaire des résultats de la requête

Les résultats des get(), list() et instances() méthodes sont renvoyés dans le fuseau horaire que vous spécifiez dans le timeZone paramètre. Si vous omettez ce paramètre, ces méthodes utilisent toutes le fuseau horaire de l'agenda par défaut.

Faire correspondre des événements d'une journée entière à des requêtes entre crochets

Les list() et instances() méthodes vous permettent de spécifier des filtres d'heure de début et de fin, la méthode renvoyant 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. La spécification de ces heures peut inclure le fuseau horaire. Vous pouvez spécifier le fuseau horaire de plusieurs manières. Les suivantes spécifient 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 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 spécifier les heures des événements en temps UTC si vous le préférez :

• Spécifiez l'heure en temps 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, comme lorsque vous définissez un fuseau horaire d'événement à l'aide de l'interface utilisateur de l'agenda :

Pour les événements uniques, vous pouvez spécifier différents fuseaux horaires pour les heures de début et de fin d'un événement. (Cela peut être utile pour les événements, tels que les voyages, qui commencent et se terminent dans des fuseaux horaires différents.) Pour les événements périodiques, consultez la section ci-dessous.

Fuseau horaire des événements périodiques

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