Kalender und Termine

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

Kalender

Ein Kalender ist eine Sammlung verwandter Termine sowie zusätzliche Metadaten wie Zusammenfassung, Standardzeitzone, Ort 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 mit einem bestimmten Datum oder Zeitraum verknüpft ist. Ereignisse werden durch eine eindeutige ID identifiziert. Neben Start- und Enddatum und Endzeit enthalten die Ereignisse weitere Daten wie Zusammenfassung, Beschreibung, Ort, Status, Erinnerungen, Anhänge usw.

Ereignistypen

Google Kalender unterstützt einzelne und wiederkehrende Termine:

  • Ein einzelnes Ereignis steht für ein eindeutiges Vorkommen.
  • Ein wiederkehrendes Ereignis definiert mehrere Wiederholungen.

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

  • Ein zeitgesteuertes Ereignis tritt zwischen zwei bestimmten Zeitpunkten auf. Bei zeitgesteuerten Ereignissen wird mit den Feldern start.dateTime und end.dateTime angegeben, wann sie auftreten.
  • Ein ganztägiger Termin kann einen ganzen Tag oder mehrere aufeinanderfolgende Tage umfassen. Bei ganztägigen Ereignissen wird mit den Feldern start.date und end.date angegeben, wann sie stattfinden. Beachten Sie, dass das Zeitzonenfeld für ganztägige Termine keine Bedeutung hat.

Organisatoren

Termine haben einen einzelnen Organizer, d. h. den Kalender, in dem sich die Hauptkopie des Termins befindet. Veranstaltungen können auch mehrere Teilnehmer haben. Ein Gast ist normalerweise der Hauptkalender 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 Kalendertyp, der mit einem einzelnen Nutzerkonto verknüpft ist. Dieser Kalender wird automatisch für jedes neue Nutzerkonto erstellt und seine ID stimmt in der Regel mit der primären E-Mail-Adresse des Nutzers überein. Solange das Konto vorhanden ist, kann der zugehörige Hauptkalender niemals gelöscht werden oder vom Nutzer „nicht Inhaber“ sein. Sie kann jedoch weiterhin für andere Nutzer freigegeben werden.

Zusätzlich zum primären Kalender können Sie explizit eine beliebige Anzahl weiterer Kalender erstellen. Diese Kalender können geändert, gelöscht und für mehrere Nutzer freigegeben werden.

Kalender und Kalenderliste

Die Sammlung Kalender umfasst alle vorhandenen Kalender. Damit können Kalender erstellt und gelöscht werden. Sie können auch globale Eigenschaften 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 Eigenschaften.

Die CalendarList ist eine Sammlung aller Kalendereinträge, die ein Nutzer im linken Bereich der Web-UI hinzugefügt hat. Sie können damit vorhandene Kalender zur Nutzerliste hinzufügen oder daraus entfernen. Sie können damit auch 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 werden die Bedeutung der Vorgänge 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 Erstellers 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 nutzerspezifische Anpassungen wie Farbe oder Überschreibung von Erinnerungen ab.
patch/update Ändert Kalendermetadaten. Damit werden nutzerspezifische Kalendereigenschaften geändert.

Wiederkehrende Termine

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

Ereignisse werden als wiederkehrend bezeichnet, wenn sie sich nach einem festgelegten Zeitplan wiederholen. Ereignisse vom Typ Einzeln sind einmalig und finden nur einmal statt.

Wiederholungsregel

Der Zeitplan für wiederkehrende Termine besteht aus zwei Teilen:

  • Die Start- und Endfelder (die das erste Vorkommen 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 Wiederholungsfeld enthält ein Array von Strings, die ein oder mehrere RRULE-, RDATE- oder EXDATE-Attribute gemäß RFC 5545 darstellen.

Das Attribut RRULE ist am wichtigsten, da es eine reguläre Regel für die Wiederholung des Ereignisses definiert. Es besteht aus mehreren Komponenten. Dazu gehören unter anderem:

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

  • INTERVAL: Gibt zusammen mit FREQ an, wie oft das Ereignis wiederholt werden soll. Beispiel: FREQ=DAILY;INTERVAL=2 bedeutet einmal alle zwei Tage.

  • COUNT: Häufigkeit, mit der das Ereignis wiederholt werden soll.

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

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

Mit dem Attribut RDATE werden zusätzliche Datumsangaben oder Uhrzeiten angegeben, zu denen das Ereignis eintreten soll. Beispiel: RDATE;VALUE=DATE:19970101,19970120. Hiermit können Sie zusätzliche Vorkommen hinzufügen, die nicht von RRULE abgedeckt sind.

Das Attribut EXDATE ähnelt RDATE, gibt jedoch Datumsangaben oder Uhrzeiten an, an denen das Ereignis nicht auftreten soll. Das heißt, diese Vorkommen sollten 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 Datumsangaben (keine Datums- und Uhrzeitangaben) für ganztägige Termine sein.

Jede der Eigenschaften kann mehrmals im Wiederholungsfeld vorkommen. Die Wiederholung ist definiert als die Kombination aller Regeln vom Typ RRULE und RDATE, abzüglich der Regeln, die von allen EXDATE-Regeln ausgeschlossen werden.

Hier einige Beispiele für wiederkehrende Ereignisse:

  1. Ein Ereignis, das ab dem 15. September 2015 jeden Dienstag und Freitag von 6:00 Uhr bis 7:00 Uhr stattfindet und nach dem fünften Ereignis 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 im Laufe des Monats alle 3 Tage wiederholt, 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, wobei die jeweiligen Ereignisse zu unterschiedlichen Zeiten auftreten. Diese Instanzen fungieren selbst als Ereignisse.

Wiederkehrende Ereignisänderungen können entweder das gesamte wiederkehrende Ereignis (und alle zugehörigen Instanzen) oder nur einzelne Instanzen betreffen. 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 enthalten, die nur zu dieser Instanz eingeladen wurden. Sie können eine Instanz auch komplett absagen, ohne den wiederkehrenden Termin zu entfernen. Abgebrochene Instanzen werden im Ereignis status angezeigt.

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, die eine einheitliche Standardzeit hat. In der Google Calendar API geben Sie Zeitzonen mithilfe von 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 Abfrageergebnisse auch als Standardzeitzone bezeichnet. Die Kalenderzeitzone beeinflusst, wie Zeitwerte von den Methoden events.get(), events.list() und events.instances() interpretiert oder dargestellt werden.

Zeitzonenumrechnung des Abfrageergebnisses
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 allen diesen Methoden die Kalenderzeitzone als Standard verwendet.
Ganztägige Ereignisse mit Abfragen in Zeitreihen abgleichen
Mit den Methoden list() und instances() können Sie Start- und Endzeitfilter angeben, wobei die Methode Instanzen zurückgibt, die in den angegebenen Bereich fallen. Die Kalenderzeitzone wird verwendet, um die Start- und Endzeiten ganztägiger Ereignisse zu berechnen, um festzustellen, ob sie unter die Filterspezifikation fallen.

Terminzeitzone

Ereignisinstanzen haben eine Start- und Endzeit. Die Angabe für diese Zeiten kann die Zeitzone enthalten. Sie können die Zeitzone auf verschiedene Arten angeben, wobei alle Elemente dieselbe Zeit angeben:

  • Geben Sie im Feld dateTime einen Zeitzonenversatz an, z. B. 2017-01-25T09:00:00-0500.
  • Geben Sie die Zeit ohne Zeitverschiebung an, z. B. 2017-01-25T09:00:00 und lassen Sie das Feld timeZone leer. Dabei wird implizit die Standardzeitzone verwendet.
  • Geben Sie die Zeit ohne Zeitverschiebung an, z. B. 2017-01-25T09:00:00, aber verwenden Sie das Feld timeZone, um die Zeitzone anzugeben.

Du kannst die Termine auch in UTC angeben:

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

Die interne Darstellung der Terminzeit ist in allen diesen Fällen gleich. Wenn Sie jedoch das Feld timeZone festlegen, wird dem Termin eine Zeitzone hinzugefügt, genau wie beim Festlegen einer Terminzeitzone über die Kalender-UI:

Screenshot-Fragment mit Zeitzone für ein Ereignis

Zeitzone für wiederkehrende Termine

Bei wiederkehrenden Terminen muss immer eine Zeitzone angegeben werden. Es wird benötigt, um die Wiederholungen des Ereignisses zu erweitern.