Kalender und Termine

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

Kalender

Ein Kalender ist eine Sammlung verwandter Ereignisse mit zusätzlichen Metadaten wie Zusammenfassung, Standardzeitzone und Standort. 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 mit einem bestimmten Datum oder Zeitraum verknüpft ist. Ereignisse werden anhand einer eindeutigen ID identifiziert. Neben einem Start- und Enddatum enthalten Ereignisse weitere Daten wie Zusammenfassung, Beschreibung, Ort, Status, Erinnerungen und Anhänge.

Ereignistypen

Google Kalender unterstützt einzelne und wiederkehrende Termine:

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

Ereignisse können auch zeitlich begrenzt oder ganztägig sein:

• Ein zeitlich festgelegtes Ereignis tritt zwischen zwei bestimmten Zeitpunkten auf. Bei zeitgesteuerten Ereignissen wird in den Feldern start.dateTime und end.dateTime angegeben, wann sie auftreten.
• Ein ganztägiger Termin umfasst einen ganzen Tag oder eine Reihe aufeinanderfolgender Tage. Bei ganztägigen Ereignissen wird in 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, 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 eine spezielle Art von Kalender, die 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 sein primärer Kalender nicht gelöscht oder vom Nutzer aufgegeben werden. Sie kann jedoch weiterhin mit anderen Nutzern geteilt werden.

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

Kalender und Kalenderliste

Die Sammlung Kalender steht für alle vorhandenen Kalender. Damit können Kalender erstellt und gelöscht 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 Eigenschaften.

Die CalendarList ist eine Sammlung aller Kalendereinträge, die ein Nutzer seiner Liste hinzugefügt hat (im linken Bereich der Weboberflä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 von nutzerspezifischen 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 standardmäßig auch der Kalenderliste des Creators hinzugefügt.	Ein vorhandener Kalender wird in die Liste des Nutzers eingefügt.
delete	Löscht einen sekundären Kalender.	Entfernt einen Kalender aus der Liste des Nutzers.
get	Ruft Kalendermetadaten wie Titel und Zeitzone ab.	Hier werden Metadaten und nutzerspezifische Anpassungen wie Farbe oder Erinnerungen zum Überschreiben abgerufen.
patch/update	Ändert Kalendermetadaten.	Ändert nutzerspezifische Kalendereigenschaften.

Wiederkehrende Termine

Einige Ereignisse finden mehrmals nach einem regelmäßigen Zeitplan statt, z. B. wöchentliche Besprechungen, Geburtstage und Feiertage. Außer den unterschiedlichen Start- und Endzeiten sind diese wiederkehrenden Ereignisse oft identisch.

Ereignisse werden als wiederkehrend bezeichnet, wenn sie sich nach einem bestimmten Zeitplan wiederholen. Einmalige Ereignisse sind nicht wiederkehrend und treten nur einmal auf.

Wiederholungsregel

Der Zeitplan für ein wiederkehrendes Ereignis besteht aus zwei Teilen:

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

• Das Wiederholungsfeld, das festlegt, wie oft das Ereignis wiederholt werden soll.

Das Wiederholungsfeld enthält ein Array von Strings, die eine oder mehrere RRULE-, RDATE- oder EXDATE-Eigenschaften gemäß RFC 5545 darstellen.

Die Property RRULE ist die wichtigste, da sie eine Regel für die Wiederholung des Ereignisses definiert. Sie besteht aus mehreren Komponenten. Beispiele:

• FREQ: 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 einmal alle zwei Tage.

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

• UNTIL: Das Datum oder die Uhrzeit, bis zu dem bzw. 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 Datumsangaben und Uhrzeiten festgelegt, zu denen die Ereignisereignisse auftreten sollen. Beispiel: RDATE;VALUE=DATE:19970101,19970120. Hiermit können Sie zusätzliche Vorkommen hinzufügen, die nicht durch RRULE abgedeckt sind.

Die Property EXDATE ähnelt RDATE, gibt aber Datumsangaben oder Uhrzeiten an, an denen das Ereignis nicht stattfinden soll. Das heißt, diese Vorkommnisse sollten ausgeschlossen werden. Dieser muss auf eine gültige Instanz verweisen, die von der Wiederholungsregel generiert wurde.

EXDATE und RDATE können eine Zeitzone haben und müssen bei ganztägigen Terminen Datumsangaben (keine Datumsangaben mit Uhrzeit) sein.

Jedes der Properties kann im Wiederholungsfeld 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 Ereignisse:

1. Ein Ereignis, das jeden Dienstag und Freitag von 6:00 bis 7:00 Uhr stattfindet, beginnend am 15. September 2015 und endend nach dem fünften Mal am 29. September:

   ...
   "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 im Laufe des Monats 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 wiederkehrendes Ereignis besteht aus mehreren Instanzen: seinen einzelnen Vorkommnissen zu verschiedenen Zeiten. Diese Instanzen fungieren selbst als Ereignisse.

Änderungen an wiederkehrenden Ereignissen können sich entweder auf das gesamte wiederkehrende Ereignis (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, einen anderen Beginn oder zusätzliche Teilnehmer haben, die nur zu dieser Instanz eingeladen wurden. Sie können eine Instanz auch vollständig absagen, ohne den wiederkehrenden Termin zu entfernen. Absagen von Instanzen werden im Termin status angezeigt.

Beispiele für die Arbeit mit 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 mithilfe von 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.

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 dargestellt werden.

Zeitzonenkonvertierung von Abfrageergebnissen

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

Abgleich ganztägiger Ereignisse mit Suchanfragen mit Zeitspannen

Mit den Methoden list() und instances() können Sie Start- und Endzeitfilter angeben. Die Methoden geben dann Instanzen zurück, die in den angegebenen Zeitraum fallen. Anhand der Zeitzone des Kalenders werden Start- und Endzeiten ganztägiger Ereignisse berechnet, um zu ermitteln, ob sie in die Filterbeschreibung fallen.

Terminzeitzone

Ereignisinstanzen haben einen Beginn und ein Ende. Die Angabe dieser Zeiten kann die Zeitzone umfassen. Sie können die Zeitzone auf verschiedene Arten angeben. Die folgenden Beispiele geben dieselbe Zeit an:

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

Sie können die Ereigniszeiten auch in UTC angeben:

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

Die interne Darstellung der Ereigniszeit ist in all diesen Fällen gleich. Wenn Sie jedoch das Feld timeZone festlegen, wird dem Ereignis eine Zeitzone zugewiesen, genau wie wenn Sie die Zeitzone eines Ereignisses über die Kalenderoberfläche festlegen:

Zeitzone für wiederkehrende Termine

Für wiederkehrende Ereignisse muss immer eine einzige Zeitzone angegeben werden. Er ist erforderlich, um die Wiederholungen des Ereignisses zu erweitern.