In diesem Leitfaden werden Kalender, Termine und ihre Beziehung zueinander beschrieben.
Kalender
Ein Kalender ist eine Sammlung verwandter Termine mit zusätzlichen Metadaten wie Zusammenfassung, Standardzeitzone, Ort usw. Jeder Kalender wird durch eine ID identifiziert, bei der es sich um eine E-Mail-Adresse handelt. 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 Datum und Uhrzeit des Start- und Enddatums enthalten Termine weitere Daten wie Zusammenfassung, Beschreibung, Ort, Status, Erinnerungen, Anhänge usw.
Ereignistypen
Google Kalender unterstützt einzelne und wiederkehrende Termine:
- Ein einzelnes Ereignis stellt einen eindeutigen Vorkommnis dar.
- Ein wiederkehrendes Ereignis definiert mehrere Vorkommen.
Termine können auch zeitlich festgelegt oder ganztägig sein:
- Ein zeitgesteuertes Ereignis findet zwischen zwei bestimmten Zeitpunkten statt. Bei zeitgesteuerten Ereignissen wird mit den Feldern
start.dateTime
undend.dateTime
angegeben, wann sie auftreten. - Ganztägige Termine können sich über einen ganzen Tag oder auf eine Reihe aufeinanderfolgender Tage erstrecken. 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
Für Termine gibt es einen einzigen Organizer. Das ist der Kalender mit der Hauptkopie des Termins. An Veranstaltungen können auch mehrere Teilnehmer teilnehmen. Ein Gast ist normalerweise der Hauptkalender eines eingeladenen Nutzers.
Das folgende Diagramm zeigt die konzeptionelle Beziehung zwischen Kalendern, Terminen und anderen verwandten 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 stimmt normalerweise mit der primären E-Mail-Adresse des Nutzers überein. Solange das Konto vorhanden ist, kann der Hauptkalender niemals gelöscht werden oder dem Nutzer nicht mehr gehören. Es kann jedoch weiterhin mit anderen Nutzern geteilt werden.
Zusätzlich zum Hauptkalender können Sie explizit 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 repräsentiert alle vorhandenen Kalender. Damit lassen sich Kalender erstellen und löschen. 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 Attribute.
Die CalendarList ist eine Sammlung aller Kalendereinträge, die ein Nutzer zu seiner Liste hinzugefügt hat. Sie wird im linken Bereich der Web-UI angezeigt. Sie können Kalender zur Nutzerliste 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 für denselben Kalender unterschiedliche Farben festlegen können.
In der folgenden Tabelle wird die Bedeutung der Vorgänge für die beiden Sammlungen verglichen:
Vorgang | Kalender | CalendarList |
---|---|---|
insert |
Ein neuer sekundärer Kalender wird erstellt. 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 Liste des Nutzers. |
get |
Ruft Kalendermetadaten wie den Titel und die Zeitzone ab. | Ruft Metadaten plus nutzerspezifische Anpassungen ab, z. B. Farben oder Überschreibungserinnerungen. |
patch /update |
Ändert Kalendermetadaten. | Ändert nutzerspezifische Kalendereigenschaften. |
Wiederkehrende Termine
Einige Ereignisse finden mehrmals in einem regelmäßigen Zeitplan statt, z. B. wöchentliche Besprechungen, Geburtstage und Feiertage. Abgesehen von unterschiedlichen Start- und Endzeiten sind diese wiederholten Ereignisse oft identisch.
Termine gelten als wiederkehrend, wenn sie sich nach einem festgelegten Zeitplan wiederholen. Einzelne Termine sind nicht-wiederkehrend und finden nur einmal statt.
Wiederholungsregel
Der Zeitplan für einen wiederkehrenden Termin besteht aus zwei Teilen:
Die Start- und Endfelder (die das erste Vorkommen definieren, als ob es sich nur um ein einzelnes Ereignis handelt) und
Das Feld für die Wiederholung, mit dem definiert wird, wie sich das Ereignis im Laufe der Zeit wiederholen soll.
Das Wiederholungsfeld enthält ein Array von Strings, die eine oder mehrere RRULE
-, RDATE
- oder EXDATE
-Eigenschaften 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 zählen:
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.FREQ=DAILY;INTERVAL=2
bedeutet beispielsweise alle zwei Tage.COUNT
: Häufigkeit, mit der dieses Ereignis wiederholt werden soll.UNTIL
: Datum oder Uhrzeit, bis zu der das Ereignis wiederholt werden soll (einschließlich).BYDAY
: die 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 Daten oder Datum-Uhrzeiten angegeben, zu denen das Ereignis eintreten soll. Beispiel: RDATE;VALUE=DATE:19970101,19970120
.
Hiermit können Sie weitere Vorkommen hinzufügen, die nicht von RRULE
abgedeckt werden.
Das Attribut EXDATE
ähnelt dem RDATE, gibt jedoch Daten oder Datum und Uhrzeit an, zu denen das Ereignis nicht stattfinden soll. Diese Vorkommen 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 ein Datum (kein Datum-Uhrzeit) sein.
Jede der Eigenschaften kann mehrmals im Feld für die Wiederholung erscheinen.
Die Wiederholung ist als Vereinigung aller RRULE
- und RDATE
-Regeln definiert, abzüglich derjenigen, die von allen EXDATE
-Regeln ausgeschlossen sind.
Hier einige Beispiele für wiederkehrende Ereignisse:
Ein Ereignis, das vom 15. September 2015 an jedem Dienstag und Freitag von 6:00 bis 7:00 Uhr stattfindet und nach dem fünften Mal 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 alle 3 Tage des Monats wiederholt wird. Ausgenommen hiervon ist der 10. Juni und der 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 wiederkehrender Termin besteht aus mehreren Instanzen, die zu unterschiedlichen Zeiten vorkommen. Diese Instanzen fungieren selbst als Ereignisse.
Wiederkehrende Ereignisänderungen können sich entweder auf das gesamte wiederkehrende Ereignis (und alle zugehörigen Instanzen) oder nur auf einzelne Instanzen auswirken. Instanzen, die sich von ihrem übergeordneten wiederkehrenden Termin unterscheiden, werden als Ausnahmen bezeichnet.
Beispielsweise kann eine Ausnahme 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 abbrechen, ohne den wiederkehrenden Termin zu entfernen. Absagen von Instanzen werden im Termin status
berücksichtigt.
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, für die eine einheitliche Standardzeit gilt. 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.
- Zeitzonenkonvertierung für Abfrageergebnis
- Die Ergebnisse der Methoden
get()
,list()
undinstances()
werden in der Zeitzone zurückgegeben, die Sie im ParametertimeZone
angeben. Wenn Sie diesen Parameter weglassen, wird für alle Methoden die Kalenderzeitzone als Standard verwendet. - Ganztägige Termine mit Suchanfragen in Zeiträumen 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. Anhand der Kalenderzeitzone werden die Anfangs- und Endzeiten von ganztägigen Terminen berechnet, 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 die gleiche Zeit angeben:
- Geben Sie im Feld
dateTime
einen Zeitzonenversatz 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 FeldtimeZone
leer (dadurch 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.
Wenn Sie möchten, können Sie die Zeiten des Termins auch in UTC angeben:
- Geben Sie die Zeit in UTC an:
2017-01-25T14:00:00Z
oder verwenden Sie einen Nullversatz von2017-01-25T14:00:00+0000
.
Die interne Darstellung der Terminzeit ist in allen diesen Fällen gleich, aber wenn Sie das Feld timeZone
festlegen, wird dem Termin eine Zeitzone zugewiesen, genau wie beim Festlegen der Zeitzone für den Termin über die Kalender-UI:
Zeitzone für wiederkehrende Termine
Bei wiederkehrenden Terminen muss immer eine einzige Zeitzone angegeben werden. Dies ist erforderlich, damit die Wiederholungen des Termins verlängert werden können.