user: findMeetingTimesuser: findMeetingTimes

命名空间:microsoft.graphNamespace: microsoft.graph

根据组织者和与会者的空闲状况以及指定为参数的时间或位置,推荐会议时间和位置。Suggest meeting times and locations based on organizer and attendee availability, and time or location constraints specified as parameters.

如果 findMeetingTimes 无法返回任何会议时间建议,响应会在 emptySuggestionsReason 属性中指明原因。根据此值,可以更好地调整参数,并重新调用 findMeetingTimesIf 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.

用于推荐会议时间和位置的算法将时不时地进行优化。The algorithm used to suggest meeting times and locations undergoes fine-tuning from time to time. 在输入参数和日历数据保持静止的测试环境等场景中,所推荐的结果可能随着时间的变化而有所不同。In scenarios like test environments where the input parameters and calendar data remain static, expect that the suggested results may differ over time.

权限Permissions

要调用此 API,需要以下权限之一。要了解详细信息,包括如何选择权限的信息,请参阅权限One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

权限类型Permission type 权限(从最低特权到最高特权)Permissions (from least to most privileged)
委派(工作或学校帐户)Delegated (work or school account) Calendars.Read.Shared、Calendars.ReadWrite.SharedCalendars.Read.Shared, Calendars.ReadWrite.Shared
委派(个人 Microsoft 帐户)Delegated (personal Microsoft account) 不支持。Not supported.
应用程序Application 不支持。Not supported.

HTTP 请求HTTP request

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

请求标头Request headers

名称Name Value
AuthorizationAuthorization Bearer {token}。必需。Bearer {token}. Required.
Prefer: outlook.timezonePrefer: outlook.timezone 表示响应的具体时区的字符串,例如,“Pacific Standard Time”。可选。如果未指定此标头则使用 UTC。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.

请求正文Request body

下面列出了支持的所有参数。根据你自己的方案,在请求正文中为各个必需参数指定 JSON 对象。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.

参数Parameter 类型Type 说明Description
attendeesattendees attendeeBase 集合attendeeBase collection 一组会议与会者或资源。由于 findMeetingTimes 假设始终需要具备与会人员,因此在对应的 type 属性中将人员指定为 required 而将资源指定为 resource。如果集合为空,则 findMeetingTimes 只会查找组织者的空闲时间段。可选。A collection of attendees or resources for the meeting. Since findMeetingTimes assumes that any attendee who is a person is always required, specify required for a person and resource for a resource in the corresponding type property. An empty collection causes findMeetingTimes to look for free time slots for only the organizer. Optional.
isOrganizerOptionalisOrganizerOptional Edm.BooleanEdm.Boolean 如果组织者不必必须参加,则指定 True。默认值为 false。可选。Specify True if the organizer doesn't necessarily have to attend. The default is false. Optional.
locationConstraintlocationConstraint locationConstraintlocationConstraint 组织者对会议地点的要求,如是否必须返回会议地点建议,或是否只能在特定地点举行会议。可选。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 要返回的会议时间建议数量上限。可选。The maximum number of meeting time suggestions to be returned. Optional.
meetingDurationmeetingDuration Edm.DurationEdm.Duration 会议时长,以 ISO8601 格式表示。例如,1 小时表示为“PT1H”,其中“P”是持续时间指示符,“T”是时间指示符,“H”是小时指示符。使用 M 指示时长的分钟数;例如,2 小时 30 分钟是“PT2H30M”。如果未指定会议持续时间,则 findMeetingTimes 使用默认值 30 分钟。可选。The length of the meeting, denoted in ISO8601 format. 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. Use M to indicate minutes for the duration; for example, 2 hours and 30 minutes would be 'PT2H30M'. If no meeting duration is specified, findMeetingTimes uses the default of 30 minutes. Optional.
minimumAttendeePercentageminimumAttendeePercentage Edm.DoubleEdm.Double 在响应中返回时间段所需的最低 confidence。这是一个介于 0 到 100 之间的百分比值。可选。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 指定 True 可以在 suggestionReason 属性中返回每个会议建议的理由。默认为 false,即不返回此属性。可选。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 会议的所有时间限制,可以包括会议性质(activityDomain 属性)和可能的会议时间段(timeSlots 属性)。如果未指定此参数,则 findMeetingTimesactivityDomain 假定为 work。可选。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.

下表介绍了可在 timeConstraint 参数中进一步指定的 activityDomain 约束。The following table describes the activityDomain restrictions you can further specify in the timeConstraint parameter.

activityDomain 值activityDomain value 会议时间建议Suggestions for meeting times
工时work 建议处于用户的工作时间(在用户的日历配置中定义该时间,并且可由用户或管理员自定义)内。默认工作时间是星期一到星期五的上午八点到下午五点(使用为邮箱设置的时区)。如果未指定 activityDomain 则此为默认值。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 建议处于用户的工作时间内及星期六和星期日。默认是星期一到星期日的上午八点到下午五点(使用邮箱的时区设置)。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 建议可以是全年任意一天的任意时间段。Suggestions can be from all hours of a day, all days of a week.
unknownunknown 请勿使用此值,因为以后会弃用此值。当前其行为与 work 相同。根据需要将任何现有代码更改为使用 workpersonal、或 unrestrictedDo 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.

根据指定的参数,findMeetingTimes 会检查组织者和与会者的主日历中的忙/闲状态。此操作会计算出最可行的会议时间,并返回所有会议时间建议。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.

响应Response

如果成功,此方法在响应正文中返回 200 OK 响应代码和 meetingTimeSuggestionsResultIf successful, this method returns 200 OK response code and a meetingTimeSuggestionsResult in the response body.

meetingTimeSuggestionsResult 包含一组会议时间建议和 emptySuggestionsReason 属性。每条建议都被定义为 meetingTimeSuggestion,同时与会者出席置信度平均值为 50%,或为你在 minimumAttendeePercentage 参数中指定的特定百分比值。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.

默认情况下,返回的每条会议时间建议的时区均为 UTC。By default, each meeting time suggestion is returned in UTC.

如果 findMeetingTimes 无法返回任何会议时间建议,响应会在 emptySuggestionsReason 属性中指明原因。根据此值,可以更好地调整参数,并重新调用 findMeetingTimesIf 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.

会议时间建议的置信度The confidence of a meeting suggestion

meetingTimeSuggestionconfidence 属性值介于 0% 到 100% 之间,表示所有与会者出席会议的可能性(以每个人的忙/闲状态为依据):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:

  • 对于每个与会者,在指定的会议时间段内,空闲、未知和忙碌状态对应的与会者出席可能性分别为 100%、49% 和 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%.
  • 会议时间建议的置信度是通过计算相应会议的所有指定与会者的出席可能性平均值而得出。The confidence of a meeting time suggestion is computed by averaging the chance of attendance over all the attendees specified for that meeting.
  • 可以使用 findMeetingTimes 的可选参数 minimumAttendeePercentage,指定仅返回置信度不低于特定值的会议时间建议。例如,如果只想返回所有与会者的出席可能性不低于 80% 的会议时间建议,可以将 minimumAttendeePercentage 指定为 80%。如果未指定 minimumAttendeePercentagefindMeetingTimes 假定值为 50%。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%.
  • 如果有多条会议时间建议,findMeetingTimes 操作首先会按计算得出的置信度值由高到低对建议进行排序。如果会议时间建议的置信度相同,此操作会按时间顺序对建议进行排序。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.

例如,如果会议时间建议涉及 3 位与会者,他们的忙/闲状态如下:As an example, if a meeting time suggestion involves 3 attendees with the following free/busy status:

与会者Attendee 忙/闲状态Free/busy status 出席可能性 (%)% Chance of attendance
DanaDana 空闲Free 100%100%
JohnJohn 未知Unknown 49%49%
SamanthaSamantha 忙碌Busy 0%0%

会议时间建议的置信度为与会者出席可能性的平均值,即 (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%.

如果你在 findMeetingTimes 操作中将 minimumAttendeePercentage 指定为 80%,此操作将不会在响应中建议此时间,这是因为 49.66% < 80%。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.

示例Example

以下示例展示了如何查找预定地点会议的时间,并请求获得各条建议的理由,具体是通过在请求正文中指定以下参数: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

设置 returnSuggestionReasons 参数后,suggestionReason 属性中还会返回各条建议的理由(如果 findMeetingTimes 返回建议的话)。By setting the returnSuggestionReasons parameter, you also get an explanation in the suggestionReason property for each suggestion, if findMeetingTimes returns any suggestion.

请注意,该请求按 PST 时区指定时间。Notice that the request specifies time in the PST time zone. 默认情况下,答复将按 UTC 的形式返回会议时间建议。By default, the response returns meeting time suggestions in UTC. 还可使用 Prefer: outlook.timezone 请求头指定将 PST 用于答复中的时间值。You can use the Prefer: outlook.timezone request header to specify PST as well for the time values in the response.

请求Request

下面展示了示例请求。Here is the example request.

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.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"
}
响应Response

下面展示了示例响应。注意:为了简单起见,可能会将此处所示的响应对象截断。将从实际调用中返回所有属性。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/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.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"
                }
            }
        }
    ]
}