Это старая версия документа!
Содержание
Как добавить REST или SOAP сервис на Сервере Безопасности
Перед началом
- Подсистема(subsystem) зарегистрирована: статус
registered. - Ваше приложение работает, API доступен с самого Security Server.
- Для REST известны базовый URL, Service Code и нужные HTTP методы/пути.
- Для SOAP опубликован корректный WSDL, доступный с Security Server.
Пример: ваша система работает по адресу http://10.10.10.10:8080/api/. Это внутренний адрес вашего приложения, а не адрес чужого Security Server.
Вариант A: REST
- Откройте CLIENTS → [ваша подсистема] → SERVICES.
- Нажмите ADD REST.
- Выберите тип описания:
- REST API Base Path — укажите базовый URL API, например
http://10.10.10.10:8080/api/. - OpenAPI 3 Description — укажите доступную ссылку на OpenAPI 3 описание, если оно существует и корректно.
- Введите Service Code — короткий уникальный код сервиса в данной подсистеме, например
citizen-info. - Нажмите ADD.
- Разверните добавленное REST-описание и откройте сервис по его коду. Проверьте целевой URL, параметры подключения и timeout; сохраните изменения (SAVE).
- В списке описаний включите добавленный сервис/описание (после добавления он по умолчанию выключен).
Обратите внимание: для REST Base Path endpoint-ы можно добавить вручную: откройте сервис → ENDPOINTS → ADD ENDPOINTS, задайте HTTP-метод и путь. Для OpenAPI 3 endpoint-ы обычно загружаются из описания. Это важно, если нужно ограничивать доступ к отдельным путям.
Вариант B: SOAP
- Откройте CLIENTS → [ваша подсистема] → SERVICES.
- Нажмите ADD WSDL.
- Вставьте URL WSDL, например
http://10.10.10.10:8080/ws/service?wsdl. - Нажмите ADD. Security Server прочитает WSDL и сформирует список методов.
- Разверните WSDL и проверьте найденные Service Code и адреса методов.
- Откройте нужный сервис, проверьте конечный URL, протокол и timeout; сохраните (SAVE).
- Включите WSDL/описание сервиса: сразу после добавления оно обычно отключено.
Важно: для SOAP нельзя произвольно придумать имя метода, не соответствующее WSDL. При изменении WSDL используйте обновление описания (Refresh) и проверьте, что методы и адреса остались корректными.
Что ещё нужно сделать
Публикация не выдаёт права другому участнику. Перейдите к настройке доступа (ACL).
Проверка результата
- Описание присутствует в SERVICES.
- Сервис enabled (включён), а не disabled.
- Внутренний URL доступен с Security Server.настройка доступа (ACL)
- У нужного потребителя есть ACL на сервис (или на конкретный REST endpoint).
- Реальный тестовый запрос проходит через X-Road; прямой
curlк вашему API проверяет только внутреннюю часть маршрута.
Частые ошибки
- WSDL не загружается — URL, DNS, firewall, TLS, некорректный XML.
- ServiceFailed / NetworkError — Security Server не может подключиться к приложению; проверьте URL, порт, сертификат и логи приложения.
- UnknownService — неверный код сервиса/подсистемы либо сервис не опубликован/недоступен; сравните идентификаторы.
- AccessDenied — сервис опубликован, но потребителю не разрешён вызов.
Источник: X-Road Security Server User Guide, главы 6–7, Тундук: предоставление REST сервисов.
