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


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или personalunrestricted соответствующим образом.

В зависимости от указанных параметров, действие 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": "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"
                }
            }
        }
    ]
}