Arbeiten mit Serienregeln in den Outlook-REST-APIs

Ereignisserien sind ein wichtiger Bestandteil der Kalenderfunktionen von Outlook. Ganz gleich, ob es sich um eine wöchentliche Besprechung mit Ihrem Vorgesetzten oder eine Abteilungsbesprechung handelt, die jeden zweiten Dienstag im Monat stattfindet, mit Ereignisserien können Sie ganz einfach eine Ereignisserie erstellen und der Server füllt den Kalender mit dem Rest der Serie.

Die wichtigsten Informationen, mit denen Ereignisserien in einzelne Termine „erweitert“ werden können, die Serienregel. In der Serie ist die Wiederholungsfrequenz und Dauer eines Ereignisses angegeben. Die Outlook-REST-APIs modellieren Serienregeln in der recurrence-Eigenschaft der -Ereignisressource. Jeder recurrence besteht aus zwei Teilen: dem Serienmuster (wie oft) und dem Serienbereich (für wie lange).

Serienmuster

Der erste Teil einer Serie ist das Muster. Darin ist angegeben, wie oft das Ereignis wiederholt wird. Beispielsweise könnte ein Ereignis „alle 3 Tage“, „jeden Donnerstag“ oder „jedes Jahr am 22. Juli“ wiederholt werden. Ein Muster wird in der-API durch die RecurrencePattern-Ressource dargestellt.

Je nach Mustertyp sind bestimmte Felder des recurrencePattern obligatorisch, optional oder werden ignoriert.

Hinweis

Auch wenn Sie ein Feld ignoriert wird, wird es dennoch überprüft. Wenn ein Feld über eine festgelegte Liste möglicher Werte verfügt, führt ein Wert außerhalb der zulässigen Gruppe von Werten zu einem Fehler, selbst wenn das Feld ignoriert wird.

Werfen Sie einen Blick auf die einzelnen Arten möglicher Muster.

Täglich

Das tägliche Serienmuster bewirkt, dass ein Ereignis basierend auf einer Anzahl von Tagen zwischen zwei Vorkommen wiederholt wird.

Relevante Eigenschaften

Eigenschaft Relevanz Beschreibung
interval Erforderlich Gibt die Anzahl der Tage zwischen zwei Vorkommen an.
type Erforderlich Muss auf daily festgelegt werden.

Beispiele

  • Dieses Ereignis täglich wiederholen

    "pattern": {
      "type": "daily",
      "interval": 1
    }
    
  • Dieses Ereignis alle drei Tage wiederholen

    "pattern": {
      "type": "daily",
      "interval": 3
    }
    

Wöchentlich

Das wöchentliche Serienmuster bewirkt, dass ein Ereignis am gleichen Tag oder an den gleichen Tagen einer Woche basierend auf der Anzahl von Wochen zwischen zwei Vorkommen wiederholt wird.

Relevante Eigenschaften

Eigenschaft Relevanz Beschreibung
daysOfWeek Erforderlich Gibt an, an welchem/-n Tag/-en der Woche das Ereignis eintritt.
firstDayOfWeek Optional Gibt an, welcher Tag als erster Tag der Woche angesehen wird. Standardwert: Sunday.
interval Erforderlich Gibt die Anzahl der Wochen zwischen zwei Vorkommen an.
type Erforderlich Muss auf weekly festgelegt werden.

Beispiele

  • Dieses Ereignis jeden Donnerstag wiederholen

    "pattern": {
      "type": "weekly",
      "interval": 1,
      "daysOfWeek": [ "Thursday" ]
    }
    
  • Dieses Ereignis jeden Montag und Dienstag wiederholen

    "pattern": {
      "type": "weekly",
      "interval": 2,
      "daysOfWeek": [
        "Monday",
        "Tuesday"
      ]
    }
    

Absolut monatlich

Das absolute monatliche Muster bewirkt, dass ein Ereignis jeden Monat am gleichen Tag (z. B. dem 15.) basierend auf der Anzahl der Monate zwischen zwei Vorkommen stattfindet.

Relevante Eigenschaften

Eigenschaft Relevanz Beschreibung
dayOfMonth Erforderlich Gibt an, an welchem Tag des Monats das Ereignis eintritt.
interval Erforderlich Gibt die Anzahl der Monate zwischen zwei Vorkommen an.
type Erforderlich Muss auf absoluteMonthly festgelegt werden.

Beispiele

  • Dieses Ereignis jeden Monat am 15. wiederholen

    "pattern": {
      "type": "absoluteMonthly",
      "interval": 1,
      "dayOfMonth": 15
    }
    
  • Dieses Ereignis vierteljährlich (alle 3 Monate) am 7. wiederholen

    "pattern": {
      "type": "absoluteMonthly",
      "interval": 3,
      "dayOfMonth": 7
    }
    

Relativ monatlich

Das relative monatliche Muster bewirkt, dass ein Ereignis am gleichen Wochentag an der gleichen relativen Position des Monats basierend auf der Anzahl der Monate zwischen zwei Vorkommen stattfindet. Beispielsweise „jeden zweiten Mittwoch des Monats“.

Relevante Eigenschaften

Eigenschaft Relevanz Beschreibung
daysOfWeek Erforderlich Gibt an, an welchem/-n Tag/-en der Woche das Ereignis eintreten kann. Relative monatliche Ereignisse treten nur einmal pro Monat ein, wird also mehr als ein Wert angegeben, fällt das Ereignis auf den ersten Tag, der das Muster erfüllt.
index Optional Gibt an, in welcher Instanz der zulässigen Tage, die unter daysOfsWeek angegeben sind, das Ereignis eintritt, ausgehend von der ersten Instanz des Monats gezählt. Mögliche Werte: first, second, third, fourth und last. Standardwert: first.
interval Erforderlich Gibt die Anzahl der Monate zwischen zwei Vorkommen an.
type Erforderlich Muss auf relativeMonthly festgelegt werden.

Beispiele

  • Dieses Ereignis jeden zweiten Mittwoch des Monats wiederholen

    "pattern": {
      "type": "relativeMonthly",
      "interval": 1,
      "daysOfWeek": [ "Wednesday" ],
      "index": "second"
    }
    
  • Dieses Ereignis jeden zweiten Mittwoch des Monats wiederholen

    "pattern": {
      "type": "relativeMonthly",
      "interval": 1,
      "daysOfWeek": [ "Thursday", "Friday" ],
      "index": "first"
    }
    

Absolut jährlich

Das absolut jährliche Muster bewirkt, dass ein Ereignis jedes Jahr am gleichen Tag (z. B. dem 15. April) basierend auf der Anzahl der Jahre zwischen zwei Vorkommen stattfindet.

Relevante Eigenschaften

Eigenschaft Relevanz Beschreibung
dayOfMonth Erforderlich Gibt an, an welchem Tag des Monats das Ereignis eintritt.
month Erforderlich Gibt an, in welchem Monat das Ereignis auftritt.
interval Erforderlich Gibt die Anzahl der Jahre zwischen zwei Vorkommen an.
type Erforderlich Muss auf absoluteYearly festgelegt werden.

Beispiel

  • Dieses Ereignis jedes Jahr am 15. April wiederholen

    "pattern": {
      "type": "absoluteYearly",
      "interval": 1,
      "dayOfMonth": 15,
      "month": 4
    }
    

Relativ jährlich

Das relative jährliche Muster bewirkt, dass ein Ereignis am gleichen Wochentag an der gleichen relativen Position eines bestimmten Monats basierend auf der Anzahl der Jahre zwischen zwei Vorkommen stattfindet. Beispielsweise „jeden letzten Mittwoch im November“.

Relevante Eigenschaften

Eigenschaft Relevanz Beschreibung
daysOfWeek Erforderlich Gibt an, an welchem/-n Tag/-en der Woche das Ereignis eintreten kann. Relative jährliche Ereignisse treten nur einmal pro Jahr ein, wird also mehr als ein Wert angegeben, fällt das Ereignis auf den ersten Tag, der das Muster erfüllt.
index Optional Gibt an, in welcher Instanz der zulässigen Tage, die unter daysOfsWeek angegeben sind, das Ereignis eintritt, ausgehend von der ersten Instanz des Monats gezählt. Mögliche Werte: first, second, third, fourth und last. Standardwert: first.
month Erforderlich Gibt an, in welchem Monat das Ereignis auftritt.
interval Erforderlich Gibt die Anzahl der Jahre zwischen zwei Vorkommen an.
type Erforderlich Muss auf relativeMonthly festgelegt werden.

Beispiele

  • Dieses Ereignis jedes Jahr am letzten Mittwoch im November wiederholen

    "pattern": {
      "type": "relativeYearly",
      "interval": 1,
      "daysOfWeek": [ "Wednesday" ],
      "index": "last",
      "month": 11
    }
    

Serienbereiche

Der zweite Teil einer Serie ist das Muster. Dies gibt an, wie lange das Muster wiederholt wird. Ein Ereignis könnte beispielsweise nach 10 Vorkommen an einem bestimmten Datum enden oder kein Ende haben. Ein Bereich wird in der-API durch die recurrenceRange-Ressource dargestellt.

Je nach Bereichstyp wsind bestimmte Felder des recurrenceRange obligatorisch oder werden ignoriert.

Hinweis

Auch wenn Sie ein Feld ignoriert wird, wird es dennoch überprüft. Wenn ein Feld über eine festgelegte Liste möglicher Werte verfügt, führt ein Wert außerhalb der zulässigen Gruppe von Werten zu einem Fehler, selbst wenn das Feld ignoriert wird.

Werfen wir einen Blick auf die einzelnen Arten möglicher Bereiche.

Nummerierter Bereich

Der nummerierte Bereich bewirkt, dass ein Ereignis eine feste Anzahl von Vorkommen (basierend auf dem Muster) ab einem Startdatum auftritt.

Relevante Eigenschaften

Eigenschaft Relevanz Beschreibung
numberOfOccurences Erforderlich Gibt die Anzahl von Vorkommen an. Das Vorkommen muss eine positive ganze Zahl sein.
recurrenceTimeZone Optional Gibt die Zeitzone für die startDate-Eigenschaft an. Falls nicht angegeben, wird die Zeitzone des Ereignisses verwendet.
startDate Erforderlich Gibt das Datum des Starts des Anwendens des Musters an. Der Wert des startDate MUSS dem Datumswert der start-Eigenschaft der -Ereignisressource entsprechen. Hinweis: das erste Vorkommen der Besprechung kann nicht an diesem Datum auftreten, wenn es nicht in das Muster passt.
type Erforderlich Muss auf numbered festgelegt werden.

Beispiele

  • Dieses Ereignis 10 Mal wiederholen

    "range": {
      "type": "numbered",
      "startDate": "2017-04-02",
      "numberOfOccurrences": 10
    }
    

Enddatumsbereich

Der Enddatumsbereich bewirkt, dass ein Ereignis an allen Tagen eintritt, die das entsprechende Muster zwischen einem Startdatum und einem Enddatum aufweisen.

Relevante Eigenschaften

Eigenschaft Relevanz Beschreibung
endDate Erforderlich Gibt das Datum zum Beenden des Anwendens des Musters an. Hinweis: das letzte Vorkommen der Besprechung kann nicht an diesem Datum auftreten, wenn es nicht in das Muster passt.
recurrenceTimeZone Optional Gibt die Zeitzone für die startDate- und endDate-Eigenschaften an. Falls nicht angegeben, wird die Zeitzone des Ereignisses verwendet.
startDate Erforderlich Gibt das Datum des Starts des Anwendens des Musters an. Der Wert des startDate MUSS dem Datumswert der start-Eigenschaft der -Ereignisressource entsprechen. Hinweis: das erste Vorkommen der Besprechung kann nicht an diesem Datum auftreten, wenn es nicht in das Muster passt.
type Erforderlich Muss auf endDate festgelegt werden.

Beispiele

  • Dieses Ereignis vom 1. Juli 2017 bis zum 31. Juli 2017 wiederholen

    "range": {
      "type": "endDate",
      "startDate": "2017-07-01",
      "endDate": "2017-07-31"
    }
    

Kein Endbereich

Der Enddatumsbereich bewirkt, dass ein Ereignis an allen Tagen eintritt, die dem anwendbaren Muster nach einem Startdatum entsprechen.

Relevante Eigenschaften

Eigenschaft Relevanz Beschreibung
recurrenceTimeZone Optional Gibt die Zeitzone für die startDate-Eigenschaft an. Falls nicht angegeben, wird die Zeitzone des Ereignisses verwendet.
startDate Erforderlich Gibt das Datum des Starts des Anwendens des Musters an. Der Wert des startDate MUSS dem Datumswert der start-Eigenschaft der -Ereignisressource entsprechen. Hinweis: das erste Vorkommen der Besprechung kann nicht an diesem Datum auftreten, wenn es nicht in das Muster passt.
type Erforderlich Muss auf noEnd festgelegt werden.

Beispiele

  • Dieses Ereignis ab dem 15. Mai 2017 immer wiederholen

    "range": {
      "type": "noEnd",
      "startDate": "2017-05-15"
    }
    

Verwenden von Mustern und Bereichen zum Erstellen von Ereignisserien

Nachdem wir uns nun Muster und Bereiche separat angesehen haben, schauen wir uns nun deren Zusammenwirken und Interagieren mit den start- und end-Eigenschaften zu dem Ereignis an.

Erstellen einer Serienregel

Um eine Serienregel zu erstellen, müssen Sie sowohl ein Muster als auch einen Bereich angeben. Jeder Mustertyp kann mit einem beliebigen Bereichstyp arbeiten. Im Folgenden finden Sie einige Beispiele:

  • Besprung von 13:00-13:30 Uhr, jeden Montag, ab dem 4. September 2017, bis zum Ende des Jahres

    • Die Anforderung „jeden Montag“ wird ganz einfach durch den weekly-Serienmustertyp erfüllt.
    • Die Anforderung „bis zum Ende des Jahres“ gibt einen endDate-Serienbereichstypen an.

      "recurrence": {
      "pattern": {
        "type": "weekly",
        "interval": 1,
        "daysOfWeek": [ "Monday" ]
      },
      "range": {
        "type": "endDate",
        "startDate": "2017-09-04",
        "endDate": "2017-12-31"
      }
      }
      

      Da der 31. Dezember 2017 auf einen Sonntag fällt, ist das letzte Vorkommen in dieser Serie am Montag, den 25. Dezember.

  • Besprechung von 14:00-15:00 Uhr am ersten Donnerstag jeden anderen Monats, ab dem 29. August 2017

    • Die Anforderung „erster Donnerstag jeden anderen Monats“ kann durch ein relatives monatliches Muster erfüllt werden. Der Teil „jeden anderen Monats“ gibt an, dass das interval auf 2 festgelegt werden sollte.
    • Da es keine Anforderung an einem Enddatum gibt, kann ein noEnd-Bereichstyp verwendet werden.

      "recurrence": {
      "pattern": {
        "type": "relativeMonthly",
        "interval": 2,
        "daysOfWeek": [ "Thursday" ],
        "index": "first"
      },
      "range": {
        "type": "noEnd",
        "startDate": "2017-08-29"
      }
      }
      

      Da der Wert des startDate nach dem ersten Donnerstag im August liegt, ist das erste Vorkommen dieser Serie im September.