user: findMeetingTimesuser: findMeetingTimes

Wichtig

APIs unter der /beta Version in Microsoft Graph können Änderungen unterworfen werden.APIs under the /beta version in Microsoft Graph are subject to change. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt.Use of these APIs in production applications is not supported.

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.Suggest meeting times and locations based on organizer and attendee availability, and time or location constraints specified as parameters.

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.If findMeetingTimes cannot return any meeting suggestions, the response would indicate a reason in the emptySuggestionsReason property. Based on this value, you can better adjust the parameters and call findMeetingTimes again.

Der zum Vorschlagen von Besprechungszeiten und -orten verwendete Algorithmus wird von Zeit zu Zeit optimiert.The algorithm used to suggest meeting times and locations undergoes fine-tuning from time to time. In Szenarien wie Testumgebungen, in denen Eingabeparameter und Kalenderdaten statisch sind, können sich die vorgeschlagenen Ergebnisse mit der Zeit ändern.In scenarios like test environments where the input parameters and calendar data remain static, expect that the suggested results may differ over time.

BerechtigungenPermissions

Eine der nachfolgenden Berechtigungen ist erforderlich, um diese API aufrufen zu können. Weitere Informationen, unter anderem zur Auswahl von Berechtigungen, finden Sie im Artikel zum Thema Berechtigungen.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

BerechtigungstypPermission type Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)Permissions (from least to most privileged)
Delegiert (Geschäfts-, Schul- oder Unikonto)Delegated (work or school account) Calendars.Read.Shared, Calendars.ReadWrite.SharedCalendars.Read.Shared, Calendars.ReadWrite.Shared
Delegiert (persönliches Microsoft-Konto)Delegated (personal Microsoft account) Nicht unterstütztNot supported.
AnwendungApplication Nicht unterstütztNot supported.

HTTP-AnforderungHTTP request

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

AnforderungsheaderRequest headers

NameName WertValue
AuthorizationAuthorization Bearer {token}. Erforderlich.Bearer {token}. Required.
Prefer: outlook.timezonePrefer: 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.A string representing a specific time zone for the response, for example, "Pacific Standard Time". Optional. UTC is used if this header is not specified.

AnforderungstextRequest body

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.All the supported parameters are listed below. Depending on your scenario, specify a JSON object for each of the necessary parameters in the request body.

ParameterParameter TypType BeschreibungDescription
attendeesattendees attendeeBase collectionattendeeBase collection Eine Sammlung von Teilnehmern oder Ressourcen für die Besprechung.A collection of attendees or resources for the meeting. Geben Sie required in der entsprechenden Type -Eigenschaft optional oder für eine Person resource und für eine Ressource wie Besprechungsraum an.In the corresponding type property, specify required or optional for a person and resource for a resource like meeting room. Wenn dieser Parameter nicht angegeben wird required , wird findMeetingTimes für die Type -Eigenschaft angenommen.If not specified, findMeetingTimes assumes required for the type property. Ist diese Sammlung leer, sucht findMeetingTimes nur für den Organisator nach freien Zeitfenstern.An empty collection causes findMeetingTimes to look for free time slots for only the organizer. Optional.Optional.
isOrganizerOptionalisOrganizerOptional Edm.BooleanEdm.Boolean Geben Sie True an, wenn der Organisator nicht zwingend teilnehmen muss. Der Standardwert lautet false. Optional.Specify True if the organizer doesn't necessarily have to attend. The default is false. Optional.
locationConstraintlocationConstraint locationConstraintlocationConstraint 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.The organizer's requirements about the meeting location, such as whether a suggestion for a meeting location is required, or there are specific locations only where the meeting can take place. Optional.
maxCandidatesmaxCandidates Edm.Int32Edm.Int32 Die maximale Anzahl an zurückgegebenen Besprechungsterminvorschlägen. Optional.The maximum number of meeting time suggestions to be returned. Optional.
meetingDurationmeetingDuration Edm.DurationEdm.Duration Die im ISO 8601 -Format bezeichnete Besprechungsdauer.The length of the meeting, denoted in ISO 8601 format. Beispielsweise wird 1 Stunde als "PT1H" bezeichnet, wobei "P" der Bezeichner für die Dauer ist, "t" ist der Zeit Kennzeichner, und "H" ist der Stunden Bezeichner.For example, 1 hour is denoted as 'PT1H', where 'P' is the duration designator, 'T' is the time designator, and 'H' is the hour designator. Verwenden Sie M, um Minuten für die Dauer anzugeben. beispielsweise wären 2 Stunden und 30 Minuten "PT2H30M".Use M to indicate minutes for the duration; for example, 2 hours and 30 minutes would be 'PT2H30M'. Wenn keine Besprechungsdauer angegeben ist, verwendet findMeetingTimes die Standardeinstellung von 30 Minuten.If no meeting duration is specified, findMeetingTimes uses the default of 30 minutes. Optional.Optional.
minimumAttendeePercentageminimumAttendeePercentage Edm.DoubleEdm.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.The minimum required confidence for a time slot to be returned in the response. It is a % value ranging from 0 to 100. Optional.
returnSuggestionReasonsreturnSuggestionReasons Edm.BooleanEdm.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.Specify True to return a reason for each meeting suggestion in the suggestionReason property. The default is false to not return that property. Optional.
timeConstrainttimeConstraint timeConstrainttimeConstraint 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.Any time restrictions for a meeting, which can include the nature of the meeting (activityDomain property) and possible meeting time periods (timeSlots property). findMeetingTimes assumes activityDomain as work if you don't specify this parameter. Optional.

In der folgenden Tabelle werden die Einschränkungen beschrieben, die Sie im Parameter timeConstraint genauer angeben können.The following table describes the restrictions you can further specify in the timeConstraint parameter.

activityDomain-Wert in timeConstraintactivityDomain value in timeConstraint Vorschläge für BesprechungstermineSuggestions for meeting times
workwork 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.Suggestions are within the user's work hours which are defined in the user’s calendar configuration and can be customized by the user or administrator. The default work hours are Monday to Friday, 8am to 5pm in the time zone set for the mailbox. This is the default value if no activityDomain is specified.
personalpersonal 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.Suggestions are within the user's work hours, and Saturday and Sunday. The default is Monday to Sunday, 8am to 5pm, in the time zone setting for the mailbox.
unrestrictedunrestricted Vorschläge können für jede Zeit des Tages an jedem Tag der Woche gemacht werden.Suggestions can be from all hours of a day, all days of a week.
unknownunknown 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.Do not use this value as it will be deprecated in the future. Currently behaves the same as work. Change any existing code to use work, personal or unrestricted as appropriate.

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.Based on the specified parameters,findMeetingTimes checks the free/busy status in the primary calendars of the organizer and attendees. The action calculates the best possible meeting times, and returns any meeting suggestions.

AntwortResponse

Bei erfolgreicher Ausführung gibt die Methode den Antwortcode 200 OK und eine Ressource des Typs meetingTimeSuggestionsResult im Antworttext zurück.If successful, this method returns 200 OK response code and a meetingTimeSuggestionsResult in the response body.

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.A meetingTimeSuggestionsResult includes a collection of meeting suggestions and an emptySuggestionsReason property. Each suggestion is defined as a meetingTimeSuggestion, with attendees having on the average a confidence level of 50% to attend, or a specific % that you have specified in the minimumAttendeePercentage parameter.

Standardmäßig wird jeder Besprechungsterminvorschlag in UTC zurückgegeben.By default, each meeting time suggestion is returned in UTC.

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.If findMeetingTimes cannot return any meeting suggestions, the response would indicate a reason in the emptySuggestionsReason property. Based on this value, you can better adjust the parameters and call findMeetingTimes again.

Die Konfidenz von BesprechungsvorschlägenThe confidence of a meeting suggestion

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:The confidence property of a meetingTimeSuggestion ranges from 0% to 100%, and represents the chance that all the attendees attend the meeting, based on each of their individual free/busy status:

  • 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 %.For each attendee, a free status for a specified meeting time period corresponds to 100% chance of attendance, unknown status 49%, and busy status 0%.
  • Zur Berechnung der Konfidenz eines Besprechungsterminvorschlags wird der Mittelwert aus den individuellen Teilnahmewahrscheinlichkeiten aller Besprechungsteilnehmer für die betreffende Besprechung gebildet.The confidence of a meeting time suggestion is computed by averaging the chance of attendance over all the attendees specified for that meeting.
  • 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.If there are multiple meeting time suggestions, the findMeetingTimes action first orders the suggestions by their computed confidence value from high to low. If there are suggestions with the same confidence, the action then orders these suggestions chronologically.
  • 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.You can use the minimumAttendeePercentage optional parameter for findMeetingTimes to specify only meeting time suggestions of at least certain confidence level should be returned. For example, you can specify a minimumAttendeePercentage of 80% if you want only suggestions that have an 80% chance or more that all the attendees are attending. If you do not specify minimumAttendeePercentage, findMeetingTimes assumes a value of 50%.

Hier ein Beispiel für einen Besprechungsterminvorschlag für drei Teilnehmer mit folgendem Frei-/Gebucht-Status:As an example, if a meeting time suggestion involves 3 attendees with the following free/busy status:

TeilnehmerAttendee Frei-/Gebucht-StatusFree/busy status Teilnahmewahrscheinlichkeit in %% Chance of attendance
DanaDana FreiFree 100 %100%
JohnJohn UnbekanntUnknown 49 %49%
SamanthaSamantha GebuchtBusy 0 %0%

Die Konfidenz des Besprechungsterminvorschlags (durchschnittliche Teilnahmewahrscheinlichkeit) liegt hier bei (100 % + 49 % + 0 %) ÷ 3 = 49,66 %.Then the confidence of the meeting time suggestion, which is the average chance of attendance, is (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.If you specify a minimumAttendeePercentage of 80% in a findMeetingTimes operation, because 49.66% < 80%, the operation will not suggest this time in the response.

BeispielExample

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:The following example shows how to find time to meet at a pre-determined location, and request a reason for each suggestion, by specifying the following parameters in the request body:

  • attendeesattendees
  • locationConstraintlocationConstraint
  • timeConstrainttimeConstraint
  • isOrganizerOptionalisOrganizerOptional
  • meetingDurationmeetingDuration
  • returnSuggestionReasonsreturnSuggestionReasons
  • minimumAttendeePercentageminimumAttendeePercentage

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.By setting the returnSuggestionReasons parameter, you also get an explanation in the suggestionReason property for each suggestion, if findMeetingTimes returns any suggestion.

Beachten Sie, dass die Anfrage Uhrzeiten in der PST-Zeitzone angibt.Notice that the request specifies time in the PST time zone. Standardmäßig werden Vorschläge für Besprechungszeit bei der Antwort als UTC-Zeiten zurückgegeben.By default, the response returns meeting time suggestions in UTC. Sie können den Anforderungsheader Prefer: outlook.timezone verwenden, um auch für die Zeitwerte in der Antwort die Zeitzone PST festzulegen.You can use the Prefer: outlook.timezone request header to specify PST as well for the time values in the response.

AnforderungRequest

Hier sehen Sie die Beispielanforderung:Here is the example request.

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

{ 
  "attendees": [ 
    { 
      "type": "required",  
      "emailAddress": { 
        "name": "Alex Wilbur",
        "address": "alexw@contoso.onmicrosoft.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"
}
AntwortResponse

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.Here is an example response. Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$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.onmicrosoft.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.onmicrosoft.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.onmicrosoft.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.onmicrosoft.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.onmicrosoft.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"
                }
            }
        }
    ]
}