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

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

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

1. Платформа, анализирующая данные (далее — Платформа). Устанавливается в закрытом периметре Компании, без доступа к сети Интернет.

2. 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

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

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

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

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

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

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

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

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

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

• Почта (Mails)

Добавляет письма/сообщения в Yva.ai. Передаётся 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"
}
]
}