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
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
undend.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
undend.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
oderWEEKLY
). Erforderlich.INTERVAL
: In Kombination mitFREQ
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 sindBYMONTH
,BYYEARDAY
undBYHOUR
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:
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" ], …
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
Wiederkehrende Termine bestehen aus mehreren Instanzen. 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()
undinstances()
Methoden werden in der Zeitzone zurückgegeben, die Sie in dentimeZone
-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()
undinstances()
können Sie Start- und Endzeitsfilter 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 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 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:
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.