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 que le 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 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 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 programmés ou tout au long de la journée:
- Un événement temporisé se produit entre deux moments précis. Les événements programmés utilisent les champs
start.dateTime
etend.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 qui durent toute la journée utilisent les champs
start.date
etend.date
pour spécifier le moment où ils se produisent. Notez que le champ de 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, c'est-à-dire l'agenda contenant la copie principale de l'événement. Un événement peut également accueillir 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, son agenda principal ne peut jamais être supprimé ni "retiré" de l'agenda de l'utilisateur. Toutefois, vous pourrez toujours le partager avec d'autres utilisateurs.
Outre 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 entre 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 les propriétés globales 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.
La liste CalendarList est une collection de toutes les entrées d'agenda qu'un utilisateur a ajoutées à sa liste (dans le panneau de gauche de l'interface utilisateur Web). Elle vous permet d'ajouter des agendas et d'en supprimer. 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 avoir différentes couleurs définies pour le même agenda.
Le tableau suivant compare la signification des opérations pour les deux collections:
Opération | Calendriers | 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, comme le titre et le fuseau horaire. | 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 d'agenda spécifiques à l'utilisateur. |
Événements périodiques
Certains événements se produisent plusieurs fois selon un calendrier régulier, comme des réunions hebdomadaires, des anniversaires et des jours fériés. Hormis les heures de début et de fin différentes, ces événements répétés sont souvent identiques.
Un événement est considéré comme récurrent s'il se répète 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 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 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
ouWEEKLY
). Obligatoire.INTERVAL
: fonctionne avecFREQ
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 répétitions de l'événement.UNTIL
: date ou date/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.).BYMONTH
,BYYEARDAY
etBYHOUR
sont d'autres composants similaires.
La propriété RDATE
spécifie des dates ou des heures supplémentaires auxquelles l'événement doit 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 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 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 s'arrêtant 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" ], …
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, sauf le 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 de ses occurrences particulières à différents moments. Ces instances agissent elles-mêmes comme des événements.
Les modifications d'événements récurrents 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 l'événement récurrent 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 récurrent (les annulations d'instance sont reflétées dans l'événement status
).
Pour consulter des exemples d'utilisation d'événements et d'instances récurrents via l'API Google Agenda, cliquez ici.
Fuseaux horaires
Un fuseau horaire spécifie une région qui respecte une heure standard uniforme. Dans l'API Google Agenda, vous spécifiez des fuseaux horaires à l'aide des identifiants de fuseau horaire de l'IANA.
Vous pouvez définir le fuseau horaire à la fois pour les agendas et pour 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 son impact 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 du résultat de la requête
- Les résultats des méthodes
get()
,list()
etinstances()
sont renvoyés dans le fuseau horaire que vous spécifiez dans le paramètretimeZone
. Si vous omettez ce paramètre, ces méthodes utilisent toutes le fuseau horaire du calendrier par défaut. - Mettre en correspondance des événements d'une journée entière avec des requêtes temporelles
- Les méthodes
list()
etinstances()
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 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 à 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 champtimeZone
vide (il 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 champtimeZone
pour indiquer le fuseau horaire.
Si vous préférez, vous pouvez également indiquer les heures des événements en UTC:
- Indiquez l'heure au format UTC:
2017-01-25T14:00:00Z
ou utilisez un décalage nul2017-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 périodiques, vous devez toujours indiquer un fuseau horaire. Il est nécessaire pour développer les récurrences de l'événement.