MS Exchange: Регулярное получение событий из календарей с помощью временной метки SyncState

В этом кейсе разберем, как организовать регулярное получение новых и измененных событий из календарей Microsoft Exchange с помощью временной метки SyncState. Полученные данные могут использоваться для последующего анализа, например, для оценки распределения встреч по времени и загрузки сотрудников.

Календари Microsoft Exchange часто используются как источник данных о встречах, занятости сотрудников и фактическом использовании рабочего времени. При регулярной загрузке данных без учета предыдущих запусков одни и те же события выгружаются повторно, что приводит к дублированию записей и росту объема данных. Метка SyncState позволяет получать только те события, которые были созданы, изменены или отменены после предыдущей загрузки данных, что снижает нагрузку на систему и исключает повторную обработку уже полученных событий.

Настройка получения событий из календарей Exchange с использованием SyncState выполняется в четыре этапа:

• Этап 1 — настройка подключения к MS Exchange Online
• Этап 2 — первичная загрузка событий и сохранение значения SyncState
• Этап 3 — повторный сбор событий с использованием SyncState
• Этап 4 — визуализация полученных данных

Настройка подключения к MS Exchange Online

В примере используется подключение к MS Exchange Online с аутентификацией OAuth 2.0 Client Credentials Grant.

Этот тип подключения подходит для фоновой синхронизации по расписанию и позволяет получать данные из календарей нескольких пользователей без их участия.

Регистрация приложения в Microsoft Entra ID

Для подключения к MS Exchange Online требуется предварительно зарегистрировать приложение в Microsoft Entra ID и выдать ему необходимые разрешения:

1. Откройте Центр администрирования Microsoft Entra или перейдите в Microsoft Entra ID через портал Azure, затем откройте раздел Регистрация приложений и нажмите + Новая регистрация
2. Укажите имя приложения и нажмите Зарегистрировать.
3. В настройках приложения откройте раздел Разрешения API и перейдите в + Добавить разрешение → Интерфейсы API, используемые моей организацией.
4. Выберите в списке Office 365 Exchange Online и откройте Разрешения приложения.
5. Добавьте разрешение full_access_as_app.
6. Перейдите в раздел Сертификаты и секреты и добавьте новый секрет клиента.
7. Задайте описание секрета и нажмите Добавить.

Настройка подключения в Proceset

После регистрации приложения выполните настройку подключения в системе Proceset:

1. В рабочем пространстве нажмите + Добавить и выберите Подключение.
2. В открывшемся окне выберите Microsoft Exchange (Вход через Microsoft).
3. Задайте название подключения и нажмите Создать.
4. В профиле подключения выберите способ аутентификации OAuth 2.0 Client Credentials Grant.
5. Перейдите в профиль приложения в Microsoft Entra, откройте раздел Обзор и скопируйте идентификатор приложения.
6. Вернитесь в настройки подключения в Proceset и укажите скопированный идентификатор в поле Client ID.
7. Аналогично скопируйте идентификатор каталога и значение секрета клиента и укажите их в полях Tenant GUID и Client secret соответственно. При необходимости укажите идентификатор секрета в поле Secret ID.
8. Проверьте подключение и сохраните его. Если проверка завершилась неуспешно, перепроверьте настройки.

Первичная загрузка событий и получение значения SyncState

Чтобы получить начальное значение SyncState, необходимо выполнить первичную загрузку событий по дате:

1. В рабочем пространстве нажмите + Добавить и выберите Скрипт.
2. Задайте название скрипта и нажмите Добавить.
3. Добавьте блок-триггер Ручной запуск.
4. Добавьте блок Получить календари из пакета MS Exchange и в параметрах укажите адрес электронной почты пользователя, календари которого требуется получить. Если адреса хранятся в таблице, нужную колонку можно подставить через маппинг.
5. Добавьте блок Получить события календаря.
6. В параметрах блока укажите идентификатор календаря и адрес электронной почты с помощью маппинга из предыдущего блока.
7. Выберите тип сбора событий По дате, задайте период и протестируйте блок. Для первичной загрузки рекомендуется использовать короткий диапазон, например, один день.
8. В выходных данных блока возвращается значение sync_state.
9. Добавьте в скрипт блок Добавить строки, чтобы сохранить данные календарей и значение SyncState в отдельной таблице. Создайте новую таблицу на основе выходных данных блока Получить события календаря.
10. Задайте название таблицы, проверьте типы данных колонок и нажмите Добавить.
11. Протестируйте скрипт.

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

Повторный сбор событий с использованием SyncState

На этом этапе необходимо изменить скрипт так, чтобы при каждом запуске возвращались только новые и измененные события:

1. Замените триггер Ручной запуск на Планировщик и настройте расписание.
2. Блок Получить календари оставьте без изменений.
3. Добавьте блок Фильтр и задайте условие отбора календаря. По умолчанию в MS Exchange может существовать несколько календарей с одинаковым идентификатором unique_id и разными именами. Фильтр позволяет выбрать нужный календарь и избежать дублирования данных.
4. Протестируйте блок.
5. Добавьте блок Выбрать строки через SQL-запрос, укажите запрос для получения сохраненного значения SyncState и идентификатора календаря и протестируйте блок.
6. В блоке Получить события календаря укажите идентификатор календаря и адрес электронной почты с помощью маппинга из предыдущего блока.
7. Выберите тип сбора С последней выгрузки, подставьте значение SyncState с помощью маппинга в соответствующее поле и протестируйте блок.
8. Сохраните полученные данные в отдельную таблицу с помощью блока Добавить строки.
9. С помощью блока Обновить данные обновите значение SyncState в таблице, где оно хранится. Это позволит получить последние актуальные данные при последующей синхронизации.
10. В параметрах блока в качестве колонки-ключа укажите sync_state и в колонку для обновления подставьте unique_id.
11. Протестируйте скрипт целиком и опубликуйте его.

Визуализация данных из календарей MS Exchange для дальнейшего анализа

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

1. Откройте дашборд в режиме редактирования и добавьте виджет Столбиковая диаграмма.
2. В поле Разрез 1 выберите колонку start из таблицы с данными календарей.
3. В раскрывающемся списке выберите значение Месяц.
4. В качестве меры выберите колонку start и используйте формулу count(start).

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