Arbeiten mit Serienregeln in den Outlook-REST-APIsWorking with recurrence rules in the Outlook REST APIs

Ereignisserien sind ein wichtiger Bestandteil der Kalenderfunktionen von Outlook.Recurring events are an important part of Outlook calendaring. 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.Whether it's a weekly one-on-one meeting with your manager, or a division-wide review meeting that happens on the second Tuesday of each month, recurring events make it easy to create the event once, and let the server fill in the rest of the series.

Die wichtigsten Informationen, mit denen Ereignisserien in einzelne Termine „erweitert“ werden können, die Serienregel.The key bit of information that allows recurring events to "expand" into individual occurrences is the recurrence rule. In der Serie ist die Wiederholungsfrequenz und Dauer eines Ereignisses angegeben.The rule specifies both how often an event repeats, and for how long. Die Outlook-REST-APIs modellieren Serienregeln in der recurrence-Eigenschaft der -Ereignisressource.The Outlook REST APIs model recurrence rules in the recurrence property of the event resource. Jeder recurrence besteht aus zwei Teilen: dem Serienmuster (wie oft) und dem Serienbereich (für wie lange).Each recurrence is made up of two parts: the recurrence pattern (how often), and the recurrence range (for how long).

SerienmusterRecurrence patterns

Der erste Teil einer Serie ist das Muster.The first part of a recurrence is the pattern. Darin ist angegeben, wie oft das Ereignis wiederholt wird.This specifies how often the event repeats. Beispielsweise könnte ein Ereignis „alle 3 Tage“, „jeden Donnerstag“ oder „jedes Jahr am 22. Juli“ wiederholt werden.For example, an event could repeat "every 3 days", "every Thursday", or "on July 22 every year". Ein Muster wird in der-API durch die RecurrencePattern-Ressource dargestellt.A pattern is represented in the API by the recurrencePattern resource.

Je nach Mustertyp sind bestimmte Felder des recurrencePattern obligatorisch, optional oder werden ignoriert.Depending on the type of pattern, certain fields of the recurrencePattern are required, optional, or ignored.

Hinweis

Auch wenn Sie ein Feld ignoriert wird, wird es dennoch überprüft.Even if a field is ignored, it is still validated. 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.If a field has a set list of possible values, using a value outside the allowed set will cause an error, even if that field is ignored.

Werfen Sie einen Blick auf die einzelnen Arten möglicher Muster.Let's take a look at each of the possible pattern types.

TäglichDaily news

Das tägliche Serienmuster bewirkt, dass ein Ereignis basierend auf einer Anzahl von Tagen zwischen zwei Vorkommen wiederholt wird.The daily recurrence pattern causes an event to repeat based on a number of days between each occurrence.

Relevante EigenschaftenRelevant properties

EigenschaftProperty RelevanzRelevance BeschreibungDescription
interval ErforderlichRequired Gibt die Anzahl der Tage zwischen zwei Vorkommen an.Specifies the number of days between each occurrence.
type ErforderlichRequired Muss auf daily festgelegt werden.Required. Must be set to daily.

BeispieleExamples

  • Dieses Ereignis täglich wiederholenRepeat this event every day

    "pattern": {
      "type": "daily",
      "interval": 1
    }
    
  • Dieses Ereignis alle drei Tage wiederholenRepeat this event every three days

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

WöchentlichWeekly

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.The weekly recurrence pattern causes an event to repeat on the same day or days of the week, based on the number of weeks between each set of occurrences.

Relevante EigenschaftenRelevant properties

EigenschaftProperty RelevanzRelevance BeschreibungDescription
daysOfWeek ErforderlichRequired Gibt an, an welchem/-n Tag/-en der Woche das Ereignis eintritt.Specifies on which day(s) of the week the event occurs.
firstDayOfWeek OptionalOptional Gibt an, welcher Tag als erster Tag der Woche angesehen wird.Specifies which day is considered the first day of the week. Standardwert: Sunday.Sunday
interval ErforderlichRequired Gibt die Anzahl der Wochen zwischen zwei Vorkommen an.Specifies the number of weeks between each set of occurrences.
type ErforderlichRequired Muss auf weekly festgelegt werden.Required. Must be set to weekly.

BeispieleExamples

  • Dieses Ereignis jeden Donnerstag wiederholenRepeat this event every Thursday

    "pattern": {
      "type": "weekly",
      "interval": 1,
      "daysOfWeek": [ "Thursday" ]
    }
    
  • Dieses Ereignis jeden Montag und Dienstag wiederholenRepeat this event every other Monday and Tuesday

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

Absolut monatlichAbsolute monthly

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.The absolute monthly pattern causes an event to repeat on the same day of the month (e.g. the 15th), based on the number of months between each occurrence.

Relevante EigenschaftenRelevant properties

EigenschaftProperty RelevanzRelevance BeschreibungDescription
dayOfMonth ErforderlichRequired Gibt an, an welchem Tag des Monats das Ereignis eintritt.The day of the month that the event occurs on.
interval ErforderlichRequired Gibt die Anzahl der Monate zwischen zwei Vorkommen an.Specifies the number of months between each occurrence.
type ErforderlichRequired Muss auf absoluteMonthly festgelegt werden.Required. Must be set to absoluteMonthly.

BeispieleExamples

  • Dieses Ereignis jeden Monat am 15. wiederholenRepeat this event on the 15th of every month

    "pattern": {
      "type": "absoluteMonthly",
      "interval": 1,
      "dayOfMonth": 15
    }
    
  • Dieses Ereignis vierteljährlich (alle 3 Monate) am 7. wiederholenRepeat this event quarterly (every 3 months) on the 7th

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

Relativ monatlichRelative monthly

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.The relative monthly pattern causes an event to repeat on the same day of the week in the same relative position in the month, based on the number of months between each occurrence. Beispielsweise „jeden zweiten Mittwoch des Monats“.For example, "every second Wednesday of the month".

Relevante EigenschaftenRelevant properties

EigenschaftProperty RelevanzRelevance BeschreibungDescription
daysOfWeek ErforderlichRequired Gibt an, an welchem/-n Tag/-en der Woche das Ereignis eintreten kann.Specifies on which day(s) of the week the event can occur. 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.Relative monthly events only occur once per month, so if more than one value is specified, the event falls on the first day that satisfies the pattern.
index OptionalOptional 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.Specifies on which instance of the allowed days specified in daysOfsWeek the event occurs, counted from the first instance in the month. Mögliche Werte: first, second, third, fourth und last.Possible values: first, second, third, fourth, and last. Standardwert: first.first
interval ErforderlichRequired Gibt die Anzahl der Monate zwischen zwei Vorkommen an.Specifies the number of months between each occurrence.
type ErforderlichRequired Muss auf relativeMonthly festgelegt werden.Required. Must be set to relativeMonthly.

BeispieleExamples

  • Dieses Ereignis jeden zweiten Mittwoch des Monats wiederholenRepeat this event on the second Wednesday of every month

    "pattern": {
      "type": "relativeMonthly",
      "interval": 1,
      "daysOfWeek": [ "Wednesday" ],
      "index": "second"
    }
    
  • Dieses Ereignis jeden zweiten Mittwoch des Monats wiederholenRepeat this event on the first Thursday or Friday of every month

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

Absolut jährlichAbsolute yearly

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.The absolute yearly pattern causes an event to repeat on the same month and day (e.g. April 15th), based on the number of years between each occurrence.

Relevante EigenschaftenRelevant properties

EigenschaftProperty RelevanzRelevance BeschreibungDescription
dayOfMonth ErforderlichRequired Gibt an, an welchem Tag des Monats das Ereignis eintritt.The day of the month that the event occurs on.
month ErforderlichRequired Gibt an, in welchem Monat das Ereignis auftritt.Specifies in which month the event occurs.
interval ErforderlichRequired Gibt die Anzahl der Jahre zwischen zwei Vorkommen an.Specifies the number of years between each occurrence.
type ErforderlichRequired Muss auf absoluteYearly festgelegt werden.Required. Must be set to absoluteYearly.

BeispielExample

  • Dieses Ereignis jedes Jahr am 15. April wiederholenRepeat this event on April 15 every year

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

Relativ jährlichRelative yearly

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.The relative yearly pattern causes an event to repeat on the same day of the week in the same relative position in a specific month, based on the number of years between each occurrence. Beispielsweise „jeden letzten Mittwoch im November“.For example, "every last Wednesday of November".

Relevante EigenschaftenRelevant properties

EigenschaftProperty RelevanzRelevance BeschreibungDescription
daysOfWeek ErforderlichRequired Gibt an, an welchem/-n Tag/-en der Woche das Ereignis eintreten kann.Specifies on which day(s) of the week the event can occur. 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.Relative yearly events only occur once per year, so if more than one value is specified, the event falls on the first day that satisfies the pattern.
index OptionalOptional 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.Specifies on which instance of the allowed days specified in daysOfsWeek the event occurs, counted from the first instance in the month. Mögliche Werte: first, second, third, fourth und last.Possible values: first, second, third, fourth, and last. Standardwert: first.first
month ErforderlichRequired Gibt an, in welchem Monat das Ereignis auftritt.Specifies in which month the event occurs.
interval ErforderlichRequired Gibt die Anzahl der Jahre zwischen zwei Vorkommen an.Specifies the number of years between each occurrence.
type ErforderlichRequired Muss auf relativeMonthly festgelegt werden.Required. Must be set to relativeMonthly.

BeispieleExamples

  • Dieses Ereignis jedes Jahr am letzten Mittwoch im November wiederholenRepeat this event on the last Wednesday of November every year

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

SerienbereicheRecurrence ranges

Der zweite Teil einer Serie ist das Muster.The second part of a recurrence is the range. Dies gibt an, wie lange das Muster wiederholt wird.This specifies how long the pattern repeats. Ein Ereignis könnte beispielsweise nach 10 Vorkommen an einem bestimmten Datum enden oder kein Ende haben.For example, an event could end after 10 occurrences, by a specific date, or could have no end. Ein Bereich wird in der-API durch die recurrenceRange-Ressource dargestellt.A range is represented in the API by the recurrenceRange resource.

Je nach Bereichstyp wsind bestimmte Felder des recurrenceRange obligatorisch oder werden ignoriert.Depending on the type of range, certain fields of the recurrenceRange are required or ignored.

Hinweis

Auch wenn Sie ein Feld ignoriert wird, wird es dennoch überprüft.Even if a field is ignored, it is still validated. 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.If a field has a set list of possible values, using a value outside the allowed set will cause an error, even if that field is ignored.

Werfen wir einen Blick auf die einzelnen Arten möglicher Bereiche.Let's take a look at each of the possible range types.

Nummerierter BereichNumbered range

Der nummerierte Bereich bewirkt, dass ein Ereignis eine feste Anzahl von Vorkommen (basierend auf dem Muster) ab einem Startdatum auftritt.The numbered range causes an event to occur a fixed number of times (based on the pattern) from a start date.

Relevante EigenschaftenRelevant properties

EigenschaftProperty RelevanzRelevance BeschreibungDescription
numberOfOccurences ErforderlichRequired Gibt die Anzahl von Vorkommen an.Specifies the number of monitors Das Vorkommen muss eine positive ganze Zahl sein.Must be a positive integer.
recurrenceTimeZone OptionalOptional Gibt die Zeitzone für die startDate-Eigenschaft an.Specifies the time zone for the startDate property. Falls nicht angegeben, wird die Zeitzone des Ereignisses verwendet.If not specified, the time zone of the event is used.
startDate ErforderlichRequired Gibt das Datum des Starts des Anwendens des Musters an.Specifies the date to start applying the pattern. Der Wert des startDate MUSS dem Datumswert der start-Eigenschaft der -Ereignisressource entsprechen.The value of startDate MUST correspond to the date value of the start property on the event resource. Hinweis: das erste Vorkommen der Besprechung kann nicht an diesem Datum auftreten, wenn es nicht in das Muster passt.Note: the first occurrence of the meeting may not occur on this date if it does not fit the pattern.
type ErforderlichRequired Muss auf numbered festgelegt werden.Required. Must be set to numbered.

BeispieleExamples

  • Dieses Ereignis 10 Mal wiederholenRepeat this event 10 times

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

EnddatumsbereichEnd date range

Der Enddatumsbereich bewirkt, dass ein Ereignis an allen Tagen eintritt, die das entsprechende Muster zwischen einem Startdatum und einem Enddatum aufweisen.The end date range causes an event to occur on all days that fit the applicable pattern between a start date and an end date.

Relevante EigenschaftenRelevant properties

EigenschaftProperty RelevanzRelevance BeschreibungDescription
endDate ErforderlichRequired Gibt das Datum zum Beenden des Anwendens des Musters an.Specifies the date to stop applying the pattern. Hinweis: das letzte Vorkommen der Besprechung kann nicht an diesem Datum auftreten, wenn es nicht in das Muster passt.Note: the last occurrence of the meeting may not occur on this date if it does not fit the pattern.
recurrenceTimeZone OptionalOptional Gibt die Zeitzone für die startDate- und endDate-Eigenschaften an.Specifies the time zone for the startDate and endDate properties. Falls nicht angegeben, wird die Zeitzone des Ereignisses verwendet.If not specified, the time zone of the event is used.
startDate ErforderlichRequired Gibt das Datum des Starts des Anwendens des Musters an.Specifies the date to start applying the pattern. Der Wert des startDate MUSS dem Datumswert der start-Eigenschaft der -Ereignisressource entsprechen.The value of startDate MUST correspond to the date value of the start property on the event resource. Hinweis: das erste Vorkommen der Besprechung kann nicht an diesem Datum auftreten, wenn es nicht in das Muster passt.Note: the first occurrence of the meeting may not occur on this date if it does not fit the pattern.
type ErforderlichRequired Muss auf endDate festgelegt werden.Required. Must be set to endDate.

BeispieleExamples

  • Dieses Ereignis vom 1. Juli 2017 bis zum 31. Juli 2017 wiederholenRepeat this event from July 1 2017 to July 31 2017

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

Kein EndbereichNo end range

Der Enddatumsbereich bewirkt, dass ein Ereignis an allen Tagen eintritt, die dem anwendbaren Muster nach einem Startdatum entsprechen.The no end range causes an event to occur on all days that fit the applicable pattern after a start date.

Relevante EigenschaftenRelevant properties

EigenschaftProperty RelevanzRelevance BeschreibungDescription
recurrenceTimeZone OptionalOptional Gibt die Zeitzone für die startDate-Eigenschaft an.Specifies the time zone for the startDate property. Falls nicht angegeben, wird die Zeitzone des Ereignisses verwendet.If not specified, the time zone of the event is used.
startDate ErforderlichRequired Gibt das Datum des Starts des Anwendens des Musters an.Specifies the date to start applying the pattern. Der Wert des startDate MUSS dem Datumswert der start-Eigenschaft der -Ereignisressource entsprechen.The value of startDate MUST correspond to the date value of the start property on the event resource. Hinweis: das erste Vorkommen der Besprechung kann nicht an diesem Datum auftreten, wenn es nicht in das Muster passt.Note: the first occurrence of the meeting may not occur on this date if it does not fit the pattern.
type ErforderlichRequired Muss auf noEnd festgelegt werden.Required. Must be set to noEnd.

BeispieleExamples

  • Dieses Ereignis ab dem 15. Mai 2017 immer wiederholenRepeat this event from May 15 2017 forever

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

Verwenden von Mustern und Bereichen zum Erstellen von EreignisserienUsing patterns and ranges to create recurring events

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.Now that we've looked at patterns and ranges separately, let's look at how they work together and how they interact with the start and end properties on the event.

Erstellen einer SerienregelCreating a recurrence rule

Um eine Serienregel zu erstellen, müssen Sie sowohl ein Muster als auch einen Bereich angeben.In order to create a recurrence rule, you must specify both a pattern and a range. Jeder Mustertyp kann mit einem beliebigen Bereichstyp arbeiten.Any pattern type can work with any range type. Im Folgenden finden Sie einige Beispiele:Here are a couple of examples of the request.

  • Besprung von 13:00-13:30 Uhr, jeden Montag, ab dem 4. September 2017, bis zum Ende des JahresMeet from 1:00 PM to 1:30 PM every Monday starting September 4, 2017 until the end of the year

    • Die Anforderung „jeden Montag“ wird ganz einfach durch den weekly-Serienmustertyp erfüllt.The "every Monday" requirement is easily met by the weekly recurrence pattern type.
    • Die Anforderung „bis zum Ende des Jahres“ gibt einen endDate-Serienbereichstypen an.The "until the end of the year" requirement indicates an endDate recurrence range type.

      "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.Because December 31, 2017 is on a Sunday, the last occurrence in this series will be on Monday, December 25.

  • Besprechung von 14:00-15:00 Uhr am ersten Donnerstag jeden anderen Monats, ab dem 29. August 2017Meet from 2:00 PM to 3:00 PM on the first Thursday of every other month starting August 29, 2017

    • Die Anforderung „erster Donnerstag jeden anderen Monats“ kann durch ein relatives monatliches Muster erfüllt werden.The "first Thursday of every other month" requirement is achievable using a relative monthly pattern. Der Teil „jeden anderen Monats“ gibt an, dass das interval auf 2 festgelegt werden sollte.The "every other month" portion indicates the interval should be set to 2.
    • Da es keine Anforderung an einem Enddatum gibt, kann ein noEnd-Bereichstyp verwendet werden.Since there is no requirement on an end date, a noEnd range type can be used.

      "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.Because the value of startDate is after the first Thursday in August, the first occurrence of this series will be in September.