Cette page a été traduite par l'API Cloud Translation.

Agendas et événements

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

Agendas

Un agenda est un ensemble d'événements associés, ainsi que de métadonnées supplémentaires telles que le résumé, le fuseau horaire par défaut, l'emplacement, etc. Chaque agenda est identifié par un ID, qui est 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 ID 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 accepte les événements ponctuels et récurrents:

Un événement unique représente un événement unique.
Un événement récurrent définit plusieurs occurrences.

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

Un événement temporisé se produit entre deux moments spécifiques. Les événements temporisés utilisent les champs start.dateTime et end.dateTime pour spécifier quand ils se produisent.
Un événement d'une journée complète s'étend sur une journée entière ou une série de jours consécutifs. Les événements de la journée entière utilisent les champs start.date et end.date pour spécifier quand ils se produisent. Notez que le champ "Fuseau horaire" n'a aucune importance pour les événements d'une journée.

Le début et la fin de l'événement doivent être définis sur une heure précise ou sur une journée complète. Par exemple, il est non 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 comporter plusieurs participants. Un participant est 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, 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 "retiré" de l'agenda de 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. Vous pouvez les modifier, les supprimer et les partager avec plusieurs utilisateurs.

Agenda et liste des agendas

La collection Agendas 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 la zone 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'UI Web). Vous pouvez l'utiliser pour ajouter et supprimer des agendas existants à la liste des utilisateurs. Vous pouvez également l'utiliser 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. Autre exemple : la couleur d'avant-plan, car différents utilisateurs peuvent définir des couleurs différentes pour un 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 et les 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 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. En dehors des heures de début et de fin différentes, 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

La planification d'un événement récurrent se compose de 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 comment l'événement doit se répéter 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, comme défini dans la RFC 5545.

La propriété RRULE est la plus importante, car elle définit une règle régulière pour répéter l'événement. Il se compose de plusieurs composants. 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 à laquelle l'événement doit être répété. 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 date/heure jusqu'à laquelle l'événement doit être répété (inclus).
BYDAY : jours de la semaine auxquels l'événement doit se répéter (SU, MO, TU, etc.). D'autres composants similaires sont BYMONTH, BYYEARDAY et BYHOUR.

La propriété RDATE spécifie des dates ou des heures supplémentaires auxquelles les occurrences d'événements doivent se produire. Exemple :RDATE;VALUE=DATE:19970101,19970120 Utilisez-le pour ajouter des occurrences supplémentaires non couvertes par RRULE.

La propriété EXDATE est semblable à RDATE, mais elle 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 avoir un fuseau horaire et doivent être des dates (et non des dates-heures) pour les événements d'une journée entière.

Chacune des propriétés peut figurer 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 périodiques:

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 le cinquième événement 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"
],
…

Un événement d'une journée 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 en incluant 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: ses occurrences particulières à différents moments. Ces instances agissent elles-mêmes en tant qu'événements.

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

Par exemple, une exception peut avoir un résumé ou une heure de début différents, 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 spécifie une région qui observe une heure normale uniforme. Dans l'API Google Agenda, vous spécifiez les fuseaux horaires à l'aide d'identifiants de fuseau horaire 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 sur les résultats de la requête. Le fuseau horaire du calendrier affecte la façon dont les valeurs de l'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 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 du calendrier par défaut.
Correspondance des événements d'une journée entière aux requêtes avec des plages horaires: Les méthodes list() et instances() vous permettent de spécifier des filtres d'heure de début et de fin, la méthode renvoyant les instances comprises dans la plage spécifiée. Le fuseau horaire de l'agenda 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 correspondent aux spécifications du filtre.

Fuseau horaire de l'événement

Les instances d'événements ont une heure 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 (le fuseau horaire par défaut est alors utilisé implicitement).
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:

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, comme lorsque vous définissez un fuseau horaire de l'événement à l'aide de l'interface utilisateur d'Agenda:

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

Pour les événements récurrents, vous devez toujours spécifier un seul fuseau horaire. Il est nécessaire pour développer les récurrences de l'événement.