Веб-сервис 

Внешняя система предназначена для подключения к системе внешних веб-сервисов.

Основные настройки 

Чтобы приступить к настройке внешней системы, на вкладке Коннектор выберите тип Веб-сервисы. После выбора типа коннектора станут доступны поля для ввода характеристик внешней системы:

Внешняя система может работать по следующим протоколам передачи данных:

REST (выбран по умолчанию)
SOAP

Данные могут передаваться в следующих форматах:

JSON (выбран по умолчанию)
XML
Text

Флажок Использовать https в разделе Параметры сервиса Platform устанавливается при использовании защищенного протокола передачи данных.

Для работы внешней системы должен быть выбран способ получения или передачи сообщений в Platform и из Platform.

Внешняя система может работать в качестве веб-сервера и / или веб-клиента.

Веб-сервер 

При установке флажка Внешний сервис вызывает методы Platform и указания порта сервера, Платформа публикует собственный веб-сервис для каждого направления.

В Platform: http://server-address:port-number/sendMessage

Из Platform: http://server-address:port-number/receive

При передаче данных в формате Text используются следующие веб-сервисы:

В Platform: http://server-address:port-number/sendBody

Из Platform: http://server-address:port-number/receiveBody

Настройка аутентификации веб-сервера 

Для аутентификации в системе используются учетные данные внутренних пользователей, созданных в сервисе Управление пользователями. При этом привязка внутренних пользователей к конкретным внешним системам отсутствует, аутентификация возможна при использовании учетных данных любого внутреннего пользователя. Настройка параметров аутентификации производится в режиме редактирования конфигурации.

Важно

Для включения аутентификации в системе добавьте следующую пару ключ-значение в объект json в значении ключа config (отсутствует по умолчанию):

"auth": {
"$type": "DT.ClusterConfiguration.AuthenticationConfig, DT_Core",
"enabled": true,
"usePasswordHash": false
},

Значение ключа enabled (тип boolean) определяет, включена ли аутентификация у внешней системы.

Пример части конфигурации внешней системы с настройками для включения аутентификации в системе:

{
  "$type": "DT.ClusterConfiguration.DtSystem, DT_Core",
  "config": {
        "$type": "DT.ConfigurationRepository.Configuration.Adapter.WebSystemSimpleConfig, DT_ConfigurationRepository",
        "asServer": {
          "$type": "DT.ConfigurationRepository.Configuration.Adapter.WebServerConfig, DT_ConfigurationRepository",
          "authTypeRest": "Bearer"
        },
        "auth": {
          "$type": "DT.ClusterConfiguration.AuthenticationConfig, DT_Core",
          "enabled": true,
          "usePasswordHash": false
        }
  }
}

В поле asServer должно присутствовать поле authTypeRest , в значении которого указывается тип аутентификации:

Basic: базовый тип аутентификации.
Bearer: аутентификация с использованием токена на предъявителя Bearer (используется по умолчанию).

При значении usePasswordHash: true для аутентификации требуется передавать не сам пароль, а только хеш от него (SHA256 в шестнадцатеричном формате).

Подробное описание настроек аутентификации приведено в разделе Расширенное REST API.

Веб-клиент 

При установке флажка Platform вызывает методы Внешнего сервиса будет запущен веб-клиент, выполняющий http-запросы к сервису подключаемой системы. Параметр Базовый URL сервиса подключаемой системы является обязательным, адрес может быть в формате http://host/ или http://host:port/ (также возможно использование протокола https).

При необходимости установите значение таймаута для вызова методов в поле Таймаут вызова, если это значение не указано в обработчике.

Настройка аутентификации веб-клиента 

Для веб-клиента можно настроить работу с внешним веб-сервисом, принимающим запросы с аутентификацией.

Выберите один из следующих способов аутентификации:

Anonymous: анонимный тип аутентификации, не требующий настройки дополнительных параметров.
Basic: базовый тип аутентификации, потребуется ввести логин и пароль в соответствующих полях.
Bearer: аутентификация с использованием токена на предъявителя Bearer, потребуется указать имя пользователя и пароль для получения токена аутентификации в конфигурации системы.

Basic (базовый тип)

При использовании базового типа аутентификации, внесите в поля Логин и Пароль соответствующие данные для аутентификации во внешней системе.

Если получение аутентификационных данных ожидается из сервиса Управление пользователями, установите флажок Получать пароль из модуля Credential. При этом поле Пароль станет недоступным для заполнения. В поле Имя внешнего пользователя в этом случае указывается имя внешнего пользователя, созданного в сервисе Управление пользователями, учетные данные которого будут использоваться для аутентификации.

Примечание

У внешнего пользователя должна быть выбрана текущая внешняя система. Это возможно только если внешняя система уже создана.

Bearer 

При запуске веб-клиента с настроенной аутентификацией типа Bearer выполняется запрос токена для выполнения процедуры аутентификации. Обновление токена происходит автоматически. Токен используется при получении сообщений и при отправке сообщений во внешний сервис.

Настройки аутентификации устанавливаются в режиме редактирования конфигурации внешней системы в значении поля asClient:

path: базовый адрес url, указанный в окне настроек внешней системы.
authTypeRest: тип аутентификации, указанный в окне настроек внешней системы.
authPath: адрес url внешнего сервиса, в котором нужно получить токен.
userName и passwordNew в поле account: имя пользователя и пароль для получения токена во внешнем сервисе, указанном в authPath.
Поле url в поле authorization: путь API-запроса получения токена, который будет добавлен к authPath. В поле можно указывать параметры {user_name} и {password}, в них подставятся значения userName и passwordNew.
methodType в поле authorization: тип API-запроса для получения токена (GET, POST, PUT).
tokenPath: наименование поля, в котором хранится токен, в json-ответе внешнего сервиса, в котором нужно получить токен.

Пример части конфигурации веб-сервис-клиента, в которой указаны параметры аутентификации для подключения к внешнему веб-сервису http://srs-dv-dev:75/ работающему с аутентификацией с использованием токена Bearer (получение токена осуществляется с помощью выполнения POST-запроса http://srs-dv-dev:75/api/session/token?login=пользователь&password=пароль):

      {

"$type": "DT.ClusterConfiguration.DtSystem, DT_Core",

"config": {

      "asClient": {

        "$type": "DT.ConfigurationRepository.Configuration.Adapter.WebClientConfig, DT_ConfigurationRepository",

        "toPlatform": false,

        "fromPlatform": true,

        "readCookiesToPlatform": false,

        "readHeadersToPlatform": false,

        "responceCodes": [],

        "path": "http://srs-dv-dev:75/",

        "authTypeSoap": "Auto",

        "authTypeRest": "Bearer",

        "authPath": "http://srs-dv-dev:75/",

        "account": {

              "$type": "DT.ClusterConfiguration.Account, DT_Core",

              "userName": "пользователь",

              "passwordNew": "пароль",

              "useCredential": false

        },

        "threadCountFromPlatform": 0,

        "authorization": {

              "$type": "DT.ConfigurationRepository.Configuration.Adapter.AuthorizationSettings, DT_ConfigurationRepository",

              "accessToken": {

                "$type": "DT.ConfigurationRepository.Configuration.Adapter.AuthTokenSettings, DT_ConfigurationRepository",

                "tokenPath": "AccessToken",

                "url": "api/session/token?login={user_name}&password={password}",

                "methodType": "Post",

                "headers": {
                      "$type": "System.Collections.Generic.Dictionary'2[[System.String, System.Private.CoreLib],[System.String, System.Private.CoreLib]], System.Private.CoreLib"
                      }

              }

                },

                "proxyOptions": {

                      "$type": "DT.ConfigurationRepository.Configuration.Adapter.ProxyOptions, DT_ConfigurationRepository",

                      "useCustomProxy": false,

                      "proxyAddress": "",

                      "bypassProxyOnLocal": true,

                      "useDefaultCredentials": true,

                      "needServerAuthentication": true

                },

                "allowIfServerCertificateValidationFailed": false

              }

        }

      }

Пример json-ответа внешнего сервиса, в котором нужно получить токен авторизации для случая выше:

{

  "AccessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6ImludHVzZXIiLCJTZXNzaW9uSWQiOiJiYTBhZmVkNy01NmFlLTRmZDYtOGE5Yy04YTlkZjVmMjkwYmUiLCJVc2VySWQiOiJjOTJmNzcxMS1lOThlLTQ1MTctYTUzNS04MzlhZWQ1MmViYzciLCJuYmYiOjE3MDMyMzU0MzQsImV4cCI6MTcwMzIzOTAzNCwiaWF0IjoxNzAzMjM1NDM0LCJpc3MiOiJEYXRhcmVvblBsYXRmb3JtIiwiYXVkIjoiRGF0YXJlb25XZWJTZXJ2aWNlIn0.AL_4rrkHgT-Oi2jHjF4oZuT17PI0c_JtukSdiFIXKLo",
  "Username": "user1",
  "RefreshToken": null,
  "UserId": "c92f7711-e98e-4517-a535-839aed52ebc7",
  "SessionId": "ba0afed7-56ae-4fd6-8a9c-8a9df5f290be",
  "IsAdmin": false
}

Примечание

При неудачной попытке получения токена внешняя система будет отображаться в ЦМ в состоянии Сломано, при этом попытки попытки получить токен будут предприниматься автоматически.

Загрузка сертификата подлинности сервера 

При подключении Платформы к внешней системе имеется возможность загрузить заверенный сертификат для проверки подлинности сервера. Для этого следует установить флажок Использовать клиентский сертификат для подключения. В результате в рабочей области будут отображены параметры авторизации сертификата:

Для загрузки сертификата:

Нажмите на кнопку Загрузить сертификат.
Выберите файл сертификата и нажмите на кнопку Открыть.

Для установки пароля для сертификата:

Установите флажок Задать пароль для сертификата.
Введите пароль в поле Пароль сертификата.
Сохраните изменения.

Если пароль сертификата хранится в сервисе Управление пользователями, установите флажок Получать пароль сертификата из модуля Credential.

Ограничение количества запросов 

В Платформе реализована возможность ограничения количества запросов в секунду для внешних систем Расширенное REST API и Веб-сервис.

Набор конечных точек (endpoints) у внешней системы Веб-сервис предопределенный, включение и настройка ограничений количества запросов в секунду производятся в настройках внешней системы.

Включенное ограничение работает для запросов, которые принимают процесс DatareonPlatformAdapter внешней системы (если в запросе отправляется адрес сервера кластера Платформы, на котором в данный момент запущен процесс DatareonPlatformAdapter внешней системы).

Перенаправление (код ответа 302 для переадресации вызова сервиса) выполняется безусловно для всех запросов без ограничений, контроль ограничения выполняется на шаге непосредственного выполнения запроса.

Включение ограничения 

Настройки выполняются в рабочей области вкладки Коннектор:

Чтобы установить ограничение:

Установите флажок Включить ограничение.
Введите значение ограничения в поле Максимальное количество запросов в секунду.

Максимальное количество запросов в секунду: диапазон значений 1-1000000000 (значение по умолчанию - 1000).
Введите значение кода ответа в поле Код ответа при превышении лимита.

Возможные значения кода ответа при превышении лимита: 429 (используется по умолчанию), 503.

Дополнительные настройки 

Для проверки соответствия выбранных обработчиков веб-системе требуется проверить конфигурацию с помощью редактора конфигурации. Для перехода в режим редактора конфигурации используйте переключатель Режим диалога / редактора конфигурации.

Внимание

Перед переходом в режим редактора конфигурации сохраните внесенные данные!

В результате отобразится интерфейс для установки дополнительных настроек:

Рабочая область редактора предоставляет возможность просмотреть, изменить или добавить новые параметры конфигурации.

После внесения данных нажмите на кнопку Сохранить изменения, после этого нажмите на кнопку Применить конфигурацию.

Для выхода из редактора конфигурации используйте переключатель Режим диалога / редактора конфигурации повторно (будет отображена подсказка Перейти в режим диалога).

В конфигурации доступен блок Config с подблоками asServer (параметры системы веб-сервис-сервер) и asClient (параметры системы веб-сервис-клиент).

Параметры подблока asServer:

Параметр

Тип данных

Описание

esb24

булево

Совместимость с Datareon ESB 2.4

bodyType

массив байтов

Тип тела сообщения (только для протокола SOAP)

fromPlatform

булево

Направление из Платформы

toPlatform

булево

Направление в Платформу

portFromPlatform

строка

Порт из Платформы

portToPlatform

строка

Порт в Платформу

useHttps

булево

Использование протокола HTTPS

authTypeRest

строка

Тип авторизации REST подключения

sslProtocols

массив строк

Настройка протоколов SSL

authForProcesses

булево

Проброс авторизации пользователя в процесс

credentialsInBody

булево

Передача аутентификационных данных в теле запроса

Примечание

При аутентификации типа Bearer с применением формата XML аутентификационные данные внутреннего пользователя требуется передавать в теле запроса в следующем виде:

<?xml version="1.0"?>
<LoginInfo xmlns="http://datareon.ru" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <Login>Администратор</Login>
        <Password>Datare0n!</Password>
</LoginInfo>

Примечание

Если значение параметра authForProcesses = true, при отправке сообщения от авторизованного пользователя к сообщению будет добавлен идентификатор пользователя (userid). Для корректной работы параметра сервис Управление пользователями должен быть активен.
При значении параметра credentialsInBody: true в запросе получения токена Bearer для аутентификации имя пользователя и пароль внутреннего пользователя будут переданы в теле запроса, при значении false - в параметрах запроса. Подробное описание приведено в разделе Расширенное REST API.

Параметры подблока asClient:

Параметр

Тип данных

Описание

fromPlatform

булево

Направление из Платформы

toPlatform

булево

Направление в Платформу

readCookiesToPlatform

булево

Чтение cookies

readHeadersToPlatform

булево

Чтение заголовков

responceCodes

массив объектов

Настройка успешности у кодов ответа

path

строка

Путь подключенного сервиса

authTypeSoap

строка

Тип авторизации SOAP подключения

authTypeRest

строка

Тип авторизации REST подключения

authForProcesses

булево

Проброс авторизации пользователя в процесс

threadCountFromPlatform

целое число

Количество потоков в направлении «Из Платформы»

useCustomProxy

булево

Использование пользовательского прокси-сервера

proxyAddress

строка

Адрес прокси-сервера

bypassProxyOnLocal

булево

Использование прокси-сервера в запросах к локальным ресурсам

useDefaultCredentials

булево

Использование идентификационных данных по умолчанию

needServerAuthentication

булево

Необходимость идентификации на сервере

allowIfServerCertificateValidationFailed

булево

Разрешать HTTPS-подключение к серверу, имеющему невалидный SSL-сертификат. Значение по умолчанию - false.

Примечание

Если в параметрах обработчика указать параметр Accept-Encoding как header (заголовок), он будет игнорироваться системой, и заголовок в ответе получен не будет.

Примеры использования параметров конфигурации 

Код ответа 

В ответе от сервиса подключаемой системы возвращается код ответа, который может восприниматься Платформой как успешный или неуспешный. Успешность и неуспешность кодов ответа может быть определена с помощью параметра responceCodes.

Пример использования параметра:

"responceCodes": [
{
"$type": "DT.ConfigurationRepository.Configuration.Adapter.ResponceCode,
DT_ConfigurationRepository",
"code": 555,
"isSuccess": true
},
{
"$type": "DT.ConfigurationRepository.Configuration.Adapter.ResponceCode,
DT_ConfigurationRepository",
"code": 200,
"isSuccess": false
}
]

В результате запроса во внешней системе и в сервисе обработки процессов код ответа 555 будет возвращаться как успешный, а код 200 как неуспешный.

Если при отправке сообщения в веб-сервис получен неуспешный код ответа, он будет перенаправлен в ветку исключений вместе с описанием ошибки. Обратиться к исключению, содержащему неуспешный код ответа, можно при помощи LastException.

Прокси-сервер 

Пример конфигурации для использования прокси-сервера:

"proxyOptions": {
        "$type": "DT.ConfigurationRepository.Configuration.Adapter.ProxyOptions, DT_ConfigurationRepository",
        "useCustomProxy": true,
        "proxyAddress": "http://5.55.555.55:5555",
        "bypassProxyOnLocal": false,
        "useDefaultCredentials": false,
        "needServerAuthentication": true
}

Примечание

Для введения идентификационных данных при использовании прокси-сервера следуйте инструкции, приведенной в разделе Использование внешних пользователей для авторизации.

Аутентификация 

Для конфигурации веб-сервис-сервер можно включить аутентификацию c использованием токенов доступа Bearer (рекомендуемый способ) или использовать базовую (Basic) схему аутентификации. Для аутентификации используются учетные данные пользователей, созданных в сервисе Управление пользователями.

Пример конфигурации для включения аутентификации:

{
        "$type": "DT.ClusterConfiguration.DtSystem, DT_Core",
        "config": {
                "authTypeRest": "Bearer",
                "auth": {
                        "$type": "DT.ClusterConfiguration.AuthenticationConfig, DT_Core",
                        "enabled": true,
                        "usePasswordHash": false
                }
        }
}

Протоколы SSL 

Поддерживается работа со следующими протоколами: TLS1.0, TLS1.1, TLS1.2. Доступны к использованию только протоколы, указанные в параметрах TLS при запросах к системе. Настройка протокола учитывается только при значении true параметра useHttps. Актуальные настройки SSL отображаются в ЦМ:

Примечание

Если значения параметра не указаны, будут использованы настройки по умолчанию (разрешено использование всех поддерживаемых протоколов), при этом информация о выбранных протоколах не будет отображаться в ЦМ.

Пример конфигурации для настройки протоколов SSL:

{
        "$type": "DT.ClusterConfiguration.DtSystem, DT_Core",
        "config": {
                "$type": "DT.ConfigurationRepository.Configuration.Adapter.WebSystemSimpleConfig, DT_ConfigurationRepository",
                "connectorType": "WebSimple",
                "protocol": "Rest",
                "format": "Json",
                "asServer": {
                        "$type": "DT.ConfigurationRepository.Configuration.Adapter.WebServerConfig, DT_ConfigurationRepository",
                        "esb24": false,
                        "bodyType": "ByteArray",
                        "toPlatform": true,
                        "fromPlatform": true,
                        "portToPlatform": 101,
                        "portFromPlatform": 567,
                        "useHttps": true,
                        "authTypeRest": "Anonymous",
                        "sslProtocols": [
                                "Tls",
                                "Tls11",
                                "Tls12"
                        ],
                        "authForProcesses": false
                }
        }
}

Мониторинг 

В Журнале ЦМ отображается информация о запросах, выполненных с ошибкой:

В Событиях есть возможность сохранять (логировать) заголовки из сообщений. Заголовки отображаются в поле Детали:

При передаче сообщения в Платформу значения заголовков устанавливаются в свойства сообщения ("properties"):

"customFields": {
               "$type": "DT.ExternalMessageData, DT_TypeBuilder.Entities",
               "id": "e34042c5-2ef4-4d1d-a6a9-ab8e2c289502",
               "properties": {
                       "$type": "SystemModels.PropertiesCollection, DT_TypeBuilder.Entities",
                       "properties": {
                               "$type": "System.Collections.Generic.Dictionary`2[[System.String, System.Private.CoreLib],[DT.Property, DT_TypeBuilder.Entities]], System.Private.CoreLib",