Kalender und Termine

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

Kalender

Ein Kalender ist eine Sammlung von verknüpften 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 für andere freigegeben werden. Hauptkalender gehören zu dem zugehörigen Nutzerkonto, andere Kalender gehören einem einzelnen Dateneigentümer.

Termine

Ein Termin ist ein Objekt, das mit einem bestimmten Datum oder Zeitraum verknüpft ist. Termine werden durch eine eindeutige ID identifiziert. Neben einem Start- und Enddatum und einer Start- und Endzeit enthalten Termine weitere Daten wie Zusammenfassung, Beschreibung, Ort, Status, Erinnerungen, Anhänge usw.

Ereignistypen

Google Kalender unterstützt einmalige und wiederkehrende Termine:

• Ein einmaliger Termin stellt ein einmaliges Ereignis dar.
• Ein wiederkehrender Termin definiert mehrere Ereignisse.

Termine können auch zeitgebunden oder ganztägig sein:

• Ein zeitgebundener Termin findet zwischen zwei bestimmten Zeitpunkten statt. Bei zeitgebundenen Terminen wird mit den Feldern start.dateTime und end.dateTime angegeben, wann sie stattfinden.
• Ein ganztägiger Termin dauert einen ganzen Tag oder mehrere aufeinanderfolgende Tage. Bei ganztägigen Terminen wird mit den Feldern start.date und end.date angegeben, wann sie stattfinden. Das Feld „Zeitzone“ hat für ganztägige Termine keine Bedeutung.

Organisatoren

Termine haben einen einzelnen Organisator , nämlich den Kalender, der die Hauptkopie des Termins enthält. Termine können auch mehrere Teilnehmer haben. Ein Teilnehmer ist in der Regel der Hauptkalender eines eingeladenen Nutzers.

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

Hauptkalender und andere Kalender

Ein Hauptkalender ist ein spezieller Kalendertyp, 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 Hauptkalender nicht gelöscht oder vom Nutzer „entfernt“ werden. Er kann jedoch weiterhin für andere Nutzer freigegeben werden.

Neben dem Hauptkalender können Sie beliebig viele andere Kalender erstellen. Diese Kalender können geändert, gelöscht und für andere freigegeben werden. Solche Kalender haben einen einzelnen Dateneigentümer mit den höchsten Berechtigungen, einschließlich des exklusiven Rechts, den Kalender zu löschen. Die Zugriffsebene des Dateneigentümers kann nicht herabgestuft werden. Der Dateneigentümer wird zunächst als der Nutzer festgelegt, der den Kalender erstellt hat. Die Dateneigentümerschaft kann jedoch in der Google Kalender-Benutzeroberfläche übertragen werden.

Kalender und Kalenderliste

Die Sammlung „Calendars“ stellt alle vorhandenen Kalender dar. Sie kann zum Erstellen und Löschen von Kalendern verwendet werden. Sie können auch globale Properties abrufen oder festlegen, die für alle Nutzer freigegeben sind, die Zugriff auf einen Kalender haben. Der Titel und die Standardzeitzone eines Kalenders sind beispielsweise globale Properties.

Die CalendarList ist eine Sammlung aller Kalendereinträge, die ein Nutzer seiner Liste hinzugefügt hat (im linken Bereich der Web-Benutzeroberfläche angezeigt). Sie können damit vorhandene Kalender zur Liste der Nutzer hinzufügen oder daraus entfernen. Außerdem können Sie damit die Werte nutzerspezifischer Kalender-Properties wie Standarderinnerungen abrufen und festlegen. Ein weiteres Beispiel ist die Vordergrundfarbe, da verschiedene Nutzer unterschiedliche Farben für denselben Kalender festlegen können.

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

Vorgang	Kalender	CalendarList
insert	Erstellt einen neuen sekundären Kalender. Dieser Kalender wird auch der Kalenderliste des Erstellers hinzugefügt und kann nicht entfernt werden, es sei denn, der Kalender wird gelöscht oder übertragen.	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 Kalender-Metadaten ab, z.B. Titel und Zeitzone.	Ruft Metadaten plus nutzerspezifische Anpassungen wie Farbe oder überschriebene Erinnerungen ab.
patch/update	Ändert Kalender-Metadaten.	Ändert nutzerspezifische Kalender-Properties.

Wiederkehrende Termine

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

Termine werden als wiederkehrend bezeichnet, wenn sie sich nach einem festgelegten Zeitplan wiederholen. Einmalige Termine sind nicht wiederkehrend und finden nur einmal statt.

Wiederholungsregel

Der Zeitplan für einen wiederkehrenden Termin wird in zwei Teilen definiert:

• Die Felder „Start“ und „Ende“ (die das erste Ereignis definieren, als wäre es nur ein eigenständiger einmaliger Termin) und

• das Feld „Wiederholung“ (das definiert, wie der Termin im Laufe der Zeit wiederholt werden soll).

Das Feld „Wiederholung“ enthält ein Array von Strings, die eine oder mehrere RRULE, RDATE oder EXDATE Properties darstellen, wie in RFC 5545 definiert.

Die RRULE-Property ist die wichtigste, da sie eine regelmäßige Regel für die Wiederholung des Termins definiert. Sie besteht aus mehreren Komponenten. Einige davon sind:

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

• INTERVAL : Wird zusammen mit FREQ verwendet, um anzugeben, wie oft der Termin wiederholt werden soll. FREQ=DAILY;INTERVAL=2 bedeutet beispielsweise einmal alle zwei Tage.

• COUNT : Anzahl der Wiederholungen dieses Termins.

• UNTIL : Das Datum oder die Uhrzeit, bis zu der der Termin wiederholt werden soll (einschließlich).

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

Die RDATE-Property gibt zusätzliche Daten oder Uhrzeiten an, zu denen die Termine stattfinden sollen. Beispiel: RDATE;VALUE=DATE:19970101,19970120. Verwenden Sie diese Option, um zusätzliche Termine hinzuzufügen, die nicht von der RRULE abgedeckt werden.

Die EXDATE-Property ähnelt RDATE, gibt aber Daten oder Uhrzeiten an, zu denen der Termin nicht stattfinden soll. Diese Termine 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 Uhrzeiten) sein.

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

Hier einige Beispiele für wiederkehrende Termine:

1. Ein Termin, der ab dem 15. September 2015 jeden Dienstag und Freitag von 6:00 bis 7:00 Uhr stattfindet und nach dem fünften Termin 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 drei Tage wiederholt, wobei der 10. Juni ausgeschlossen ist, der 9. und 11. Juni aber eingeschlossen sind:

   ...
   "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: den einzelnen Terminen zu unterschiedlichen Zeiten. Diese Instanzen fungieren als Termine selbst.

Ä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 Termin 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 auch eine Instanz ganz absagen, ohne den wiederkehrenden Termin zu entfernen (Absagen von Instanzen werden im Termin status berücksichtigt).

Beispiele für die Verwendung von wiederkehrenden Terminen und Instanzen über die Google Kalender API finden Sie hier.

Zeitzonen

Eine Zeitzone gibt eine Region an, in der eine einheitliche Standardzeit gilt. In der Google Kalender 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 werden die Auswirkungen dieser Einstellungen beschrieben.

Kalenderzeitzone

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

Zeitzonenkonvertierung für Suchergebnisse

Die Ergebnisse der get(), list() und instances() Methoden werden in der Zeitzone zurückgegeben, die Sie im timeZone Parameter angeben. Wenn Sie diesen Parameter weglassen, verwenden alle diese Methoden die Kalenderzeitzone als Standard.

Ganztägige Termine mit zeitgebundenen Abfragen abgleichen

Mit den list() und instances() Methoden können Sie Filter für Start- und Endzeit angeben. Die Methode gibt dann Instanzen zurück, die in den angegebenen Zeitraum fallen. Die Kalenderzeitzone wird verwendet, um Start- und Endzeiten von ganztägigen Terminen zu berechnen und zu ermitteln, ob sie der Filterspezifikation entsprechen.

Terminzeitzone

Termininstanzen haben eine Start- und Endzeit. Die Spezifikation für diese Zeiten kann die Zeitzone enthalten. Sie können die Zeitzone auf verschiedene Arten angeben. Die folgenden Angaben beziehen sich alle auf dieselbe Zeit:

• Fügen Sie im Feld dateTime einen Zeitzonen-Offset ein, z. B. 2017-01-25T09:00:00-0500.
• Geben Sie die Zeit ohne Offset 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 Offset an, z. B. 2017-01-25T09:00:00, verwenden Sie aber das Feld timeZone, um die Zeitzone anzugeben.

Sie können Terminzeiten auch in UTC angeben:

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

Die interne Darstellung der Terminzeit ist in allen diesen Fällen gleich, wenn Sie jedoch das Feld timeZone festlegen, wird dem Termin eine Zeitzone zugewiesen, genau wie wenn Sie eine Terminzeitzone über die Kalender Benutzeroberfläche 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.