Веб-сервис

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

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

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

../../_images/image76.png

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

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

  • SOAP

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

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

  • XML

  • Text

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

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

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

Веб-сервер

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

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

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

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

Важно

Для включения аутентификации в системе добавьте следующую пару ключ-значение в объект 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).

../../_images/platform_outer.png

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

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

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

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

  • Anonymous: анонимный тип аутентификации, не требующий настройки дополнительных параметров.

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

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

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

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

../../_images/auth_basic1.png

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

../../_images/auth_basic2.png

Примечание

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

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
}

Примечание

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

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

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

../../_images/image802.png

Внимание

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

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

../../_images/image81.png

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

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

../../_images/config_apply1.png

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

В конфигурации доступен блок 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 отображаются в ЦМ:

../../_images/ssl_cm.png

Примечание

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

Пример конфигурации для настройки протоколов 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
                }
        }
}