user: findMeetingTimes
Пространство имен: microsoft.graph
Предложение времени проведения собрания и местоположения с учетом доступности организатора и участников, а также ограничений по местоположению или времени, указанных в качестве параметров.
Если метод findMeetingTimes не может вернуть предложение, то в свойстве emptySuggestionsReason будет указана причина. Это значение поможет вам лучше настраивать параметры и снова вызывать метод findMeetingTimes.
Алгоритм, используемый для предложения времени проведения собраний и местоположений, периодически подвергается точной настройке. В таких сценариях, как среды тестирования, где входные параметры и данные календаря остаются неизменными, можно ожидать, что со временем предлагаемые результаты могут отличаться.
Этот API доступен в следующих национальных облачных развертываниях.
Глобальная служба | Правительство США L4 | Правительство США L5 (DOD) | Китай управляется 21Vianet |
---|---|---|---|
✅ | ✅ | ✅ | ❌ |
Разрешения
Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более привилегированное разрешение или разрешения только в том случае, если это требуется приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в разделе Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.
Тип разрешения | Разрешения с наименьшими привилегиями | Более высокие привилегированные разрешения |
---|---|---|
Делегированные (рабочая или учебная учетная запись) | Calendars.Read.Shared | Calendars.ReadWrite.Shared |
Делегированные (личная учетная запись Майкрософт) | Не поддерживается. | Не поддерживается. |
Для приложений | Не поддерживается. | Не поддерживается. |
HTTP-запрос
POST /me/findMeetingTimes
POST /users/{id|userPrincipalName}/findMeetingTimes
Заголовки запросов
Имя | Значение |
---|---|
Авторизация | Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации. |
Prefer: outlook.timezone | Строка, представляющая определенный часовой пояс для ответа, например "Тихоокеанское время США (зима)". Необязательный параметр. 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 | Минимальная достоверность, необходимая, чтобы вернуть период времени в ответе. Это процентное значение от 0 до 100. Необязательный параметр. |
returnSuggestionReasons | Edm.Boolean | Укажите True , чтобы вернуть причину для каждого предложения собрания в свойстве suggestionReason . По умолчанию задано значение false , и это свойство не возвращается. Необязательный параметр. |
timeConstraint | timeConstraint | Любые ограничения времени для собрания, которые могут включать характер собрания (свойство activityDomain ) и возможные периоды времени собрания (свойство timeSlots ).
FindMeetingTimes предполагает , что activityDomainwork не указан этот параметр. Необязательный параметр. |
В таблице ниже описываются ограничения activityDomain, которые можно в дальнейшем указать в параметре timeConstraint.
Значение activityDomain | Предложения по времени проведения собраний |
---|---|
work | Предложения находятся в пределах рабочего времени пользователя, определенного в конфигурации календаря пользователя и могут быть настроены пользователем или администратором. Рабочие часы по умолчанию : с понедельника по пятницу с 8:00 до 5 вечера в часовом поясе, заданном для почтового ящика. Это значение по умолчанию, если параметр activityDomain не указан. |
personal | Предложения находятся в рабочее время пользователя, а также в субботу и воскресенье. Значение по умолчанию — с понедельника по воскресенье с 8:00 до 17:00 в параметре часового пояса для почтового ящика. |
unrestricted | Предложения могут относиться к любому времени в любой день недели. |
unknown | Не используйте это значение, так как в будущем оно будет не рекомендуется. В настоящее время ведет себя так же, как work . Измените любой существующий код, чтобы использовать work или personal unrestricted соответствующим образом. |
В зависимости от указанных параметров, действие findMeetingTimes проверяет сведения о доступности в основных календарях организатора и участников. Действие вычисляет наиболее подходящее время собрания и возвращает предложения.
Отклик
В случае успеха этот метод возвращает код ответа 200 OK
и объект meetingTimeSuggestionsResult в тексте ответа.
Объект meetingTimeSuggestionsResult включает коллекцию предложений и свойство emptySuggestionsReason. Каждое предложение определяется как объект meetingTimeSuggestion, где средняя вероятность присутствия участников составляет 50 % или определенное процентное значение, указанное в параметре minimumAttendeePercentage.
По умолчанию каждое предлагаемое время проведения собрания указывается в формате UTC.
Если метод findMeetingTimes не может вернуть предложение, то в свойстве emptySuggestionsReason будет указана причина. Это значение поможет вам лучше настраивать параметры и снова вызывать метод findMeetingTimes.
Достоверность предложения
Свойство confidence объекта meetingTimeSuggestion принимает значения от 0 % до 100 % и представляет вероятность того, что все участники посетят собрание. Она зависит от сведений о доступности каждого участника:
- Если тот или иной участник доступен в указанный период времени, для него задается вероятность посещения 100 %, если его состояние неизвестно — 49 %, а если он занят— 0 %.
- Достоверность предлагаемого времени собрания вычисляется как средняя вероятность присутствия всех указанных участников собрания.
- С помощью необязательного параметра minimumAttendeePercentage метода findMeetingTimes вы можете сделать так, чтобы возвращались предложения со значением достоверности не ниже указанного. Например, вы можете задать для параметра minimumAttendeePercentage значение 80 %, если вас интересуют только те предложения, для которых вероятность присутствия всех участников составляет не менее 80 %. Если параметр minimumAttendeePercentage не указан, метод findMeetingTimes предполагает значение 50 %.
- При наличии нескольких предложений времени действие findMeetingTimes сначала сортирует их по убыванию значения достоверности. При наличии нескольких предложений с одинаковой достоверностью это действие сортирует их в хронологическом порядке.
Допустим, время проведения собрания предложено с учетом 3 участников со следующими сведениями о доступности:
Участник | Сведения о доступности | Процентная вероятность посещения |
---|---|---|
Дарья | Свободна | 100 % |
Иван | Неизвестно | 49 % |
Samantha | Занята | 0 % |
В этом случае достоверность предлагаемого времени проведения собрания (средняя вероятность посещения) составляет (100 % + 49 % + 0 %)/3 = 49,66 %.
Если указать минимальное значениеAttendeePercentage в 80 % в операции findMeetingTimes , так как 49,66 % < 80 %, операция не будет предлагать этот раз в ответе.
Пример
В приведенном ниже примере показано, как найти время для встречи в заранее установленном месте и запросить причину для каждого предложения, указав следующие параметры в тексте запроса:
- attendees
- locationConstraint
- timeConstraint
- isOrganizerOptional
- meetingDuration
- returnSuggestionReasons
- minimumAttendeePercentage
Указав параметр returnSuggestionReasons, вы также получите в свойстве suggestionReason объяснение для каждого предложения, если метод findMeetingTimes возвращает какие-либо предложения.
Обратите внимание, что в запросе указывается Тихоокеанское время. В ответе по умолчанию возвращаются предложения времени проведения собрания в формате UTC. С помощью заголовка запроса Prefer: outlook.timezone
вы можете сделать так, чтобы в ответе тоже возвращалось Тихоокеанское время.
Запрос
Ниже представлен пример запроса.
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": "[email protected]"
}
}
],
"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": "[email protected]"
}
}
}
],
"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": "[email protected]"
}
}
}
],
"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": "[email protected]"
}
}
}
],
"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": "[email protected]"
}
}
}
],
"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": "[email protected]"
}
}
}
],
"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"
}
}
}
]
}