Kalender und Termine

In diesem Leitfaden werden Kalender, Termine und ihre Beziehung zueinander beschrieben.

Kalender

Ein Kalender ist eine Sammlung verwandter Ereignisse, einschließlich zusätzlicher Metadaten wie Zusammenfassung, Standardzeitzone, Standort usw. Jeder Kalender wird durch eine ID identifiziert, die eine E-Mail-Adresse ist. Kalender können mehrere Eigentümer haben.

Veranstaltungen

Ein Ereignis ist ein Objekt, das einem bestimmten Datum oder Zeitraum zugeordnet ist. Ereignisse sind durch eine eindeutige ID gekennzeichnet. Neben dem Start- und Enddatum (Datum und Uhrzeit) enthalten Ereignisse weitere Daten wie Zusammenfassung, Beschreibung, Ort, Status, Erinnerungen, Anhänge usw.

Ereignistypen

Google Kalender unterstützt einzelne und wiederkehrende Termine:

  • Ein einzelnes Ereignis stellt ein eindeutiges Vorkommen dar.
  • Ein wiederkehrendes Ereignis definiert mehrere Vorkommnisse.

Ereignisse können auch zeitgesteuert oder ganztägig sein:

  • Ein timed-Ereignis tritt zwischen zwei bestimmten Zeitpunkten ein. Bei Ereignissen mit Zeitstempel werden die Felder start.dateTime und end.dateTime verwendet, um den Zeitpunkt anzugeben.
  • Ein ganztägiges Ereignis erstreckt sich über einen ganzen Tag oder eine Reihe von aufeinanderfolgenden Tagen. Bei ganztägigen Ereignissen geben Sie mit den Feldern start.date und end.date an, wann sie stattfinden sollen. Beachten Sie, dass das Zeitzonenfeld für ganztägige Ereignisse keine Bedeutung hat.

Organisatoren

Termine haben einen einzigen Organisator, also den Kalender, der die Hauptkopie des Termins enthält. Ereignisse können auch mehrere Teilnehmer haben. Ein Teilnehmer ist in der Regel der primäre Kalender eines eingeladenen Nutzers.

Das folgende Diagramm zeigt die konzeptionelle Beziehung zwischen Kalendern, Ereignissen und anderen zugehörigen Elementen:

Primäre Kalender und andere Kalender

Ein primärer Kalender ist ein spezieller Kalender, der mit einem einzelnen Nutzerkonto verknüpft ist. Dieser Kalender wird automatisch für jedes neue Nutzerkonto erstellt und seine ID entspricht normalerweise der primären E-Mail-Adresse des Nutzers. Solange das Konto vorhanden ist, kann der primäre Kalender nie vom Nutzer gelöscht oder von einem Nutzer als „nicht Eigentum“ markiert werden. Sie kann jedoch für andere Nutzer freigegeben werden.

Zusätzlich zum primären Kalender können Sie beliebig viele andere Kalender erstellen. Diese Kalender können von mehreren Nutzern geändert, gelöscht und freigegeben werden.

Kalender und Kalenderliste

Die Sammlung Kalender stellt alle vorhandenen Kalender dar. Damit können Kalender erstellt und gelöscht werden. Sie können auch globale Attribute abrufen oder festlegen, die für alle Nutzer mit Zugriff auf einen Kalender freigegeben sind. Der Titel und die Standardzeitzone eines Kalenders sind beispielsweise globale Attribute.

Die CalendarList ist eine Sammlung aller Kalendereinträge, die ein Nutzer seiner Liste hinzugefügt hat (erscheint im linken Bereich der Webbenutzeroberfläche). Damit können Sie Kalender hinzufügen und aus der Nutzerliste entfernen. Sie können damit auch nutzerspezifische Kalendereigenschaften abrufen und festlegen, z. B. Standarderinnerungen. Ein weiteres Beispiel ist die Vordergrundfarbe, da verschiedene Nutzer für denselben Kalender unterschiedliche Farben verwenden können.

In der folgenden Tabelle wird die Bedeutung von Vorgängen für die beiden Sammlungen verglichen:

Aktion Kalender Kalenderliste
insert Erstellt einen neuen sekundären Kalender. Standardmäßig wird dieser Kalender auch der Kalenderliste des Creators hinzugefügt. Fügt einen vorhandenen Kalender in die Liste des Nutzers ein.
delete Löscht einen sekundären Kalender. Entfernt einen Kalender aus der Nutzerliste.
get Ruft Kalendermetadaten ab, z. B. Titel und Zeitzone Ruft Metadaten sowie benutzerspezifische Anpassungen wie Farben oder Überschreibungen von Erinnerungen ab.
patch/update Ändert Kalendermetadaten. Nutzerspezifische Kalendereigenschaften ändern

Wiederkehrende Termine

Einige Termine finden mehrmals täglich statt, z. B. wöchentliche Besprechungen, Geburtstage und Feiertage. Abgesehen von unterschiedlichen Start- und Endzeiten sind diese wiederkehrenden Ereignisse oft identisch.

Termine werden als wiederkehrend bezeichnet, wenn sie sich gemäß einem festgelegten Zeitplan wiederholen. Einmalige Termine werden nur einmal wiederholt.

Wiederholungsregel

Der Zeitplan für einen wiederkehrenden Termin ist in zwei Teile gegliedert:

  • Seine Start- und Endfelder (die das erste Auftreten definieren, als wäre es nur ein eigenständiges Ereignis) und

  • Das Wiederholungsfeld, das definiert, wie das Ereignis im Laufe der Zeit wiederholt werden soll.

Das Serienfeld enthält ein String-Array, das eine oder mehrere RRULE-, RDATE- oder EXDATE-Properties gemäß RFC 5545 darstellt.

Das Attribut RRULE ist die wichtigste, da es eine reguläre Regel zum Wiederholen des Ereignisses definiert. Sie besteht aus mehreren Komponenten. Dazu gehören:

  • FREQ: Die Häufigkeit, mit der das Ereignis wiederholt werden soll (z. B. DAILY oder WEEKLY). Erforderlich.

  • INTERVAL: Zusammen mit FREQ gibt an, wie oft das Ereignis wiederholt werden soll. FREQ=DAILY;INTERVAL=2 bedeutet beispielsweise alle zwei Tage.

  • COUNT: Gibt an, wie oft dieses Ereignis wiederholt werden soll.

  • UNTIL: Datum oder Uhrzeit, bis zu der das Ereignis wiederholt werden soll (einschließlich).

  • BYDAY: Wochentage, an denen das Ereignis wiederholt werden soll (SU, MO, TU usw.). Weitere ähnliche Komponenten sind BYMONTH, BYYEARDAY und BYHOUR.

Das Attribut RDATE gibt zusätzliche Daten oder Uhrzeiten an, zu denen das Ereignis stattfinden soll. Beispiel: RDATE;VALUE=DATE:19970101,19970120. Hiermit können Sie zusätzliche Vorkommen hinzufügen, die nicht von RRULE abgedeckt werden.

Das Attribut EXDATE ähnelt dem RDATE, gibt jedoch Daten oder Uhrzeiten an, zu denen das Ereignis nicht stattfinden soll. Das heißt, diese Vorfälle sollten ausgeschlossen werden. Dies muss auf eine gültige Instanz verweisen, die von der Wiederholungsregel generiert wird.

EXDATE und RDATE können eine Zeitzone haben und müssen als Datum (nicht Datum und Uhrzeit) gelten.

Jedes der Attribute kann mehrmals im wiederkehrenden Feld vorkommen. Die Wiederholung ist definiert als Vereinigung aller RRULE- und RDATE-Regeln, abzüglich der Regeln, die durch alle EXDATE-Regeln ausgeschlossen sind.

Hier einige Beispiele für wiederkehrende Ereignisse:

  1. Ein von 6:00 Uhr bis 7:00 Uhr jeden Dienstag und Freitag beginnender Termin, der vom 15. September 2015 bis zum fünften Mal am 29. September endet:

    ...
"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. Ein ganztägiger Termin vom 1. Juni 2015 mit Wiederholung alle 3 Tage des Monats, ausgenommen 10. Juni, einschließlich 9. und 11. Juni:

    ...
"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"
],
…

Instanzen und Ausnahmen

Ein wiederkehrendes Ereignis besteht aus mehreren Instanzen, die jeweils zu unterschiedlichen Zeitpunkten auftreten. Diese Instanzen dienen selbst als Ereignisse.

Wiederkehrende Ereignisänderungen können sich entweder auf das gesamte wiederkehrende Ereignis (und alle zugehörigen Instanzen) oder nur auf einzelne Instanzen auswirken. Instanzen, die sich von ihren übergeordneten wiederkehrenden Ereignissen unterscheiden, werden als Ausnahmen bezeichnet.

Eine Ausnahme kann beispielsweise eine andere Zusammenfassung, eine andere Startzeit oder zusätzliche Gäste haben, die nur zu dieser Instanz eingeladen wurden. Sie können eine Instanz auch komplett löschen, ohne das wiederkehrende Ereignis zu entfernen (Abbrüche von Instanzen werden im Ereignis status widergespiegelt).

Beispiele für die Arbeit mit wiederkehrenden Terminen und Instanzen über die Google Calendar API finden Sie hier.

Zeitzonen

Eine Zeitzone gibt eine Region an, für die eine einheitliche Standardzeit gilt. In der Google Calendar API geben Sie mithilfe von Zeitzonen für IANA Zeitzonen an.

Sie können die Zeitzone für Kalender und Termine festlegen. In den folgenden Abschnitten werden die Auswirkungen dieser Einstellungen beschrieben.

Kalenderzeitzone

Die Zeitzone des Kalenders wird aufgrund der Auswirkungen auf die Abfrageergebnisse auch als Standardzeitzone bezeichnet. Die Kalenderzeitzone wirkt sich darauf aus, wie Zeitwerte von den Methoden events.get(), events.list() und events.instances() interpretiert oder dargestellt werden.

Zeitzone für Abfrageergebnis
Die Ergebnisse der Methoden get(), list() und instances() werden in der Zeitzone zurückgegeben, die Sie im Parameter timeZone angeben. Wenn Sie diesen Parameter weglassen, wird für alle Methoden standardmäßig die Zeitzone des Kalenders verwendet.
Ganztägige Termine für Abfragen in der Zeitreihe
Mit den Methoden list() und instances() können Sie Start- und Endzeitfilter festlegen. Dabei werden Instanzen zurückgegeben, die in den angegebenen Bereich fallen. Die Zeitzone des Kalenders wird verwendet, um die Start- und Endzeiten von ganztägigen Ereignissen zu berechnen und so zu bestimmen, ob sie in die Filterspezifikation fallen.

Terminzeitzone

Ereignisinstanzen haben eine Start- und Endzeit. Die Spezifikation für diese Zeiten kann die Zeitzone enthalten. Sie können die Zeitzone auf verschiedene Arten angeben. Im Folgenden wird jeweils die gleiche Zeit angegeben:

  • Geben Sie im Feld dateTime einen Zeitzonenversatz ein, z. B. 2017-01-25T09:00:00-0500.
  • Geben Sie die Uhrzeit ohne Offset an, z. B. 2017-01-25T09:00:00. Lassen Sie das Feld timeZone leer (verwendet standardmäßig die Standardzeitzone).
  • Geben Sie die Zeit ohne Abweichung an, z. B. 2017-01-25T09:00:00, aber geben Sie die Zeitzone im Feld timeZone an.

Wenn du möchtest, kannst du auch Ereigniszeiten in UTC angeben:

  • Gib die Zeit in UTC an: 2017-01-25T14:00:00Z oder verwende einen Nullversatz 2017-01-25T14:00:00+0000.

Die interne Darstellung der Terminzeit ist in allen diesen Fällen gleich, aber wenn Sie das Feld timeZone festlegen, wird eine Zeitzone an den Termin angehängt, so wie Sie eine Ereigniszeitzone über die Kalender-UI festlegen:

Screenshot-Fragment mit der Zeitzone eines Ereignisses

Zeitzone des wiederkehrenden Termins

Für wiederkehrende Termine muss immer eine Zeitzone angegeben werden. Er wird benötigt, um die Wiederholungen des Termins zu verlängern.