Поделиться через

user: findMeetingTimes

  • Статья

Пространство имен: microsoft.graph

Важно!

API версии /beta в Microsoft Graph могут быть изменены. Использование этих API в производственных приложениях не поддерживается. Чтобы определить, доступен ли API в версии 1.0, используйте селектор версий.

Предложение времени проведения собрания и местоположения с учетом доступности организатора и участников, а также ограничений по местоположению или времени, указанных в качестве параметров.

Если метод 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 Коллекция участников или ресурсов для собрания. В свойстве соответствующего типа укажите required или optional для пользователя и resource для ресурса, например комнаты для собраний. Если значение не указано, findMeetingTimes предполагает required для свойства type . Если указана пустая коллекция, действие findMeetingTimes ищет свободные периоды времени для организатора. Необязательный параметр.
isOrganizerOptional Edm.Boolean Укажите True , не обязательно ли организатору присутствовать. Значение по умолчанию: false. Необязательный параметр.
locationConstraint locationConstraint Требования организатора к месту проведения собрания (например, требуется ли предложение или собрание может пройти только в определенных местах). Необязательный параметр.
maxCandidates Edm.Int32 Максимальное количество возвращаемых предложений времени проведения собрания. Необязательный параметр.
meetingDuration Edm.Duration Длина собрания, обозначенная в формате ISO 8601 . Например, 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 не указан этот параметр. Необязательный параметр.

В таблице ниже описываются ограничения, которые можно в дальнейшем указать в параметре timeConstraint.

Значение activityDomain в параметре timeConstraint Предложения по времени проведения собраний
work Предложения находятся в пределах рабочего времени пользователя, определенного в конфигурации календаря пользователя и могут быть настроены пользователем или администратором. Рабочие часы по умолчанию : с понедельника по пятницу с 8:00 до 5 вечера в часовом поясе, заданном для почтового ящика. Это значение по умолчанию, если параметр activityDomain не указан.
personal Предложения находятся в рабочее время пользователя, а также в субботу и воскресенье. Значение по умолчанию — с понедельника по воскресенье с 8:00 до 17:00 в параметре часового пояса для почтового ящика.
unrestricted Предложения могут относиться к любому времени в любой день недели.
unknown Не используйте это значение, так как в будущем оно будет не рекомендуется. В настоящее время ведет себя так же, как work. Измените любой существующий код, чтобы использовать workили personalunrestricted соответствующим образом.

В зависимости от указанных параметров, действие findMeetingTimes проверяет сведения о доступности в основных календарях организатора и участников. Действие вычисляет наиболее подходящее время собрания и возвращает предложения.

Отклик

В случае успеха этот метод возвращает код ответа 200 OK и объект meetingTimeSuggestionsResult в тексте ответа.

Объект meetingTimeSuggestionsResult включает коллекцию предложений и свойство emptySuggestionsReason. Каждое предложение определяется как объект meetingTimeSuggestion, где средняя вероятность присутствия участников составляет 50 % или определенное процентное значение, указанное в параметре minimumAttendeePercentage.

По умолчанию каждое предлагаемое время проведения собрания указывается в формате UTC.

Если метод findMeetingTimes не может вернуть предложение, то в свойстве emptySuggestionsReason будет указана причина. Это значение поможет вам лучше настраивать параметры и снова вызывать метод findMeetingTimes.

Достоверность предложения

Свойство confidence объекта meetingTimeSuggestion принимает значения от 0 % до 100 % и представляет вероятность того, что все участники посетят собрание. Она зависит от сведений о доступности каждого участника:

  • Если тот или иной участник доступен в указанный период времени, для него задается вероятность посещения 100 %, если его состояние неизвестно — 49 %, а если он занят— 0 %.
  • Достоверность предлагаемого времени собрания вычисляется как средняя вероятность присутствия всех указанных участников собрания.
  • При наличии нескольких предложений времени действие findMeetingTimes сначала сортирует их по убыванию значения достоверности. При наличии нескольких предложений с одинаковой достоверностью это действие сортирует их в хронологическом порядке.
  • С помощью необязательного параметра minimumAttendeePercentage метода findMeetingTimes вы можете сделать так, чтобы возвращались предложения со значением достоверности не ниже указанного. Например, вы можете задать для параметра minimumAttendeePercentage значение 80 %, если вас интересуют только те предложения, для которых вероятность присутствия всех участников составляет не менее 80 %. Если параметр minimumAttendeePercentage не указан, метод findMeetingTimes предполагает значение 50 %.

Допустим, время проведения собрания предложено с учетом 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/beta/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/beta/$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"
                }
            }
        }
    ]
}