user: findMeetingTimes

Mit dieser Methode können Sie Vorschläge für Besprechungstermine abrufen. Die Vorschläge basieren auf der Verfügbarkeit des Organisators und der Teilnehmer sowie auf als Parameter spezifizierten Zeit- oder Ortseinschränkungen.

Wenn findMeetingTimes keine Besprechungsvorschläge zurückgeben kann, enthält die Antwort einen Grund, angegeben in der Eigenschaft emptySuggestionsReason. Ausgehend von diesem Wert können Sie die Parameter optimieren und findMeetingTimes erneut aufrufen.

Voraussetzungen

Einer der folgenden Bereiche ist erforderlich, um diese API auszuführen: Calendars.Read.Shared oder Calendars.ReadWrite.Shared.

HTTP-Anforderung

POST /me/findMeetingTimes
POST /users/{id|userPrincipalName}/findMeetingTimes

Anforderungsheader

Name Wert
Authorization Bearer . Required.
Prefer: outlook.timezone Eine Zeichenfolge, die eine bestimmte Zeitzone für die Antwort darstellt, beispielsweise „Pacific Standard Time“. Optional. Wenn dieser Header nicht angegeben ist, wird UTC verwendet.

Anforderungstext

In der Tabelle unten sind alle unterstützten Parameter aufgeführt. Geben Sie abhängig von Ihrem jeweiligen Szenario für jeden notwendigen Parameter im Anforderungstext ein JSON-Objekt an.

Parameter Typ Beschreibung
attendees attendeeBase collection Eine Sammlung von Teilnehmern oder Ressourcen für die Besprechung. Da findMeetingTimes davon ausgeht, dass jeder Teilnehmer, bei dem es sich um eine Person handelt, immer erforderlich ist, geben Sie required für eine Person und resource für eine Ressource in der entsprechenden type-Eigenschaft an. Ist diese Sammlung leer, sucht findMeetingTimes nur für den Organisator nach freien Zeitfenstern. Optional.
isOrganizerOptional Edm.Boolean Geben Sie True an, wenn der Organisator nicht zwingend teilnehmen muss. Der Standardwert lautet false. Optional.
locationConstraint locationConstraint Die Anforderungen des Organisators bezüglich des Besprechungsorts, z. B. ob ein Vorschlag für einen Besprechungsort erforderlich ist oder nur bestimmte Besprechungsorte zulässig sind. Optional.
maxCandidates Edm.Int32 Die maximale Anzahl an zurückgegebenen Besprechungsterminvorschlägen. Optional.
meetingDuration Edm.Duration Die Dauer der Besprechung im Format ISO8601. 1 Stunde wird beispielsweise als „PT1H“ angegeben. Dabei ist „P“ der Bezeichner für die Dauer, „T“ der Bezeichner für die Zeit und „H“ der Bezeichner für die Zeiteinheit Stunde. Wenn keine Besprechungsdauer angegeben wird, verwendet findMeetingTimes den Standardwert von 30 Minuten. Optional.
minimumAttendeePercentage Edm.Double Die mindestens erforderliche Konfidenz, damit ein bestimmtes Zeitfenster in der Antwort zurückgegeben wird. Hierbei handelt es sich um einen Prozentwert zwischen 0 und 100. Optional.
returnSuggestionReasons Edm.Boolean Geben Sie True an, wenn für jeden Besprechungsvorschlag ein Grund in der Eigenschaft suggestionReason zurückgegeben werden soll. Der Standardwert ist false, damit diese Eigenschaft nicht zurückgegeben wird. Optional.
timeConstraint timeConstraint Alle Zeiteinschränkungen für eine Besprechung, z. B. die Art der Besprechung (Eigenschaft activityDomain) und mögliche Besprechungszeiträume (Eigenschaft timeSlots). findMeetingTimes geht davon aus, dass activityDomain auf work festgelegt ist, wenn Sie diesen Parameter nicht angeben. Optional.

In der folgenden Tabelle werden die Einschränkungen beschrieben, die Sie im Parameter timeConstraint genauer angeben können.

activityDomain-Wert in timeConstraint Vorschläge für Besprechungstermine
work Vorschläge liegen innerhalb der Arbeitszeit des Benutzers, die in der Kalenderkonfiguration des Benutzers definiert wird, und können vom Benutzer oder Administrator angepasst werden. Die Standardarbeitszeit ist Montag bis Freitag von 08:00 Uhr bis 17:00 Uhr in der Zeitzone, die für das Postfach festgelegt ist. Dies ist der Standardwert, wenn keine activityDomain angegeben ist.
personal Vorschläge liegen innerhalb der Arbeitszeit des Benutzers sowie am Samstag und Sonntag. Der Standardwert ist Montag bis Sonntag von 08:00 Uhr bis 17:00 Uhr in der Zeitzone, die für das Postfach festgelegt ist.
unrestricted Vorschläge können für jede Zeit des Tages an jedem Tag der Woche gemacht werden.
unknown Verwenden Sie diesen Wert nicht, da er in Zukunft veraltet sein wird. Aktuell verhält er sich genauso wie work. Ändern Sie vorhandenen Code so, dass er work, personal bzw. unrestricted verwendet.

Ausgehend von den angegebenen Parametern überprüft findMeetingTimes den Frei-/Gebucht-Status im Hauptkalender des Organisators und in den Hauptkalendern der Teilnehmer. Die Aktion berechnet die bestmöglichen Besprechungstermine und gibt Besprechungsvorschläge zurück.

Antwort

Bei erfolgreicher Ausführung gibt die Methode den Antwortcode 200, OK und eine Ressource des Typs meetingTimeSuggestionsResult im Antworttext zurück.

Eine Ressource des Typs meetingTimeSuggestionsResult enthält eine Sammlung von Besprechungsvorschlägen und eine Eigenschaft emptySuggestionsReason. Jeder Vorschlag ist als eine Ressource des Typs meetingTimeSuggestion definiert, für die die durchschnittliche Teilnahmekonfidenz der Teilnehmer bei 50 % oder einem spezifischen Prozentwert liegt, den Sie im Parameter minimumAttendeePercentage festgelegt haben.

Standardmäßig wird jeder Besprechungsterminvorschlag in UTC zurückgegeben.

Wenn findMeetingTimes keine Besprechungsvorschläge zurückgeben kann, enthält die Antwort einen Grund, angegeben in der Eigenschaft emptySuggestionsReason. Ausgehend von diesem Wert können Sie die Parameter optimieren und findMeetingTimes erneut aufrufen.

Die Konfidenz von Besprechungsvorschlägen

Die Eigenschaft confidence einer Ressource des Typs meetingTimeSuggestion liegt in einem Bereich von 0 % bis 100 %. Sie gibt an, wie wahrscheinlich es ist, dass alle Teilnehmer an der Besprechung teilnehmen können, und basiert auf den Frei-/Gebucht-Status der einzelnen Teilnehmer:

  • Für jeden Teilnehmer gilt: Ist der Status für eine Besprechung „Frei“, liegt die Teilnahmewahrscheinlichkeit bei 100 %. Beim Status „Unbekannt“ liegt sie bei 49 %, beim Status „Gebucht“ bei 0 %.
  • Zur Berechnung der Konfidenz eines Besprechungsterminvorschlags wird der Mittelwert aus den individuellen Teilnahmewahrscheinlichkeiten aller Besprechungsteilnehmer für die betreffende Besprechung gebildet.
  • Mithilfe des optionalen Parameters minimumAttendeePercentage für findMeetingTimes können Sie festlegen, dass nur Besprechungsterminvorschläge mit einem bestimmten Mindestkonfidenzwert zurückgegeben werden. Beispielsweise können Sie eine minimumAttendeePercentage von 80 % festlegen, wenn Sie nur Vorschläge erhalten möchten, bei denen die Wahrscheinlichkeit, dass alle Teilnehmer teilnehmen können, bei mindestens 80 % liegt. Wenn Sie keine minimumAttendeePercentage festlegen, setzt findMeetingTimes einen Wert von 50 % an.
  • Gibt es mehrere Besprechungsterminvorschläge, ordnet die Aktion findMeetingTimes die Vorschläge zunächst nach ihrem berechneten Konfidenzwert, beginnend mit dem Vorschlag mit dem höchsten Wert. Haben mehrere Vorschläge jeweils denselben Konfidenzwert, ordnet die Aktion diese Vorschläge chronologisch.

Hier ein Beispiel für einen Besprechungsterminvorschlag für drei Teilnehmer mit folgendem Frei-/Gebucht-Status:

Teilnehmer Frei-/Gebucht-Status Teilnahmewahrscheinlichkeit in %
Dana Frei 100 %
John Unbekannt 49 %
Fanny Gebucht 0 %

Die Konfidenz des Besprechungsterminvorschlags (durchschnittliche Teilnahmewahrscheinlichkeit) liegt hier bei (100 % + 49 % + 0 %) ÷ 3 = 49,66 %.

Wenn Sie eine minimumAttendeePercentage von 80 % in einer Operation des Typs findMeetingTimes festlegen, wird die Operation diesen Termin nicht in der Antwort vorschlagen, da 49,66 % < 80 % ist.

Beispiel

Das folgende Beispiel veranschaulicht, wie Sie einen Besprechungstermin für einen vorab festgelegten Ort finden und für jeden Vorschlag einen Grund anfragen. Dazu geben Sie im Anforderungstext folgende Parameter an:

  • attendees
  • locationConstraint
  • timeConstraint
  • meetingDuration
  • returnSuggestionReasons
  • minimumAttendeePercentage

Durch Setzen des Parameters returnSuggestionReasons wird für jeden Vorschlag auch eine Erklärung in der Eigenschaft suggestionReason vermerkt, sofern findMeetingTimes Vorschläge zurückgibt.

Beachten Sie: In der Anforderung gilt für die Zeit die Zeitzone PST. Die Antwort gibt Besprechungsterminvorschläge jedoch standardmäßig in UTC zurück. Sie können den Anforderungsheader Prefer: outlook.timezone verwenden, um auch für die Zeitwerte in der Antwort die Zeitzone PST festzulegen.

Anforderung

Hier sehen Sie die Beispielanforderung:

POST https://graph.microsoft.com/v1.0/me/findMeetingTimes
Prefer: outlook.timezone="Pacific Standard Time"
Content-Type: application/json

{ 
  "attendees": [ 
    { 
      "type": "required",  
      "emailAddress": { 
        "name": "Fanny Downs",
        "address": "fannyd@contoso.onmicrosoft.com" 
      } 
    }
  ],  
  "locationConstraint": { 
    "isRequired": "false",  
    "suggestLocation": "false",  
    "locations": [ 
      { 
        "resolveAvailability": "false",
        "displayName": "Conf room Hood" 
      } 
    ] 
  },  
  "timeConstraint": {
    "activityDomain":"unrestricted", 
    "timeslots": [ 
      { 
        "start": { 
          "dateTime": "2017-04-17T09:00:00",  
          "timeZone": "Pacific Standard Time" 
        },  
        "end": { 
          "dateTime": "2017-04-19T17:00:00",  
          "timeZone": "Pacific Standard Time" 
        } 
      } 
    ] 
  },  
  "meetingDuration": "PT2H",
  "returnSuggestionReasons": "true",
  "minimumAttendeePercentage": "100"
}
Antwort

Unten sehen Sie eine Beispielantwort. Hinweis: Das hier gezeigte Antwortobjekt ist möglicherweise aus Platzgründen abgeschnitten. Von einem tatsächlichen Aufruf werden alle Eigenschaften zurückgegeben.

HTTP/1.1 200 OK
Content-type: application/json
Preference-Applied: outlook.timezone="Pacific Standard Time"
Content-Length: 976

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.meetingTimeSuggestionsResult",
    "emptySuggestionsReason":"",
    "meetingTimeSuggestions":[
        {
            "confidence":100.0,
            "organizerAvailability":"free",
            "suggestionReason":"Suggested because it is one of the nearest times when all attendees are available.",
            "meetingTimeSlot":{
                "start":{
                    "dateTime":"2017-04-17T18:00:00.0000000",
                    "timeZone":"Pacific Standard Time"
                },
                "end":{
                    "dateTime":"2017-04-17T20:00:00.0000000",
                    "timeZone":"Pacific Standard Time"
                }
            },
            "attendeeAvailability":[
                {
                    "availability":"free",
                    "attendee":{
                        "type":"required",
                        "emailAddress":{
                            "address":"fannyd@contoso.onmicrosoft.com"
                        }
                    }
                }
            ],
            "locations":[
                {
                    "displayName":"Conf room Hood"
                }
            ]
        },
        {
            "confidence":100.0,
            "organizerAvailability":"free",
            "suggestionReason":"Suggested because it is one of the nearest times when all attendees are available.",
            "meetingTimeSlot":{
                "start":{
                    "dateTime":"2017-04-17T20:00:00.0000000",
                    "timeZone":"Pacific Standard Time"
                },
                "end":{
                    "dateTime":"2017-04-17T22:00:00.0000000",
                    "timeZone":"Pacific Standard Time"
                }
            },
            "attendeeAvailability":[
                {
                    "availability":"free",
                    "attendee":{
                        "type":"required",
                        "emailAddress":{
                            "address":"fannyd@contoso.onmicrosoft.com"
                        }
                    }
                }
            ],
            "locations":[
                {
                    "displayName":"Conf room Hood"
                }
            ]
        }
   ]
}