Обзор интеграции с Exchange¶
Документ описывает Exchange как платформенный интеграционный контур: компоненты, точки настройки, обмен данными и границы между calendar, mail, system, integrations. Для инцидентов по конкретному пользователю — Exchange — диагностика синхронизации пользователя. Внутри: зоны ответственности, API управления и рабочие вызовы, конфигурация EWS, сквозная синхронизация календаря, служебные таблицы, фоновые задания, риски и порядок обращения в поддержку.
Границы ответственности и точки входа API¶
Exchange-контур разбит на зоны ответственности между доменами:
| Зона | Что покрывает |
|---|---|
calendar |
бизнес-операции по событиям, режимы синхронизации пользователя, обработка ошибок EWS |
mail |
почтовые ящики Exchange (EWS/IMAP провайдеры), синхронизация папок/писем |
system / integrations |
сервисные учётные данные, флаги и политики интеграции |
platform/backend |
SignalR, инфраструктура заданий, очереди |
Ключевой принцип: Exchange не является единым монолитным модулем; это набор связанных подсистем.
Admin API (управление и диагностика)
| Метод | Маршрут | Назначение |
|---|---|---|
| GET | /api/admin/exchange/subscriptions |
Список активных подписок Exchange |
| GET | /api/admin/users/{userId:int}/service/settings |
Текущие сервисные/Exchange-настройки пользователя |
| POST | /api/admin/users/{userId:int}/exchange/reset-fails |
Сброс счётчика неудачных попыток синхронизации |
| POST | /api/admin/users/{userId:int}/exchange/update-sync-mode |
Смена режима Exchange для пользователя |
API календаря (рабочие вызовы)
| Метод | Маршрут | Назначение |
|---|---|---|
| POST | /api/calendar/events |
Получение событий (агрегированный листинг) |
| POST | /api/calendar/create |
Создание события |
| POST | /api/calendar/update |
Обновление события |
| POST | /api/calendar/delete |
Удаление события |
| POST | /api/calendar/messages/unread/count |
Счётчик непрочитанных календарных сообщений |
Конфигурация Exchange¶
1. Сервис ExchangeWebService
Главная форма настройки: ews-service-settings (dbo.EwsServiceSettings).
Критичные параметры:
- Url, Login, Password, Domain;
- UseImpersonalization;
- UseSIDForImpersonalization;
- параметры видимости чужих календарей/занятости.
2. Общие настройки приложения
Используются для глобальных политик синхронизации: - режимы синхронизации с Exchange; - лимиты повторов; - флаги Exchange-подписок/поведения при ошибках.
3. Пользовательские сервисные настройки
Уровень пользователя определяет, будет ли синхронизация идти и в каком режиме:
- Disabled;
- Sync;
- Direct.
Синхронизация календаря, таблицы и фоновые задания¶
Сквозная цепочка синхронизации календаря:
- Пользователь/процесс меняет событие календаря (1Ф или Exchange).
CalendarManagerи Exchange-провайдер выполняют операцию синхронизации.- При ошибках EWS срабатывает обработка исключений и увеличивается счётчик ошибок.
- Если превышен лимит, режим пользователя может быть отключён.
- Интерфейс получает состояние опросом (pull) (
calendar/*,service/settings) и сигналами передачи.
| Объект | Назначение |
|---|---|
EwsServiceSettings |
Конфигурация подключения к Exchange |
EwsFolders |
Кэш папок Exchange по пользователям |
EwsFolderPermissions |
Кэш прав доступа к папкам/календарям |
UsersMessageCountCache |
Кэш счётчиков сообщений/состояний |
UserInfoExtValues (Sync.Exchange.*) |
Служебные флаги/состояния пользователя |
ExchangeSyncLog, ExchangeExportEvents |
Технические логи и экспортные события Exchange-контура |
Ключевые задания:
- EnableDoSyncWithExchangeJob — повторное включение синхронизации для пользователей, отключённых из-за Exchange-ошибок;
- LazyUpdatableCachesUpdateJob — обновление отложенных кэшей (включая Exchange-права/папки);
- связанные почтовые задания (EmailJobSyncFolders, EmailJobReceive) для mail-контура.
Типовые архитектурные риски¶
Частые архитектурные риски Exchange-контура и где их искать:
| Риск | Где проявляется | Что проверять первым |
|---|---|---|
| Ошибки прав/имперсонализации | calendar + service settings | UseImpersonalization, SID/email, права сервисного аккаунта |
| Локальный счётчик ошибок у пользователя | user service settings | syncWithExchangeFailedAttempts vs лимит повторов |
| Деградация подписок | admin exchange subscriptions | /api/admin/exchange/subscriptions, состояние подключения |
| Подписки не запускаются совсем, логов нет | Settings.DefaultEwsServiceId = NULL + нет AD-профилей, привязанных к EWS |
SELECT DefaultEwsServiceId FROM Settings; см. Провайдер Exchange (EWS), раздел «Как определяется список EWS-сервисов» |
| Рассинхрон кэша папок/прав | calendar/mail | EwsFolders, EwsFolderPermissions, задание обновления кэшей |
Разная конфигурация между system и user-уровнем |
system + user profile | фактический ewsMode, глобальные ключи и сервисные параметры |
Когда обращаться в поддержку 1Ф и связанные документы¶
Обращаться в поддержку 1Ф (серверная часть) нужно, если: 1. API управления режимом/сбросом fail не меняет фактическое состояние пользователя. 2. Подписки Exchange стабильно не активируются после проверки учётных данных/URL. 3. Наблюдается массовая деградация (не один пользователь), особенно вместе с ошибками сети/инфраструктуры.
Проверить настройки администрирования нужно, если: 1. неверно настроены сервисные параметры Exchange; 2. права impersonation/delegate не соответствуют выбранному режиму; 3. применены конфликтующие ключи общих настроек.
Связанные документы: