Kalender und Termine

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

Kalender

Kalender ist eine Sammlung verwandter Ereignisse sowie zusätzliche Metadaten. wie Zusammenfassung, Standardzeitzone, Ort usw. durch eine ID, bei der es sich um eine E-Mail-Adresse handelt. Kalender können mehrere Eigentümer haben.

Ereignisse

Ein Ereignis ist ein Objekt, das mit einem bestimmten Datum oder Zeitbereich verknüpft ist. Ereignisse werden durch eine eindeutige ID identifiziert. Neben dem Start und der Enddatum und -zeit können Ereignisse andere Daten enthalten, z. B. Zusammenfassung, Beschreibung, Standort, 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. Geplante Ereignisse können Sie mit den Feldern start.dateTime und end.dateTime festlegen, auftreten.
  • Ganztägige Termine können sich über einen ganzen Tag oder auf eine Reihe aufeinanderfolgender Tage erstrecken. Ganztägig Ereignisse verwenden die Felder start.date und end.date, um anzugeben, wann sie auftreten. Beachten Sie, dass das Zeitzonenfeld für ganztägige Termine keine Bedeutung hat.

Organisatoren

Für Termine gibt es einen einzigen Organisator. Das ist der Kalender mit dem Haupttext. der Veranstaltung. Ereignisse können auch mehrere Teilnehmer. Ein Gast ist normalerweise der Hauptkalender eines eingeladenen Nutzers.

Das folgende Diagramm zeigt die konzeptionelle Beziehung zwischen Kalendern, -Ereignisse und andere verwandte Elemente:

Primäre Kalender und weitere Kalender

Ein primärer Kalender ist eine spezielle Art von Kalender, die mit einem einzelnen Nutzerkonto. Dieser Kalender wird automatisch für jedes neue Nutzerkonto erstellt. und die ID stimmt normalerweise mit der primären E-Mail-Adresse des Nutzers überein. Solange das Feld vorhanden ist, kann der Hauptkalender nie gelöscht werden durch die Nutzer. Es kann jedoch weiterhin mit anderen Nutzern geteilt werden.

Zusätzlich zum Hauptkalender können Sie explizit beliebig viele Kalender andere Kalender, können diese Kalender geändert, gelöscht und freigegeben werden. für mehrere Nutzende.

Kalender und Kalenderliste

Die Sammlung Kalender steht für alle vorhandenen Kalender. Sie kann zum Erstellen und Löschen Kalender. Sie können auch globale Eigenschaften abrufen oder festlegen, die für alle Nutzer mit Zugriff auf einen Kalender Zum Beispiel Titel und Standardeinstellung eines Kalenders. Zeitzonen sind globale Properties.

Die CalendarList ist ein Sammlung aller Kalendereinträge, die ein Nutzer zu seiner Liste hinzugefügt hat (siehe im linken Bereich der Web-UI). Sie können damit vorhandene Kalender zur/von der Nutzerliste hinzu. Sie verwenden es auch zum Abrufen und Festlegen des nutzerspezifischen Kalendereigenschaften, z. B. Standarderinnerungen, Anderes Beispiel ist die Vordergrundfarbe, da verschiedene Nutzer unterschiedliche Farben Kalender für denselben Kalender.

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. In diesem Kalender werden standardmäßig wurde 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 ab, z.B. Titel, Zeitzone. Ruft Metadaten plus nutzerspezifische Anpassungen ab. z. B. Farben oder Erinnerungen überschreiben.
patch/update Ändert Kalendermetadaten. Ändert benutzerspezifische Kalendereigenschaften.

Wiederkehrende Termine

Manche Termine finden mehrmals in regelmäßigen Abständen statt, z. B. wöchentliche Meetings, 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 Felder „start“ und „end“ (die das erste Vorkommen definieren, als ein eigenständiges Einzelereignis,

  • Das Feld für die Wiederholung, mit dem definiert wird, wie sich das Ereignis im Laufe der Zeit wiederholen soll.

Das Feld für die Wiederholung enthält ein Array von Zeichenfolgen, die einen oder mehrere darstellen. Eigenschaften RRULE, RDATE oder EXDATE, wie in RFC definiert 5545.

Das Attribut RRULE ist am wichtigsten, da es eine reguläre Regel für den Termin wiederholen. Es besteht aus mehreren Komponenten. Dazu zählen:

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

  • INTERVAL: In Kombination mit FREQ gibt es an, wie oft das Ereignis ausgelöst wird. sollte wiederholt werden. FREQ=DAILY;INTERVAL=2 bedeutet beispielsweise einmal pro 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: Wochentage, an denen der Termin wiederholt werden soll (SU, MO, TU usw.). Weitere ähnliche Komponenten sind BYMONTH, BYYEARDAY und BYHOUR

Mit der Eigenschaft RDATE werden zusätzliche Daten oder Datum-Uhrzeiten für die Veranstaltung angegeben. auftreten sollten. Beispiel: RDATE;VALUE=DATE:19970101,19970120. Hiermit können Sie weitere Vorkommen hinzufügen, die nicht von RRULE abgedeckt werden.

Die Eigenschaft EXDATE ähnelt RDATE, gibt jedoch Daten oder Datum/Uhrzeit an wann das Ereignis nicht eintreten sollte. Diese Vorkommnisse sollten also ausgeschlossen. 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 ein Datum sein (kein Datum-Uhrzeit). für ganztägige Termine.

Jede der Eigenschaften kann mehrmals im Feld für die Wiederholung erscheinen. Die Wiederholung ist definiert als Vereinigung aller RRULE- und RDATE-Regeln, abzüglich der Durch alle EXDATE-Regeln ausgeschlossene Ausdrücke

Hier einige Beispiele für wiederkehrende Ereignisse:

  1. Ein Ereignis, das jeden Dienstag und Freitag von 6:00 bis 7:00 Uhr stattfindet, beginnt ab dem 15. September 2015 und endet 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 alle drei Tage wiederholt wird im Laufe des Monats, außer dem 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 wiederkehrender Termin besteht aus mehreren Instanzen, die jeweils auftreten. zu unterschiedlichen Zeiten. Diese Instanzen fungieren selbst als Ereignisse.

Wiederkehrende Ereignisänderungen können sich wiederkehrender Termin (und alle zugehörigen Instanzen) oder nur einzelne Instanzen. Instanzen, die sich von ihrem übergeordneten wiederkehrenden Termin unterscheiden, werden als Ausnahmen bezeichnet.

Eine Ausnahme kann z. B. eine andere Zusammenfassung, eine andere Startzeit, oder zusätzliche Gäste, die nur zu dieser Instanz eingeladen wurden. Sie können auch ein ohne den wiederkehrenden Termin zu entfernen, (Kündigungen von Instanzen werden im Ereignis berücksichtigt. status)

Beispiele für das Arbeiten mit wiederkehrenden Terminen und Instanzen über die 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

Sie können die Zeitzone sowohl für Kalender als auch für Termine festlegen. Die folgenden Abschnitte die Auswirkungen dieser Einstellungen.

Kalenderzeitzone

Die Zeitzone des Kalenders wird auch als Standardzeitzone bezeichnet, weil Auswirkungen auf Abfrageergebnisse. Die Kalenderzeitzone beeinflusst, Zeitwerte werden vom events.get(), events.list() und events.instances()-Methoden.

Zeitzonenkonvertierung für Abfrageergebnis
Ergebnisse der get(), list() und instances() Methoden werden in der Zeitzone zurückgegeben, die Sie in den timeZone-Tags angeben. . Wenn Sie diesen Parameter weglassen, verwenden alle diese Methoden den Kalender Zeitzone ausgewählt.
Ganztägige Termine mit Suchanfragen in Zeiträumen abgleichen
Die list() und instances() können Sie Start- und Endzeitfilter angeben, mit der Methode zurückgegebene Instanzen, die in den angegebenen Bereich fallen. Die Kalenderzeitzone wird verwendet, um die Start- und Endzeiten von ganztägigen Ereignissen zu berechnen und so zu ermitteln, ob sie der Filterspezifikation entsprechen.

Terminzeitzone

Ereignisinstanzen haben eine Start- und eine Endzeit. die Spezifikation für diese Zeiten kann die Zeitzone enthalten. Es gibt mehrere Möglichkeiten, die Zeitzone anzugeben: die folgende geben alle dieselbe Zeit an:

  • 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 Feld timeZone 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 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 allen diesen Fällen gleich, Wenn Sie jedoch das Feld timeZone festlegen, wird dem Termin eine Zeitzone hinzugefügt, wenn Sie die Zeitzone für einen Termin im Kalender UI:

Screenshot-Fragment, das die Zeitzone für einen Termin zeigt

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.