Teilen über


user: findMeetingTimes

Namespace: microsoft.graph

Schlagen Sie Besprechungstermine und -orte basierend auf der Verfügbarkeit des Organisators und der Teilnehmer sowie auf als Parameter spezifizierten Zeit- oder Ortseinschränkungen vor.

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.

Der zum Vorschlagen von Besprechungszeiten und -orten verwendete Algorithmus wird von Zeit zu Zeit optimiert. In Szenarien wie Testumgebungen, in denen Eingabeparameter und Kalenderdaten statisch sind, können sich die vorgeschlagenen Ergebnisse mit der Zeit ändern.

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Globaler Dienst US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet

Berechtigungen

Wählen Sie für diese API die Als am wenigsten privilegierten Berechtigungen gekennzeichneten Berechtigungen aus. Verwenden Sie nur dann eine Berechtigung mit höheren Berechtigungen , wenn dies für Ihre App erforderlich ist. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) Calendars.Read.Shared Calendars.ReadWrite.Shared
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Anwendung Nicht unterstützt Nicht unterstützt

HTTP-Anforderung

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

Anforderungsheader

Name Wert
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über die Authentifizierung und Autorisierung.
Prefer: outlook.timezone Eine Zeichenfolge, die eine bestimmte Zeitzone für die Antwort festlegt, beispielsweise „Pacific Standard Time“ Optional. UTC wird verwendet, wenn dieser Header nicht angegeben ist.

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 ein JSON-Objekt im Anforderungstext an.

Parameter Typ Beschreibung
attendees attendeeBase collection Eine Sammlung von Teilnehmern oder Ressourcen für die Besprechung. Da findMeetingTimes davon ausgeht, dass jeder Teilnehmer, der eine Person ist, immer erforderlich ist, geben Sie required für eine Person und resource für eine Ressource in der entsprechenden Typeigenschaft an. Ist diese Sammlung leer, sucht findMeetingTimes nur für den Organisator nach freien Zeitfenstern. Optional.
isOrganizerOptional Edm.Boolean Geben Sie an True , ob der Organisator nicht unbedingt 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 Länge der Besprechung, die im Format ISO8601 angegeben ist. Beispielsweise wird 1 Stunde als "PT1H" bezeichnet, wobei "P" der Dauer-Bezeichner, "T" der Zeit-Bezeichner und "H" der Stunden-Bezeichner ist. Verwenden Sie M, um Minuten für die Dauer anzugeben. Beispielsweise wären 2 Stunden und 30 Minuten "PT2H30M". Wenn keine Besprechungsdauer angegeben ist, 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, um einen Grund für jeden Besprechungsvorschlag in der eigenschaft suggestionReason zurückzugeben. Der Standardwert ist false, damit diese Eigenschaft nicht zurückgegeben wird. Optional.
timeConstraint timeConstraint Alle Zeiteinschränkungen für eine Besprechung, die die Art der Besprechung (activityDomain-Eigenschaft ) und mögliche Besprechungszeiträume (timeSlots-Eigenschaft ) umfassen können. findMeetingTimes geht von activityDomain aus, als work ob Sie diesen Parameter nicht angeben. Optional.

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

activityDomain-Wert Vorschläge für Besprechungstermine
work Vorschläge liegen innerhalb der Arbeitszeiten des Benutzers, die in der Kalenderkonfiguration des Benutzers definiert sind und vom Benutzer oder Administrator angepasst werden können. Die Standardarbeitszeiten sind Montag bis Freitag, 8:00 bis 17:00 Uhr in der für das Postfach festgelegten Zeitzone. Dies ist der Standardwert, wenn keine activityDomain angegeben ist.
personal Vorschläge liegen innerhalb der Arbeitszeiten des Benutzers sowie samstags und sonntags. Der Standardwert ist Montag bis Sonntag, 8 bis 17 Uhr, in der Zeitzoneneinstellung für das Postfach.
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 ist. Verhält sich derzeit genauso wie work. Ändern Sie den vorhandenen Code so, dass workoder personalunrestricted verwendet wird.

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 %
Samantha Gebucht 0 %

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

Wenn Sie eine minimumAttendeePercentage von 80 % in einem findMeetingTimes-Vorgang angeben, da 49,66 % < 80 %, schlägt der Vorgang dieses Mal in der Antwort nicht vor.

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
  • isOrganizerOptional
  • 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, dass die Anfrage Uhrzeiten in der PST-Zeitzone angibt. Standardmäßig werden Vorschläge für Besprechungszeit bei der Antwort als UTC-Zeiten zurückgegeben. 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": "Alex Wilbur",
        "address": "alexw@contoso.com"
      }
    }
  ],
  "locationConstraint": {
    "isRequired": false,
    "suggestLocation": false,
    "locations": [
      {
        "resolveAvailability": false,
        "displayName": "Conf room Hood"
      }
    ]
  },
  "timeConstraint": {
    "activityDomain":"work",
    "timeSlots": [
      {
        "start": {
          "dateTime": "2019-04-16T09:00:00",
          "timeZone": "Pacific Standard Time"
        },
        "end": {
          "dateTime": "2019-04-18T17:00:00",
          "timeZone": "Pacific Standard Time"
        }
      }
    ]
  },
  "isOrganizerOptional": "false",
  "meetingDuration": "PT1H",
  "returnSuggestionReasons": "true",
  "minimumAttendeePercentage": 100
}
Antwort

Unten sehen Sie eine Beispielantwort. Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt sein.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.meetingTimeSuggestionsResult",
    "emptySuggestionsReason": "",
    "meetingTimeSuggestions": [
        {
            "confidence": 100,
            "order": 1,
            "organizerAvailability": "free",
            "suggestionReason": "Suggested because it is one of the nearest times when all attendees are available.",
            "attendeeAvailability": [
                {
                    "availability": "free",
                    "attendee": {
                        "emailAddress": {
                            "address": "alexw@contoso.com"
                        }
                    }
                }
            ],
            "locations": [
                {
                    "displayName": "Conf room Hood"
                }
            ],
            "meetingTimeSlot": {
                "start": {
                    "dateTime": "2019-04-18T16:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                },
                "end": {
                    "dateTime": "2019-04-18T17:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                }
            }
        },
        {
            "confidence": 100,
            "order": 2,
            "organizerAvailability": "free",
            "suggestionReason": "Suggested because it is one of the nearest times when all attendees are available.",
            "attendeeAvailability": [
                {
                    "availability": "free",
                    "attendee": {
                        "emailAddress": {
                            "address": "alexw@contoso.com"
                        }
                    }
                }
            ],
            "locations": [
                {
                    "displayName": "Conf room Hood"
                }
            ],
            "meetingTimeSlot": {
                "start": {
                    "dateTime": "2019-04-18T08:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                },
                "end": {
                    "dateTime": "2019-04-18T09:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                }
            }
        },
        {
            "confidence": 100,
            "order": 3,
            "organizerAvailability": "tentative",
            "suggestionReason": "Suggested because it is one of the nearest times when all attendees are available.",
            "attendeeAvailability": [
                {
                    "availability": "free",
                    "attendee": {
                        "emailAddress": {
                            "address": "alexw@contoso.com"
                        }
                    }
                }
            ],
            "locations": [
                {
                    "displayName": "Conf room Hood"
                }
            ],
            "meetingTimeSlot": {
                "start": {
                    "dateTime": "2019-04-18T15:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                },
                "end": {
                    "dateTime": "2019-04-18T16:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                }
            }
        },
        {
            "confidence": 100,
            "order": 4,
            "organizerAvailability": "tentative",
            "suggestionReason": "Suggested because it is one of the nearest times when all attendees are available.",
            "attendeeAvailability": [
                {
                    "availability": "free",
                    "attendee": {
                        "emailAddress": {
                            "address": "alexw@contoso.com"
                        }
                    }
                }
            ],
            "locations": [
                {
                    "displayName": "Conf room Hood"
                }
            ],
            "meetingTimeSlot": {
                "start": {
                    "dateTime": "2019-04-18T09:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                },
                "end": {
                    "dateTime": "2019-04-18T10:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                }
            }
        },
        {
            "confidence": 100,
            "order": 5,
            "organizerAvailability": "tentative",
            "suggestionReason": "Suggested because it is one of the nearest times when all attendees are available.",
            "attendeeAvailability": [
                {
                    "availability": "free",
                    "attendee": {
                        "emailAddress": {
                            "address": "alexw@contoso.com"
                        }
                    }
                }
            ],
            "locations": [
                {
                    "displayName": "Conf room Hood"
                }
            ],
            "meetingTimeSlot": {
                "start": {
                    "dateTime": "2019-04-18T12:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                },
                "end": {
                    "dateTime": "2019-04-18T13:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                }
            }
        }
    ]
}