在 Outlook 日历上找到可能的会议时间
在工作场所或学校,寻找开会的公共时间和场所经常会产生开销。 Microsoft Graph 应用程序可以使用 findMeetingTimes 来识别满足时间、地点和其他约束的任何可能的会议时间。
通过 findMeetingTimes 操作,可以指定会议日期/时间范围、持续时间、可选或必需的与会者,以及活动性质 (activityDomain) 。 该操作考虑到与会者和组织者的正常工作计划和忙/闲状态,并建议适合参与者和活动类型的时间。 例如,与工作相关的活动建议始终出现在组织者和与会者的工作时间,而建议的所需与会者可用,则建议在建议列表中较高位置排序。
在 Microsoft 365 中,每个邮箱可配置工作时间和时区。 findMeetingTimes 操作处理组织者和与会者之间的时区变化。 默认情况下, findMeetingTimes 以 UTC 返回建议。 可以使用以下请求标头让 findMeetingTimes 返回在特定时区表示的建议。
Prefer: outlook.timezone="{time-zone-string}}"
这对于大型会议特别有用,你可以为仲裁指定一个百分比 (minimumAttendeePercentage),并且让 findMeetingTimes 仅在满足最低与会者可用性时返回建议。
如果 findMeetingTimes 无法建议任何会议时间,它将指示一个特定原因 (emptySuggestionsReason) ,例如组织者或所需的与会者不可用。 根据此值,可以更好地调整参数,并重新调用 findMeetingTimes。
备注
findMeetingTimes 操作当前可用于Microsoft 365工作或学校邮箱,但不适用于个人 outlook.com 邮箱。
以下示例演示如何使用 findMeetingTimes 返回 2 个用户可能见面的几个小时的时间,同时考虑到用户的忙/闲和工作日程,以及与会者在部分时间之外。 由于此会议只有 2 个用户,因此建议需要 100% 的出席率。 下面显示了用户的忙/闲计划。
该示例调用 findMeetingTimes 两次:
- 第一次调用位于 4 月 18 日至 20 日的日期范围内。 由于与会者在 4 月 18 日至 19 日外出,并且 4 月 20 日没有常见可用时间,因此第一次调用不会返回任何建议,原因 (空SuggestionsReason) 与会者不可用。
- 第二次调用查找 4 月 21 日的可用性并返回下午 2-4 点的建议。
对 findMeetingTimes 的两个调用包括以下参数。 findMeetingTimes 的所有参数都是可选的。
-
与会者:一位与会者 Samantha Booth 的类型属性设置为
required
- locationConstraint:不需要任何位置建议
- timeConstraint:第一次调用查找日期/时间范围 4 月 18 日上午 9 点到 4 月 20 日下午 5 点;如果第一次调用未能建议任何时间,第二次调用查找范围 4 月 21 日上午 9 点到下午 5 点
- meetingDuration:两个小时
- returnSuggestionReasons:本示例要求为每个建议提供一个原因
- minimumAttendeePercentage:100%,因为与会者必须能够在任何建议的时间出席
为两个用户查找 4 月 18 到 20 日之间 2 小时的空闲时间空挡。
POST https://graph.microsoft.com/v1.0/me/findMeetingTimes
Prefer: outlook.timezone="Pacific Standard Time"
Content-type: application/json
{
"attendees": [
{
"type": "required",
"emailAddress": {
"name": "Samantha Booth",
"address": "samanthab@contoso.com"
}
}
],
"locationConstraint": {
"isRequired": false,
"suggestLocation": false,
"locations": [
{
"resolveAvailability": false,
"displayName": "Conf room Hood"
}
]
},
"timeConstraint": {
"activityDomain":"work",
"timeslots": [
{
"start": {
"dateTime": "2017-04-18T09:00:00",
"timeZone": "Pacific Standard Time"
},
"end": {
"dateTime": "2017-04-20T17:00:00",
"timeZone": "Pacific Standard Time"
}
}
]
},
"meetingDuration": "PT2H",
"returnSuggestionReasons": true,
"minimumAttendeePercentage": 100
}
当这两个用户均有空时,4 月 18 到 20 日工作时间内没有 2 小时的时间空挡。
HTTP/1.1 200 OK
Content-type: application/json
Preference-Applied: outlook.timezone="Pacific Standard Time"
Content-Length: 184
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.meetingTimeSuggestionsResult",
"emptySuggestionsReason":"AttendeesUnavailable",
"meetingTimeSuggestions":[
]
}
在 4 月 21 日寻找 2 小时的时间空挡。
POST https://graph.microsoft.com/v1.0/me/findMeetingTimes
Prefer: outlook.timezone="Pacific Standard Time"
Content-type: application/json
{
"attendees": [
{
"type": "required",
"emailAddress": {
"name": "Samantha Booth",
"address": "samanthab@contoso.com"
}
}
],
"locationConstraint": {
"isRequired": false,
"suggestLocation": false,
"locations": [
{
"resolveAvailability": false,
"displayName": "Conf room Hood"
}
]
},
"timeConstraint": {
"activityDomain":"work",
"timeslots": [
{
"start": {
"dateTime": "2017-04-21T09:00:00",
"timeZone": "Pacific Standard Time"
},
"end": {
"dateTime": "2017-04-21T17:00:00",
"timeZone": "Pacific Standard Time"
}
}
]
},
"meetingDuration": "PT2H",
"returnSuggestionReasons": true,
"minimumAttendeePercentage": 100
}
第二个 findMeetingTimes 请求建议两个用户在 4 月 21 日下午 2-4 点开会。
HTTP/1.1 200 OK
Content-type: application/json
Preference-Applied: outlook.timezone="Pacific Standard Time"
Content-Length: 714
{
"@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-21T14:00:00.0000000",
"timeZone":"Pacific Standard Time"
},
"end":{
"dateTime":"2017-04-21T16:00:00.0000000",
"timeZone":"Pacific Standard Time"
}
},
"attendeeAvailability":[
{
"availability":"free",
"attendee":{
"type":"required",
"emailAddress":{
"address":"samanthab@contoso.com"
}
}
}
],
"locations":[
{
"displayName":"Conf room Hood"
}
]
}
]
}
有时并非所有与会者都可以参加会议。 可以通过指定 minimumAttendeePercentage 可选参数,让 findMeetingTimes 在出席置信度达到特定百分比时建议一个时间。 详细了解会议建议和其他参数的置信度,并根据需要将其应用于较大规模的会议。
获取会议时间建议后,可能需要:
- 创建事件并将其作为会议请求发送。
- 在事件中添加附件。
了解更多关于与 Outlook 日历集成的信息。