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