Спецификация коннекторов и API платформы Yva.ai

Верхнеуровневое описание архитектуры Системы и требования к инфраструктуре

Система состоит из двух логических элементов:

Платформа, анализирующая данные (далее — Платформа). Устанавливается в закрытом периметре Компании, без доступа к сети Интернет.
EWS-коннектор — программное обеспечение, используемое в качестве промежуточного звена между почтовым сервером MS Exchange и Платформой. Функциональные возможности EWS-Коннектора сводятся к получению данных по EWS-протоколу (443/TCP) с почтового сервера MS Exchange и транзиту их по защищенному протоколу HTTPS в платформу. Коннектор устанавливается на сервер под управлением Windows и представляет собой службу MS Windows.

Принципиальная схема сетевого взаимодействия.

Для автоматизации загрузки пользователей в платформу может использоваться AD-коннектор.

AD-коннектор

AD-коннектор подключается к серверу Active Directory по протоколу LDAP, получает список пользователей AD и загружает его в платформу через HTTPS / 443 через Public Yva Api.

Поля, получаемые из AD:

objectGUID
givenName
sn
displayName
mail
title
department
manager

Поиск пользователей осуществляется следующим образом:

(&(samAccountType=805306368)(mail=*))

EWS-коннектор

EWS-коннектор подключается к серверу MS Exchange по протоколу EWS и отправляет сообщения из почтовых ящиков на сервере Api (3), через соединение 2-3 (HTTPS / 443).

Коннектор Microsoft Exchange Yva.ai не выполняет изменение данных в Microsoft Exchange. Это гарантируется тем фактом, что коннектор использует только методы чтения данных в Exchange Web Services Managed API, и запросы выполняются от имени пользователя с ограниченными правами

Поля, получаемые с сервера MS Exchange:

subject
body
Headers:
Реальный отправитель письма(Sender)
Email отправителя письма(From)
Email-ы получателей письма
Email-ы вторичных получателей письма (CC)
Email-ы скрытых получателей письма(BCC)
Признак письма, отправленного пользователем (IsSent)
Время отправки
Время получения
IsFlagged, IsAutomatic и Importance (признаки есть не во всех конфигурациях серверов, получаем у кого это возможно)

Коннектор EWS для получения писем использует стандартную библиотеку от Microsoft в следующем виде:

/// <summary>
/// Unique message id.
/// This property can be null if there is no suitable in external system.
/// </summary>
public string Id { get; set; }
/// <summary>
/// Date the message was sent.
/// </summary>
public DateTime SentAt { get; set; }
/// <summary>
/// Date the message was received.
/// </summary>
public DateTime? ReceivedAt { get; set; }
/// <summary>
/// The from address for this e-mail message.
/// </summary>
public MailAddress From { get; set; }
/// <summary>
/// Collection that contains the recipients of this e-mail message.
/// This property can be null or empty collection.
/// </summary>
public List<MailAddress> To { get; set; }
/// <summary>
/// Collection that contains the carbon copy (CC) recipients for this e-mail message.
/// This property can be null or empty collection.
/// </summary>
public List<MailAddress> Cc { get; set; }
/// <summary>
/// Collection that contains the blind carbon copy (BCC) recipients for this e-mail message.
/// This property can be null or empty collection.
/// </summary>
public List<MailAddress> Bcc { get; set; }
/// <summary>
/// The priority of this e-mail message.
/// This property can be null.
/// </summary>
public MailImportance? Importance { get; set; }
/// <summary>
/// Thread id.
/// This property can be null or empty string.
/// </summary>
public string ThreadId { get; set; }
/// <summary>
/// The subject line for this e-mail message.
/// This property can be null or empty string.
/// </summary>
public string Subject { get; set; }
/// <summary>
/// The body of the message. It can be in HTML or text format.
/// </summary>
public MailBody Body { get; set; }
/// <summary>
/// Message headers.
/// This property can be null or empty collection.
/// </summary>
public List<MailHeader> Headers { get; set; }
/// <summary>
/// Is this message flagged, starred, marked, etc?
/// This property should be set only if external source has exact information.
/// </summary>
public bool? IsFlagged { get; set; }
/// <summary>
/// Is this message was sent by the owner or received?
/// </summary>
public bool IsSent { get; set; }
/// <summary>
/// Is Automatic mail?
/// </summary>
public bool? IsAutomatic { get; set; }

Возможности ограничения EWS-коннектора со стороны инфраструктуры:

Ограничение возможностей сервисной учетной записи, с правами которой EWS-коннектор подключается к Exchange-серверу средствами администрирования Throttlingpolicy https://docs.microsoft.com/en-us/powershell/module/exchange/server-health-and-performance/new-throttlingpolicy?view=exchange-ps
Снижение приоритета получения доступа к данных сервисной учетной записи, с привилегиями которой EWS-коннектор подключается к Exchange серверу

EWS-коннектор спроектирован таким образом, что работает в асинхронном режиме, получая данные порциями по 10 сообщений за одно обращение и делая паузу между обращениями на передачу данных в платформу. Пауза зависит от объемов полученных объектов и составляет от 3 до 15 секунд.
Коннектор корректно обрабатывает исключения почтового сервера, предписывающие временно приостановить отправку запросов.
Коннектор оперирует белым списком пользователей, запрашивая данные только о почтовых ящиках, указанных в нем.

Есть возможность управления уровнем логгирования приложения, изменяя значение переменной nlog.rules.logger[writeTo=file] в файле nlog.config.

Возможные значения: Trace, Debug, Info, Warn, Error и Fatal.

Файлы конфигурации коннекторов

ConnectorService.exe.config

Общие настройки коннектора:

	Поле	Описание
1	SyncRepeatPeriodInMin	Интервал через который коннектор будет начинать работу.
2	IgnoreTrustForSSL	Не проверять SSL-сертификат ADFS\Exchange сервера.
3	ConnectAdfs	Признак необходимости подключения ADFS (пользователи). Требует заполнения конфигурации подключения к ADFS (см. ниже).
4	ConnectExchange	Признак необходимости подключения Exchange (письма). Требует заполнения конфигурации подключения к Exchange (см. ниже).
5	SendToYva	Признак необходимости отправки результатов работы коннектора в Yva. Требует заполнения конфигурации подключения к Yva (см. ниже).
6	DataPath	Путь в директорию в которую будут записаны результаты работы коннектора. Используется при SendToYva = false.

Поля, использующиеся при указании значения True параметра ConnectAdfs

	Поле	Описание
1	AdfsLdapUrl	URL вида LDAP://dc.domain.com
2	AdfsUserLogin	Логин (еmail) пользователя, от имени которого коннектор будет работать с ADFS.
3	AdfsUserPassword	Пароль пользователя, от имени которого коннектор будет работать с ADFS.
4	AdfsItemsPerPage	Количество сообщений, получаемых за один запрос к серверу

Поля, использующиеся при `ConnectExchange = true`.

	Поле	Описание
1	ExchangeUrl	Exchange Web Services (EWS) URL. ("https://dc.domain.com/EWS/Exchange.asmx")
2	ExchangeVersion	Поддерживаемые версии: Exchange2010, Exchange2010_SP1, Exchange2013. Exchange2013 по умолчанию. Для Exchange 2016 выбирать Exchange 2013 (API не менялся)
3	ExchangeUserLogin	Логин (еmail) пользователя, от имени которого коннектор будет работать с EWS Managed API.
4	ExchangeUserPassword	Пароль пользователя, от имени которого коннектор будет работать с EWS Managed API.
5	ExchangeUserDomain	Домен пользователя, от имени которого коннектор будет работать с EWS Managed API.
6	ExchangeEmailsPerCall	Количество сообщений, получаемых за один запрос к серверу
7	ExchangeFoldersPerCall	Количество папок, получаемых за один запрос к серверу
8	ExchangeWhiteList	Путь к файлу со списком почтовых ящиков разрешенных для сканирования.
9	ExchangeBlackList	Путь к файлу со списком почтовых ящиков запрещенных для сканирования
10	ExchangeMaxDegreeOfParallelism	Максимальное количество параллельных потоков (не может быть больше количества ядер)
11	ExchangeLogExtendedStatisticsOnly	Ведение расширенной статистики по каждому ящику (используется для диагностики проблем получения писем из ящиков)

Поля, использующиеся при настройке `SendToYva = true`.

	Поле	Описание
1	UsersEndpointUrl	Endpoint URL API Платформы Yva для загрузки пользователей.
2	MailsEndpointUrl	Endpoint URL API Платформы Yva для загрузки писем.
3	AuthToken	JWT-токен доступа к API Платформы Yva.
4	MaxRequestSizeInMb	Максимальный размер запроса к API Yva

Файлы whitelist.json \ blacklist.json

Пути к файлам указываются в полях `ExchangeWhiteList` и `ExchangeBlackList`.

Пример содержимого файла:

["test@test.com", "test1@test.com"]

Описание API для передачи данных в платформу

Почта (Mails)

Добавляет письма/сообщения в Yva. Передаётся POST-запросом.

В теле запроса передается описание письм/сообщений:

{
"ownerIdentity": {
"type": "string",
"value": "string"
},
"mailMessages": [
{
"id": "string",
"sentAt": "2018-12-08T05:50:49.360Z",
"receivedAt": "2018-12-08T05:50:49.360Z",
"from": {
"displayName": "string",
"address": "string"
},
"to": [
{
"displayName": "string",
"address": "string"
}
],
"cc": [
{
"displayName": "string",
"address": "string"
}
],
"bcc": [
{
"displayName": "string",
"address": "string"
}
],
"importance": "low",
"threadId": "string",
"subject": "string",
"body": {
"contentType": "text","content": "string"
},
"headers": [
{
"name": "string",
"value": "string"
}
],
"isFlagged": true,
"isSent": true,
"isAutomatic": true
}
]
}

Пользователи (Users)

Добавляет пользователей в Платформу. Передаётся POST-запросом.

В теле запроса передается описание пользователей:

{
"users": [
{
"id": "string",
"loginEmail": "string",
"identities": [
{
"type": "string",
"value": "string"
}
],
"firstName": "string",
"lastName": "string",
"displayName": "string",
"jobTitle": "string",
"department": "string",
"timeZoneOffset": "string"
}
]
}