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.

Agendas

Un agenda est un ensemble d'événements associés, ainsi que des métadonnées supplémentaires par exemple le résumé, le fuseau horaire par défaut, l'emplacement, etc. Chaque agenda est identifié par un identifiant, 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 identifiant unique. Outre un début et la date et l'heure de fin, les événements contiennent d'autres données telles que le résumé, la description, position, état, rappels, 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. Événements planifiés utilisez les champs start.dateTime et end.dateTime pour indiquer 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. 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 de fuseau horaire n'a pas d'importance pour les événements d'une journée entière.

Le début et la fin de l'événement doivent être chronométrés ou les deux. toute la journée. Par exemple, il est non valide de spécifier start.date et end.dateTime.

Organisateurs

Les événements ont un seul organisateur, c'est-à-dire 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, événements et 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 identifiant correspond généralement à l'adresse e-mail principale de l'utilisateur. Tant que existe, son agenda principal ne peut jamais être supprimé ni "ne vous appartient plus". par le utilisateur. Toutefois, vous pourrez toujours le partager avec d'autres utilisateurs.

Outre l'agenda principal, vous pouvez créer explicitement autant d'agendas que vous le souhaitez Autres agendas ces agendas peuvent être modifiés, supprimés et partagés entre plusieurs utilisateurs.

Agenda et liste des agendas

Collection Agendas représente tous les agendas existants. Il peut être utilisé pour créer et supprimer agendas. Vous pouvez également récupérer ou définir des propriétés globales partagées entre les utilisateurs ayant accès à un agenda. Par exemple, le titre et les paramètres par défaut d'un agenda fuseau horaire sont des propriétés globales.

La liste CalendarList est collection de toutes les entrées d'agenda qu'un utilisateur a ajoutées à sa liste (affichée dans dans le panneau de gauche de l'interface utilisateur Web). Vous pouvez l'utiliser pour ajouter et supprimer agendas vers et depuis la liste des utilisateurs. Vous l'utilisez également 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 ; Autre exemple est la couleur de premier plan, car différents utilisateurs peuvent avoir des couleurs différentes définis 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é à sa liste d'agendas.	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, par exemple titre, fuseau horaire.	Récupère les métadonnées et les personnalisations spécifiques à l'utilisateur. comme 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, anniversaires et 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.

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 qu'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 qui répète 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 à laquelle l'événement doit être répété. Par exemple, FREQ=DAILY;INTERVAL=2 signifie une fois toutes les deux jours.
COUNT : nombre de répétitions de l'événement.

Vous pouvez utiliser la fonction COUNT ou UNTIL pour indiquer 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 pendant lesquels l'événement doit être répété (SU, MO, TU, etc.). BYMONTH, BYYEARDAY et BYHOUR

La propriété RDATE spécifie des dates ou des heures supplémentaires pour l'événement 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. quand l'événement ne doit pas se produire. Autrement dit, ces occurrences doivent être exclu. 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 les ceux qui sont exclus par les règles EXDATE.

Voici quelques exemples d'événements périodiques:

Un événement qui a lieu de 6h à 7h tous les mardis et vendredis à partir de entre le 15 septembre 2015 et 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 commençant 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 des exceptions

Un événement récurrent est constitué 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'intégralité un é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 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 sans supprimer l'événement périodique (Les annulations d'instances sont reflétées dans l'événement status).

Exemples de gestion d'événements et d'instances récurrents via le Pour accéder à l'API Google Calendar, cliquez ici.

Fuseaux horaires

Un fuseau horaire spécifie une région qui respecte une heure standard uniforme. Dans l'API Google Calendar, vous pouvez spécifier des fuseaux horaires à l'aide de la fonction 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écrire 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 pour ses implications pour les résultats des requêtes. Le fuseau horaire de l'agenda a une incidence sur la façon dont les valeurs temporelles sont interprétées ou présentées par events.get(), events.list() events.instances().

Conversion du fuseau horaire du résultat de la requête: Résultats du get(), list() instances() sont renvoyées dans le fuseau horaire que vous avez spécifié dans timeZone . Si vous omettez ce paramètre, ces méthodes utilisent toutes le calendrier fuseau horaire par défaut.
Mise en correspondance des événements d'une journée entière avec des requêtes temporelles: Le list() et instances() vous permettent de spécifier des filtres d'heure de début et de fin. La méthode en renvoyant des instances comprises dans la plage spécifiée. Fuseau horaire de l'agenda sert à 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 ou non à 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 : la tous les suivants spécifient 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 (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 champ timeZone 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 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, En définissant le champ timeZone, vous associez un fuseau horaire à l'événement, tout comme lorsque vous définissez le fuseau horaire d'un événement dans la console UI:

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.