1. База знаний Yva.ai
  2. Безопасность и соблюдение стандартов

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

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

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

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

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

Для автоматизации загрузки пользователей в платформу может использоваться 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"
}
]
}