Веб-сервис 

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

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

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

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

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://srv-dt-dev01:7635/ работающему с аутентификацией с использованием токена Bearer (получение токена осуществляется с помощью выполнения POST-запроса http://srv-dt-dev01:7635/api/session/token?login=user1&password=password1):

      {

"$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://srv-dt-dev01:7635/",

        "authTypeSoap": "Auto",

        "authTypeRest": "Bearer",

        "authPath": "http://srv-dt-dev01:7635/",

        "account": {

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

              "userName": "user1",

              "passwordNew": "password1",

              "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
}

Примечание

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

Редактирование конфигурации 

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

Внимание

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

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

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

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

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

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

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

Параметр

Тип данных

Описание

esb24

булево

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

bodyType

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

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

fromPlatform

булево

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

toPlatform

булево

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

portFromPlatform

строка

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

portToPlatform

строка

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

useHttps

булево

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

authTypeRest

строка

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

sslProtocols

массив строк

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

authForProcesses

булево

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

credentialsInBody

булево

Передача аутентификационных данных

Примечание

Если значение параметра 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": 405,
"isSuccess": false
}
]

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

Если при отправке сообщения в веб-сервис получен неуспешный код ответа, он будет перенаправлен в ветку исключений вместе с описанием ошибки. Обратиться к исключению, содержащему неуспешный код ответа, можно при помощи строки 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) схему аутентификации. Для аутентификации Bearer используются учетные данные пользователей, созданных в сервисе Управление пользователями.

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

{
        "$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
                }
        }
}