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


Получить график занятости пользователей и ресурсов календаря Outlook

Общим сценарием на рабочем месте или в учебном заведении является просмотр доступности пользователя для собрания или доступности команды, помещения или оборудования в некоторый период времени.

Действие getSchedule позволяет получить сведения о доступности одной или нескольких сущностей (пользователей, списков рассылки или ресурсов) для определенного периода времени.

Пример

Простой пример — поиск расписания доступности сотрудника Игоря в определенный день с 9:00 до 18:00 по тихоокеанскому времени:

POST https://graph.microsoft.com/v1.0/me/calendar/getschedule
Prefer: outlook.timezone="Pacific Standard Time"
Content-Type: application/json

{
    "Schedules": ["AlexW@contoso.com"],
    "StartTime": {
        "dateTime": "2018-08-06T09:00:00",
        "timeZone": "Pacific Standard Time"
    },
    "EndTime": {
        "dateTime": "2018-08-06T18:00:00",
        "timeZone": "Pacific Standard Time"
    },
    "availabilityViewInterval": "15"
}

getSchedule возвращает два элемента расписания, соответствующие имеющимся событиям в стандартном календаре Алексея, с указанием времени начала и окончания каждого события и сведений о доступности. Можно считать, что в остальное время Алексей свободен в этом диапазоне дат и времени.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.scheduleInformation)",
    "value":[
        {
            "scheduleId":"AlexW@contoso.com",
            "availabilityView":"111111002222222200000000000000000000",
            "scheduleItems":[
                {
                    "status":"Tentative",
                    "start":{
                        "dateTime":"2018-08-06T09:00:00.0000000",
                        "timeZone":"Pacific Standard Time"
                    },
                    "end":{
                        "dateTime":"2018-08-06T10:30:00.0000000",
                        "timeZone":"Pacific Standard Time"
                    }
                },
                {
                    "status":"Busy",
                    "start":{
                        "dateTime":"2018-08-06T11:00:00.0000000",
                        "timeZone":"Pacific Standard Time"
                    },
                    "end":{
                        "dateTime":"2018-08-06T13:00:00.0000000",
                        "timeZone":"Pacific Standard Time"
                    }
                }
            ],
            "workingHours":{
                "daysOfWeek":[
                    "monday",
                    "tuesday",
                    "wednesday",
                    "thursday",
                    "friday"
                ],
                "startTime":"08:00:00.0000000",
                "endTime":"17:00:00.0000000",
                "timeZone":{
                    "@odata.type":"#microsoft.graph.customTimeZone",
                    "bias":480,
                    "name":"Customized Time Zone",
                    "standardOffset":{
                        "time":"02:00:00.0000000",
                        "dayOccurrence":1,
                        "dayOfWeek":"sunday",
                        "month":11,
                        "year":0
                    },
                    "daylightOffset":{
                        "daylightBias":-60,
                        "time":"02:00:00.0000000",
                        "dayOccurrence":2,
                        "dayOfWeek":"sunday",
                        "month":3,
                        "year":0
                    }
                }
            }
        }
    ]
}

Кроме расписания доступности и рабочего времени Алексея, getSchedule также возвращает свойство availabilityView, являющееся объединенным представлением доступности Алексея в этот день. Объединенное представление — это строка, состоящая из интервалов времени, охватывающих этот день, в каждом из которых указывается доступность Алексея с использованием следующего стандарта:

  • 0= свободен
  • 1= под вопросом
  • 2= занят
  • 3= не на месте
  • 4= работает в другом месте.

По умолчанию длина каждого интервала времени составляет 30 минут. В этом примере используется свойство availabilityViewInterval для изменения интервала времени до 15 минут.

Сравнение getSchedule с findMeetingTimes

Действие findMeetingTimes похоже на getSchedule тем, что оба они считывают сведения о доступности и рабочем времени указанных пользователей и ресурсов. Эти два действиями отличаются по нескольким основным моментам.

Приложение

В действии findMeetingTimes применяется определенная бизнес-логика, чтобы предложить время и место собрания, например:

  • необязательное или обязательное посещение каждой сущности;
  • тип запрошенного действия для времени суток;
  • необходимое минимальное присутствие для кворума на собрании.

Оно подходит для сценариев, зависящих от оптимизации планирования встреч.

Действие getSchedule просто возвращает сведения о доступности с учетом существующих событий в каждом из запрошенных календарей для указанного промежутка времени, и предполагается, что остальное время в этом промежутке является свободным. После этого вы можете применить бизнес-логику, чтобы использовать эти данные для завершения сценария.

Поддержка только для приложений

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

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

Разрешения

Разрешения с минимальным уровнем привилегий, необходимые для действия findmeetingtimes, — Calendars.Read.Shared.

Разрешение с минимальным уровнем привилегий, необходимое для действия getSchedule, — Calendars.Read.

Поддержка версии

Действия findmeetingtimes и getSchedule общедоступны и подходят для применения в рабочих приложениях.

Возвращаемые данные события

Разрешение с минимальным уровнем привилегий, необходимое действию getSchedule для получения приложением сведений о доступности, — Calendars.Read. В зависимости от сценария приложения согласие может даваться вошедшим в систему пользователем или администратором.

Если полученное разрешение позволяет приложению использовать действие getSchedule в календарях запрошенных пользователей через Outlook, запрошенный пользователь выбирает, какие данные события (при наличии) возвращает это действие getSchedule.

Например, getSchedule может возвращать сведения о доступности и рабочем времени запрошенных пользователей или может просто вернуть свойства subject, location и isPrivate события, если:

  • Событие помечено низким уровнем конфиденциальности (normal или personal) И применяется одно или несколько следующих условий:

    • параметры запрошенного календаря пользователя разрешают вошедшим пользователям просматривать строки тем и расположения;
    • к запрошенному календарю предоставлен общий доступ вошедшему в систему пользователю;

Эти условия применяются независимо от того, является ли пользователь, вошедший в систему, администратором в организации. Запрошенный пользователь управляет возвращаемыми данными события.

Представление часового пояса

По умолчанию время начала и окончания возвращаемых элементов расписания отображается в формате UTC. Вы можете использовать заголовок Prefer, чтобы указать соответствующий часовой пояс для приложения. Например:

Prefer: outlook.timezone="Pacific Standard Time"

Ограничения и состояния ошибок

Необходимо учитывать следующие ограничения и состояние ошибки:

  • getSchedule может поддерживать поиск сведений о доступности для 20 сущностей одновременно. Это ограничение относится к количеству пользователей, определенных по отдельности или в качестве участников списка рассылки, а также к количеству ресурсов.
  • Период времени для поиска должен быть меньше 62 дней.
  • Если действие getSchedule не может определить указанного пользователя или ресурс, оно возвращает один элемент расписания и сообщает об ошибке.