在 Outlook 日历上找到可能的会议时间

项目
03/21/2024

在工作场所或学校，寻找开会的公共时间和场所经常会产生开销。 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% 的出席率。下面显示了用户的忙/闲计划。

组织者的日历

4 月 17-21 日的组织者工作日历显示忙/闲时间

与会者的日历

4 月 17 日至 21 日与会者的工作日历显示忙/闲时间

该示例调用 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 日历集成的信息。