Kalender und Termine

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

Kalender

Ein Kalender ist eine Sammlung von Terminen sowie zusätzlichen Metadaten wie Zusammenfassung, Standardzeitzone und Ort. Jeder Kalender wird durch eine ID identifiziert, die eine E‑Mail-Adresse ist. Kalender können für andere freigegeben werden. Primäre Kalender gehören 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/-zeit enthalten Termine weitere Daten wie Zusammenfassung, Beschreibung, Ort, Status, Erinnerungen und Anhänge.

Ereignistypen

Google Kalender unterstützt einmalige und wiederkehrende Termine:

• Ein einmaliger Termin ist ein einzelnes Ereignis.
• 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 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 primärer Kalender 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 primäre Kalender nicht gelöscht oder vom Nutzer „entfernt“ werden. Er kann jedoch weiterhin für andere Nutzer freigegeben werden.

Neben dem primären Kalender 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 ist zunächst der Nutzer, 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 Eigenschaften 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 Eigenschaften.

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 des Nutzers hinzufügen oder 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 unterschiedliche Farben für denselben Kalender 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. 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 Kalendereigenschaften.

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 nach einem festgelegten Zeitplan wiederholt werden. Einmalige Termine werden nicht wiederholt 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 Eigenschaften darstellen, wie in RFC 5545 definiert.

Die RRULE-Eigenschaft 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.). Andere ähnliche Komponenten sind BYMONTH, BYYEARDAY und BYHOUR.

Die RDATE-Eigenschaft gibt zusätzliche Daten oder Uhrzeiten an, an 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-Eigenschaft ähnelt RDATE, gibt aber Daten oder Uhrzeiten an, an denen der Termin nicht stattfinden soll. Diese Termine sollten also ausgeschlossen werden. Dies 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 Daten (nicht Uhrzeiten) sein.

Jede der Eigenschaften kann mehrmals im Feld „Wiederholung“ 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 2015 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 eine Instanz auch ganz absagen, ohne den wiederkehrenden Termin zu entfernen (Absagen von Instanzen werden im statusdes Termins berücksichtigt).

Beispiele für die Verwendung von wiederkehrenden Terminen und Instanzen mit der Google Calendar API finden Sie unter Wiederkehrende Termine.

Zeitzonen

Eine Zeitzone gibt eine Region an, in der eine einheitliche Standardzeit gilt. In der Google Calendar API geben Sie Zeitzonen mit IANA-Zeitzonen-IDs 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 auf die Art und Weise 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 diese Methoden standardmäßig die Kalenderzeitzone.

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 so zu ermitteln, ob sie in die Filterspezifikation fallen.

Terminzeitzone

Termininstanzen haben eine Start- und Endzeit. Die Angabe 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

Bei wiederkehrenden Terminen müssen Sie immer eine einzelne Zeitzone angeben, um die Wiederholungen des Termins zu erweitern.