Kalender und Termine

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

Kalender

Ein Kalender ist eine Sammlung von zusammengehörigen Terminen mit zusätzlichen Metadaten wie Zusammenfassung, Standardzeitzone, Ort usw. Jeder Kalender wird durch eine ID identifiziert, die eine E-Mail-Adresse ist. Kalender können mehrere Inhaber haben.

Ereignisse

Ein Ereignis ist ein Objekt, das einem bestimmten Datum oder Zeitraum zugeordnet ist. Ereignisse werden anhand einer eindeutigen ID identifiziert. Neben Start- und Enddatum/-uhrzeit enthalten Termine auch andere Daten wie Zusammenfassung, Beschreibung, Ort, Status, Erinnerungen und Anhänge.

Ereignistypen

Google Kalender unterstützt einzelne und wiederkehrende Termine:

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

Termine können auch mit Uhrzeit oder ganztägig sein:

• Ein zeitlich begrenztes Ereignis tritt zwischen zwei bestimmten Zeitpunkten auf. Bei zeitgesteuerten Ereignissen wird mit den Feldern start.dateTime und end.dateTime angegeben, wann sie stattfinden.
• Ein ganztägiger Termin erstreckt sich über einen ganzen Tag oder eine Reihe aufeinanderfolgender Tage. Bei ganztägigen Ereignissen wird mit den Feldern start.date und end.date angegeben, wann sie stattfinden. Das Feld „Zeitzone“ ist für ganztägige Termine nicht relevant.

Organisatoren

Termine haben einen einzelnen Organisator, nämlich den Kalender mit der Hauptkopie des Termins. Termine 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, Terminen und anderen zugehörigen Elementen:

Primäre und andere Kalender

Ein Hauptkalender ist eine spezielle Art von Kalender, der mit einem einzelnen Nutzerkonto verknüpft ist. Dieser Kalender wird automatisch für jedes neue Nutzerkonto erstellt und seine ID entspricht in der Regel der primären E‑Mail-Adresse des Nutzers. Solange das Konto vorhanden ist, kann der zugehörige Hauptkalender nie gelöscht oder vom Nutzer „ent-eignet“ werden. Es kann jedoch weiterhin 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 bearbeitet, gelöscht und freigegeben werden.

Kalender und Kalenderliste

Die Sammlung Calendars (Kalender) enthält alle vorhandenen Kalender. Damit lassen sich Kalender erstellen und löschen. 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 (im linken Bereich der Weboberfläche). Damit können Sie vorhandene Kalender zur Liste der Nutzer hinzufügen und daraus entfernen. Außerdem können Sie damit die Werte nutzerspezifischer Kalendereigenschaften wie Standarderinnerungen abrufen und festlegen. Ein weiteres Beispiel ist die Vordergrundfarbe, da verschiedene Nutzer für denselben Kalender unterschiedliche Farben festlegen können.

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

Vorgang	Kalender	CalendarList
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 Liste des Nutzers.
get	Ruft Kalendermetadaten wie Titel und Zeitzone ab.	Ruft Metadaten sowie nutzerspezifische Anpassungen wie Farbe oder überschriebene Erinnerungen ab.
patch/update	Berechtigung zum Ändern von Kalendermetadaten.	Ändert nutzerspezifische Kalendereigenschaften.

Wiederkehrende Termine

Einige Termine finden regelmäßig statt, z. B. wöchentliche Besprechungen, Geburtstage und Feiertage. Abgesehen von den unterschiedlichen Start- und Endzeiten sind diese wiederholten Termine oft identisch.

Ereignisse werden als wiederkehrend bezeichnet, wenn sie sich gemäß einem definierten Zeitplan wiederholen. Einzelne Termine sind nicht wiederkehrend und finden nur einmal statt.

Wiederholungsregel

Der Zeitplan für ein wiederkehrendes Ereignis wird in zwei Teilen definiert:

• Die Start- und Endfelder (die das erste Vorkommen definieren, als wäre dies nur ein einzelnes Ereignis) und

• Das Feld „Wiederholung“ (in dem definiert wird, wie das Ereignis im Laufe der Zeit wiederholt werden soll).

Das Feld „recurrence“ enthält ein Array von Strings, die ein oder mehrere RRULE-, RDATE- oder EXDATE-Attribute gemäß RFC 5545 darstellen.

Die Property RRULE ist am wichtigsten, da sie eine reguläre Regel für die Wiederholung 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: Wird zusammen mit FREQ verwendet, um anzugeben, wie oft das Ereignis wiederholt werden soll. FREQ=DAILY;INTERVAL=2 bedeutet beispielsweise alle zwei Tage.

• COUNT – Anzahl der Wiederholungen dieses Ereignisses.

• UNTIL: Das Datum oder die Datums-/Uhrzeitangabe, 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.

Mit der Property RDATE werden zusätzliche Datumsangaben oder Datums-/Uhrzeitangaben angegeben, an denen die Ereignisinstanzen stattfinden sollen. Beispiel: RDATE;VALUE=DATE:19970101,19970120. Damit können Sie zusätzliche Vorkommen hinzufügen, die nicht von RRULE abgedeckt werden.

Die Property EXDATE ähnelt RDATE, gibt aber Datumsangaben oder Datums-/Uhrzeitangaben an, an denen die Veranstaltung nicht stattfinden soll. Diese Vorkommen sollten also ausgeschlossen werden. Sie muss auf eine gültige Instanz verweisen, die von der Wiederholungsregel generiert wurde.

EXDATE und RDATE können eine Zeitzone haben und müssen für ganztägige Termine Datumsangaben (nicht Datums- und Zeitangaben) sein.

Jede der Eigenschaften kann im Wiederholungsfeld mehrmals vorkommen. Die Wiederholung wird als Vereinigung aller RRULE- und RDATE-Regeln definiert, abzüglich der Regeln, die durch alle EXDATE-Regeln ausgeschlossen werden.

Hier einige Beispiele für wiederkehrende Ereignisse:

1. Ein Ereignis, das jeden Dienstag und Freitag vom 15. September 2015 an von 6:00 Uhr bis 7:00 Uhr stattfindet und nach dem 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, der am 1. Juni 2015 beginnt und sich den ganzen Monat über alle 3 Tage wiederholt, mit Ausnahme des 10. Juni, aber einschließlich des 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 wiederkehrender Termin besteht aus mehreren Instanzen, d. h. den einzelnen Terminen zu unterschiedlichen Zeiten. Diese Instanzen fungieren selbst als Ereignisse.

Änderungen an wiederkehrenden Terminen können sich entweder auf den gesamten wiederkehrenden Termin (und alle seine Instanzen) oder nur auf einzelne Instanzen auswirken. Instanzen, die sich von ihrem übergeordneten wiederkehrenden Ereignis unterscheiden, werden als Ausnahmen bezeichnet.

Eine Ausnahme kann beispielsweise eine andere Zusammenfassung, eine andere Startzeit oder zusätzliche Teilnehmer haben, die nur zu dieser Instanz eingeladen wurden. Sie können eine Instanz auch ganz stornieren, ohne den wiederkehrenden Termin zu entfernen. Stornierungen von Instanzen werden im Termin status angezeigt.

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

Zeitzonen

Eine Zeitzone gibt eine Region an, in der eine einheitliche Standardzeit gilt. In der Google Calendar API geben Sie Zeitzonen mit IANA-Zeitzonenkennungen an.

Sie können die Zeitzone sowohl für Kalender als auch für Termine festlegen. In den folgenden Abschnitten wird beschrieben, wie sich diese Einstellungen auswirken.

Zeitzone des Kalenders

Die Zeitzone des Kalenders wird aufgrund ihrer 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 präsentiert werden.

Konvertierung der Zeitzone für Abfrageergebnisse

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 diese Methoden standardmäßig die Zeitzone des Kalenders verwendet.

Ganztägige Termine mit Suchanfragen mit Zeitangaben abgleichen

Mit den Methoden list() und instances() können Sie Filter für Start- und Endzeit angeben. Die Methode gibt Instanzen zurück, die in den angegebenen Bereich fallen. Die Zeitzone des Kalenders wird verwendet, um Start- und Endzeiten von ganztägigen Ereignissen zu berechnen und festzustellen, ob sie in die Filterspezifikation fallen.

Terminzeitzone

Termine haben eine Start- und Endzeit. Die Angabe dieser Zeiten kann die Zeitzone enthalten. Sie können die Zeitzone auf verschiedene Arten angeben. Die folgenden Beispiele geben alle dieselbe Zeit an:

• Fügen Sie im Feld dateTime einen Zeitzonenversatz ein, z. B. 2017-01-25T09:00:00-0500.
• Geben Sie die Zeit ohne Versatz an, z. B. 2017-01-25T09:00:00, und lassen Sie das Feld timeZone leer (dadurch wird implizit die Standardzeitzone verwendet).
• Geben Sie die Zeit ohne Versatz an, z. B. 2017-01-25T09:00:00, verwenden Sie aber das Feld timeZone, um die Zeitzone anzugeben.

Sie können die Ereigniszeiten auch in UTC angeben:

• Geben Sie die Zeit in UTC an: 2017-01-25T14:00:00Z oder verwenden Sie einen Null-Offset 2017-01-25T14:00:00+0000.

Die interne Darstellung der Terminzeit ist in allen diesen Fällen dieselbe. Wenn Sie jedoch das Feld timeZone festlegen, wird dem Termin eine Zeitzone zugewiesen, genau wie wenn Sie über die Kalender-Benutzeroberfläche eine Terminzeitzone festlegen:

Zeitzone für wiederkehrende Termine

Für wiederkehrende Termine muss immer eine einzelne Zeitzone angegeben werden. Sie ist erforderlich, um die Wiederholungen des Termins zu erweitern.