user: findMeetingTimes

  • 项目

命名空间：microsoft.graph

根据组织者和与会者的空闲状况以及指定为参数的时间或位置，推荐会议时间和位置。

如果 findMeetingTimes 无法返回任何会议时间建议，响应会在 emptySuggestionsReason 属性中指明原因。 根据此值，可以更好地调整参数，并重新调用 findMeetingTimes。

用于推荐会议时间和位置的算法将时不时地进行优化。 在输入参数和日历数据保持静止的测试环境等场景中，所推荐的结果可能随着时间的变化而有所不同。

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ✅ ✅ ❌

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时，才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息，请参阅权限类型。 要了解有关这些权限的详细信息，请参阅 权限参考。

权限类型 最低特权权限 更高特权权限
委派（工作或学校帐户） Calendars.Read.Shared Calendars.ReadWrite.Shared
委派（个人 Microsoft 帐户） 不支持。 不支持。
应用程序 不支持。 不支持。

HTTP 请求

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

请求标头

名称 值
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。
Prefer: outlook.timezone 表示响应的具体时区的字符串，例如，“Pacific Standard Time”。 可选。 如果未指定此标头，则使用 UTC。

请求正文

下面列出了支持的所有参数。 根据你自己的方案，在请求正文中为各个必需参数指定 JSON 对象。

参数 类型 说明
attendees attendeeBase 集合 一组会议与会者或资源。 由于 findMeetingTimes 假定始终需要属于人员的任何与会者，required因此请在相应的类型属性中指定人员和资源resource。 若集合为空，findMeetingTimes 只会查找组织者的空闲时间段。 可选。
isOrganizerOptional Edm.Boolean 指定 True 组织者是否不必参加。 默认值为 false。 可选。
locationConstraint locationConstraint 组织者对会议地点的要求，如是否必须返回会议地点建议，或是否只能在特定地点举行会议。 可选。
maxCandidates Edm.Int32 要返回的会议时间建议数量上限。 可选。
meetingDuration Edm.Duration 会议时长，以 ISO8601 格式表示。 例如，1 小时表示为“PT1H”，其中“P”是持续时间指示符，“T”是时间指示符，“H”是小时指示符。 使用 M 指示持续时间的分钟数;例如，2 小时 30 分钟是“PT2H30M”。 如果未指定会议持续时间，findMeetingTimes 使用默认值 30 分钟。 可选。
minimumAttendeePercentage Edm.Double 在响应中返回时间段所需的最低 confidence。 这是一个介于 0 到 100 之间的百分比值。 可选。
returnSuggestionReasons Edm.Boolean 指定 True 以在 suggestionReason 属性中返回每个会议建议的原因。 默认为 false，即不返回此属性。 可选。
timeConstraint timeConstraint 会议的任何时间限制，可能包括会议的性质 (activityDomain 属性) 和可能的会议时间段 (timeSlots 属性) 。 findMeetingTimes 假定 activityDomain ，就像未指定此参数一样 work 。 可选。

下表介绍了可在 timeConstraint 参数中进一步指定的 activityDomain 约束。

activityDomain 值 会议时间建议
工时 建议在用户的日历配置中定义的用户工作时间内，可由用户或管理员自定义。 默认工作时间为星期一到星期五，上午 8 点到下午 5 点，时区为邮箱设置。 如果未指定 activityDomain ，则为默认值。
personal 建议在用户的工作时间以及星期六和星期日内提供。 默认值为星期一到星期日，上午 8 点到下午 5 点，在邮箱的时区设置中。
unrestricted 建议可以是全年任意一天的任意时间段。
unknown 请勿使用此值，因为将来将弃用此值。 当前的行为与 相同 work。 根据需要更改任何现有代码以使用 work或 unrestrictedpersonal 。

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

响应

如果成功，此方法在响应正文中返回 200 OK 响应代码和 meetingTimeSuggestionsResult。

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

默认情况下，返回的每条会议时间建议的时区均为 UTC。

如果 findMeetingTimes 无法返回任何会议时间建议，响应会在 emptySuggestionsReason 属性中指明原因。 根据此值，可以更好地调整参数，并重新调用 findMeetingTimes。

会议时间建议的置信度

meetingTimeSuggestion 的 confidence 属性值介于 0% 到 100% 之间，表示所有与会者出席会议的可能性（以每个人的忙/闲状态为依据）：

  • 对于每个与会者，在指定的会议时间段内，空闲、未知和忙碌状态对应的与会者出席可能性分别为 100%、49% 和 0%。
  • 会议时间建议的置信度是通过计算相应会议的所有指定与会者的出席可能性平均值而得出。
  • 可以使用 findMeetingTimes 的可选参数 minimumAttendeePercentage，指定仅返回置信度不低于特定值的会议时间建议。 例如，如果只想返回所有与会者的出席可能性不低于 80% 的会议时间建议，可以将 minimumAttendeePercentage 指定为 80%。 如果未指定 minimumAttendeePercentage，findMeetingTimes 假定值为 50%。
  • 如果有多条会议时间建议，findMeetingTimes 操作首先会按计算得出的置信度值由高到低对建议进行排序。 如果会议时间建议的置信度相同，此操作会按时间顺序对建议进行排序。

例如，如果会议时间建议涉及 3 位与会者，他们的忙/闲状态如下：

与会者 忙/闲状态 出席可能性 (%)
Dana 空闲 100%
John 未知 49%
Samantha 忙碌 0%

会议时间建议的置信度为与会者出席可能性的平均值，即 (100% + 49% + 0%)/3 = 49.66%。

如果在 findMeetingTimes 操作中将 minimumAttendeePercentage 指定为 80%，因为 49.66% < 为 80%，该操作不会在响应中建议这次。

示例

以下示例展示了如何查找预定地点会议的时间，并请求获得各条建议的理由，具体是通过在请求正文中指定以下参数：

  • attendees
  • locationConstraint
  • timeConstraint
  • isOrganizerOptional
  • meetingDuration
  • returnSuggestionReasons
  • minimumAttendeePercentage

设置 returnSuggestionReasons 参数后，suggestionReason 属性中还会返回各条建议的理由（如果 findMeetingTimes 返回建议的话）。

请注意，该请求按 PST 时区指定时间。 默认情况下，答复将按 UTC 的形式返回会议时间建议。 还可使用 Prefer: outlook.timezone 请求头指定将 PST 用于答复中的时间值。

请求

下面展示了示例请求。

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
}
响应

下面展示了示例响应。 注意：为了提高可读性，可能缩短了此处显示的响应对象。

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"
                }
            }
        }
    ]
}