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
undend.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
undend.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
oderWEEKLY
). Erforderlich.INTERVAL
: Gibt zusammen mitFREQ
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 sindBYMONTH
,BYYEARDAY
undBYHOUR
.
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:
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" ], …
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()
undinstances()
werden in der Zeitzone zurückgegeben, die Sie im ParametertimeZone
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()
undinstances()
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 FeldtimeZone
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 FeldtimeZone
, um die Zeitzone anzugeben.
Du kannst die Termine auch in UTC angeben:
- Gib die Zeit in UTC an:
2017-01-25T14:00:00Z
oder verwende2017-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:
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.