Diese Seite wurde von der Cloud Translation API übersetzt.

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 durch eine eindeutige 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 mit den Feldern start.date und end.date angegeben, wann sie stattfinden. Das Feld „Zeitzone“ hat für ganztägige Termine keine Bedeutung.

Der Beginn und das Ende der Veranstaltung müssen entweder zeitlich festgelegt oder ganztägig sein. Es ist beispielsweise unzulässig, start.date und end.dateTime anzugeben.

Organisatoren

Termine haben einen einzelnen Organisator, also den Kalender, der die Hauptkopie des Termins enthält. Ereignisse 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 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 der primäre Kalender nicht gelöscht oder die Inhaberschaft nicht aufgehoben werden. Es 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 repräsentiert 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 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`	Erstellt einen neuen sekundären Kalender. Dieser Kalender wird standardmäßig auch der Kalenderliste des Creators 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 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. Einzelne 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 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.

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

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.

Sie können entweder COUNT oder UNTIL verwenden, um das Ende der Wiederholung des Ereignisses anzugeben. Verwenden Sie nicht beides in derselben Regel.
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 weitere Vorkommen hinzufügen, die nicht von RRULE abgedeckt werden.

Die Property EXDATE ähnelt RDATE, gibt aber Datumsangaben oder Uhrzeiten an, an denen das Ereignis nicht stattfinden soll. Das heißt, diese Vorkommen sollten 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 und eine 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:

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"
],
…

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 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, 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 Kalender API finden Sie hier.

Zeitzonen

Eine Zeitzone gibt eine Region an, für die 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 beeinflusst, 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 für alle Methoden die Kalenderzeitzone als Standard 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 Kalenderzeitzone werden die Anfangs- und Endzeiten von ganztägigen Terminen berechnet, um festzustellen, ob sie unter die Filterspezifikation 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 Zeitversatz 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.

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 von 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.