Клиент REST-сервиса на основе OpenAPI

На платформе Entaxy вы можете создать клиентов двух типов: Клиент SOAP-сервиса на основе WSDL (с поддержкой службы аутентификации и авторизации Java (JAAS)) и Клиент REST-сервиса на основе OpenAPI (с поддержкой службы аутентификации и авторизации Java (JAAS) и OAuth авторизации*). Выбор между ними зависит от требований проекта и предпочтений в использовании соответствующих технологий.

*Текущая версия модуля OAuth разработана под сервер авторизации Keycloak, но может быть сконфигурирована под работу с другими серверами авторизации.

Ниже представлено руководство по созданию и настройке REST-клиента.

Параметры REST-клиента

General

Название	Описание
Factory	Идентификатор используемой фабрики с предустановленным значением (REST :: OPENAPI :: CLIENT).
Object Id	Уникальный идентификатор клиента.
Display name	Отображаемое имя клиента.
Description	Поле для краткого описания.

Название

Описание

Factory

Идентификатор используемой фабрики с предустановленным значением (REST :: OPENAPI :: CLIENT).

Object Id

Уникальный идентификатор клиента.

Display name

Отображаемое имя клиента.

Description

Поле для краткого описания.

Redelivery policy

Настройка обработки ошибок и повторной доставки сообщений. Подробнее ознакомиться можно здесь.

Routes

AGGREGATOR
Маршрут для агрегирования нескольких сообщений на основе заданных критериев.
LISTENER-QUEUE-ARTEMIS
Маршрут для интеграции с использованием очередей брокера сообщений ActiveMQ Artemis, с прослушиванием и обработкой сообщений в рамках интеграционных маршрутов.
QUARTZ
Маршрут используется для планирования задач с помощью Quartz Scheduler. Он позволяет запускать маршруты на основе расписания, которое можно настроить с помощью Cron выражений или простых интервалов времени.
ROUTE-CALLABLE
Маршрут для выполнения настраиваемых логик и операций, позволяющий вызывать различные функции и взаимодействовать с внешними системами.
SUBSCRIPTION-TOPIC-ARTEMIS
Маршрут для интеграции с использованием подписки на топики брокера сообщений ActiveMQ Artemis, с прослушиванием и обработкой сообщений в рамках интеграционных маршрутов.
TIMER
Маршрут предназначен для создания периодических событий. Он позволяет запускать маршруты через заданные интервалы времени, такие как каждая секунда, минута или час, без необходимости использования внешних планировщиков или триггеров.

Main

Название	Описание
Schema Validation Enabled	Активация проверки тела запроса на соответствие структуре и формату заданной схемы API.
Data Format	Формат данных для обработки: * POJO: Используется для работы с данными в виде Plain Old Java Objects, что позволяет напрямую работать с Java объектами. * ORIGIN: Используется для работы с данными в их исходном виде.
Absolute Address	Полный URL адрес публикации REST-сервиса в рамках шины по которому будут отправляться запросы.
OpenApi schema	Загрузка YAML/JSON файла. Для загрузки нажать "Select" и выбрать предварительно загруженный на платформу YAML/JSON файл. В открывшемся окне выбрать .yaml / .json файл и нажать кнопку "Select".
Title	Заголовок API. Заполняется автоматически на основе загруженного YAML/JSON файла.
Operation Router	Редактируемый параметр маршрутизации данных на основе загруженного YAML/JSON файла.

Название

Описание

Schema Validation Enabled

Активация проверки тела запроса на соответствие структуре и формату заданной схемы API.

Data Format

Формат данных для обработки:

* POJO: Используется для работы с данными в виде Plain Old Java Objects, что позволяет напрямую работать с Java объектами.

* ORIGIN: Используется для работы с данными в их исходном виде.

Absolute Address

Полный URL адрес публикации REST-сервиса в рамках шины по которому будут отправляться запросы.

OpenApi schema

Загрузка YAML/JSON файла. Для загрузки нажать "Select" и выбрать предварительно загруженный на платформу YAML/JSON файл. В открывшемся окне выбрать .yaml / .json файл и нажать кнопку "Select".

Title

Заголовок API. Заполняется автоматически на основе загруженного YAML/JSON файла.

Operation Router

Редактируемый параметр маршрутизации данных на основе загруженного YAML/JSON файла.

Security

Название	Описание
Auth Password	Пароль используемый для аутентификации.
Auth Username	Имя пользователя используемое для аутентификации.

Название

Описание

Auth Password

Пароль используемый для аутентификации.

Auth Username

Имя пользователя используемое для аутентификации.

Producer

Название	Описание
Lazy Start Producer	Определяет, следует ли откладывать инициализацию продюсера до момента получения первого сообщения. Ленивый запуск позволяет CamelContext и маршрутам запускаться даже в тех случаях, когда немедленная инициализация продюсера может привести к сбою и прервать запуск маршрута. При ленивой инициализации возможные ошибки можно обработать с помощью маршрутизируемых обработчиков ошибок Camel при первом обращении к продюсеру. Следует учитывать, что инициализация и запуск продюсера при первом сообщении могут занять больше времени, что увеличит общее время обработки.
Cookie Handler	Определяет использование обработчика cookies для управления и поддержания состояния HTTP-сессии.
Hostname verifier	Параметр, позволяющий использовать пользовательский javax.net.ssl.HostnameVerifier.
Throw Exception On Failure	Параметр, позволяющий отключить генерацию HttpOperationFailedException в случае неудачных ответов от удаленного сервера. Это позволяет получать все ответы независимо от кода состояния HTTP.

Название

Описание

Lazy Start Producer

Определяет, следует ли откладывать инициализацию продюсера до момента получения первого сообщения. Ленивый запуск позволяет CamelContext и маршрутам запускаться даже в тех случаях, когда немедленная инициализация продюсера может привести к сбою и прервать запуск маршрута. При ленивой инициализации возможные ошибки можно обработать с помощью маршрутизируемых обработчиков ошибок Camel при первом обращении к продюсеру. Следует учитывать, что инициализация и запуск продюсера при первом сообщении могут занять больше времени, что увеличит общее время обработки.

Cookie Handler

Определяет использование обработчика cookies для управления и поддержания состояния HTTP-сессии.

Hostname verifier

Параметр, позволяющий использовать пользовательский javax.net.ssl.HostnameVerifier.

Throw Exception On Failure

Параметр, позволяющий отключить генерацию HttpOperationFailedException в случае неудачных ответов от удаленного сервера. Это позволяет получать все ответы независимо от кода состояния HTTP.

Advanced

Название	Описание
Basic Property Binding	Определяет, должен ли компонент использовать базовое связывание свойств (Camel 2.x) или новое связывание свойств с дополнительными возможностями.
Continuation Timeout	Используется для настройки таймаута Continuation CXF, который может использоваться в CxfConsumer по умолчанию, когда сервер CXF использует транспорт Jetty или Servlet.
Default Bus	Устанавливает шину по умолчанию, которая будет использоваться, если конечная точка CXF создает шину самостоятельно.
Perform Invocation	Если чек-бокс включен, Camel выполнит вызов экземпляра класса ресурса и поместит объект ответа в обмен (exchange) для дальнейшей обработки.
Propagate Contexts	Если чек-бокс включен, контексты JAXRS UriInfo, HttpHeaders, Request и SecurityContext будут доступны для пользовательских процессоров CXFRS в виде типизированных свойств обмена Camel. Эти контексты могут быть использованы для анализа текущих запросов с помощью JAX-RS API.
Synchronous	Устанавливает, следует ли строго использовать синхронную обработку, или Camel может использовать асинхронную обработку (если это поддерживается).

Название

Описание

Basic Property Binding

Определяет, должен ли компонент использовать базовое связывание свойств (Camel 2.x) или новое связывание свойств с дополнительными возможностями.

Continuation Timeout

Используется для настройки таймаута Continuation CXF, который может использоваться в CxfConsumer по умолчанию, когда сервер CXF использует транспорт Jetty или Servlet.

Default Bus

Устанавливает шину по умолчанию, которая будет использоваться, если конечная точка CXF создает шину самостоятельно.

Perform Invocation

Если чек-бокс включен, Camel выполнит вызов экземпляра класса ресурса и поместит объект ответа в обмен (exchange) для дальнейшей обработки.

Propagate Contexts

Если чек-бокс включен, контексты JAXRS UriInfo, HttpHeaders, Request и SecurityContext будут доступны для пользовательских процессоров CXFRS в виде типизированных свойств обмена Camel. Эти контексты могут быть использованы для анализа текущих запросов с помощью JAX-RS API.

Synchronous

Устанавливает, следует ли строго использовать синхронную обработку, или Camel может использовать асинхронную обработку (если это поддерживается).

Header filter

Название	Описание
Header Filter Strategy	Для использования пользовательской стратегии фильтрации заголовков org.apache.camel.spi.HeaderFilterStrategy для фильтрации заголовков в сообщениях Camel.

Название

Описание

Header Filter Strategy

Для использования пользовательской стратегии фильтрации заголовков org.apache.camel.spi.HeaderFilterStrategy для фильтрации заголовков в сообщениях Camel.

Common

Название	Описание
Logging Feature Enabled	Чек-бокс включает функцию CXF Logging Feature, которая записывает входящие и исходящие REST-сообщения в журнал.
Logging Size Limit	Ограничение общего размера количества байт, которые будет выводить регистратор при включенной функции протоколирования.
Providers	Установка списка пользовательских провайдеров JAX-RS для конечной точки CxfRs. Вы можете указать строку со списком провайдеров для поиска в реестре через запятую.
Skip Fault Logging	Чек-бокс определяет, будет ли цепочка перехватчиков PhaseInterceptorChain пропускать логирование ошибки (Fault), которую она перехватывает.

Название

Описание

Logging Feature Enabled

Чек-бокс включает функцию CXF Logging Feature, которая записывает входящие и исходящие REST-сообщения в журнал.

Logging Size Limit

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

Providers

Установка списка пользовательских провайдеров JAX-RS для конечной точки CxfRs. Вы можете указать строку со списком провайдеров для поиска в реестре через запятую.

Skip Fault Logging

Чек-бокс определяет, будет ли цепочка перехватчиков PhaseInterceptorChain пропускать логирование ошибки (Fault), которую она перехватывает.

Ssl Context Parameters

Название	Описание
Ssl Context Parameters	Этот параметр используется для настройки безопасности с помощью SSLContextParameters. Вы можете использовать визуальную конфигурацию с базовыми настройками или, если требуется более точная настройка, создать beans и выбрать опцию "custom".

Название

Описание

Ssl Context Parameters

Этот параметр используется для настройки безопасности с помощью SSLContextParameters. Вы можете использовать визуальную конфигурацию с базовыми настройками или, если требуется более точная настройка, создать beans и выбрать опцию "custom".

Producer (advanced)

Название	Описание
Http Client API	Если значение установлено в "true", CxfRsProducer будет использовать HttpClientAPI для вызова сервиса. Если значение установлено в "false", CxfRsProducer будет использовать ProxyClientAPI для вызова сервиса.
Ignore Delete Method Message Body	Чек-бокс определяет, будет ли CxfRsProducer игнорировать тело сообщения метода DELETE при использовании HTTP API.
Max Client Cache Size	Параметр позволяет настроить максимальный размер кэша. Реализация кэширует CXF-клиентов или ClientFactoryBean в CxfProvider и CxfRsProvider. По умолчанию размер кэша равен 10.

Название

Описание

Http Client API

Если значение установлено в "true", CxfRsProducer будет использовать HttpClientAPI для вызова сервиса. Если значение установлено в "false", CxfRsProducer будет использовать ProxyClientAPI для вызова сервиса.

Ignore Delete Method Message Body

Чек-бокс определяет, будет ли CxfRsProducer игнорировать тело сообщения метода DELETE при использовании HTTP API.

Max Client Cache Size

Параметр позволяет настроить максимальный размер кэша. Реализация кэширует CXF-клиентов или ClientFactoryBean в CxfProvider и CxfRsProvider. По умолчанию размер кэша равен 10.

Oauth

Название	Описание
Enable OAuth	Чек-бокс активирует параметры OAuth авторизации.
Static token	Чек-бокс активирует использование статических токенов (требуется заполнить параметр Token).
Target header	Указывает заголовок, который используется для направления запроса. По умолчанию - Authorization.
Target header pattern	Задает шаблон для формирования значения целевого заголовка. Значение по умолчанию "Bearer ${exchangeProperty.oauthToken}".
Encode token to base64	Чек-бокс определяет, будет ли токен закодирован в формат base64 перед его отправкой.
Grant type	Определяет тип потока аутентификации, используемый для получения токена доступа. Варианты: Password: используется, когда клиент предоставляет имя пользователя и пароль для получения токена. Client Credentials: используется, когда клиент получает токен, аутентифицируясь с помощью учетных данных client_id и client_secret.
URL token	Параметр указывает URL, по которому осуществляется запрос для получения токена.
URL refresh	Параметр указывает URL для обновления токена. Если он не задан, используется URL токена.
Client Id	Уникальный идентификатор клиента, используемый для аутентификации в системе.
Client secret	Секретный ключ клиента, используемый для аутентификации и подтверждения его подлинности.
Username	Имя пользователя, используемое для аутентификации.
Password	Пароль пользователя, используемый для аутентификации.
Pre-Token	Конфигурация параметров получения токена до выполнения основной операции.
Pre-Refresh	Конфигурация параметров обновления токена до выполнения основной операции.
Parse response	Конфигурация параметров обработки ответа сервера после получения запроса.
Refresh policy	Политика обновления токена. Варианты: no refresh - обновление токена не выполняется. expired - токен обновляется за заданное время до истечения его срока действия (требуется заполнить параметр Request beforehand). timer - токен обновляется через фиксированные интервалы времени (требуется заполнить параметр Refresh timer). error - будут предприниматься попытки повторного получения токена, если сервис возвращает ошибку, код состояния которой указан в параметре Http error codes (можно указать несколько кодов состояния через запятую).

Название

Описание

Enable OAuth

Чек-бокс активирует параметры OAuth авторизации.

Static token

Чек-бокс активирует использование статических токенов (требуется заполнить параметр Token).

Target header

Указывает заголовок, который используется для направления запроса. По умолчанию - Authorization.

Target header pattern

Задает шаблон для формирования значения целевого заголовка. Значение по умолчанию "Bearer ${exchangeProperty.oauthToken}".

Encode token to base64

Чек-бокс определяет, будет ли токен закодирован в формат base64 перед его отправкой.

Grant type

Определяет тип потока аутентификации, используемый для получения токена доступа. Варианты:

Password: используется, когда клиент предоставляет имя пользователя и пароль для получения токена.

Client Credentials: используется, когда клиент получает токен, аутентифицируясь с помощью учетных данных client_id и client_secret.

URL token

Параметр указывает URL, по которому осуществляется запрос для получения токена.

URL refresh

Параметр указывает URL для обновления токена. Если он не задан, используется URL токена.

Client Id

Уникальный идентификатор клиента, используемый для аутентификации в системе.

Client secret

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

Username

Имя пользователя, используемое для аутентификации.

Password

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

Pre-Token

Конфигурация параметров получения токена до выполнения основной операции.

Pre-Refresh

Конфигурация параметров обновления токена до выполнения основной операции.

Parse response

Конфигурация параметров обработки ответа сервера после получения запроса.

Refresh policy

Политика обновления токена. Варианты:

no refresh - обновление токена не выполняется.

expired - токен обновляется за заданное время до истечения его срока действия (требуется заполнить параметр Request beforehand).

timer - токен обновляется через фиксированные интервалы времени (требуется заполнить параметр Refresh timer).

error - будут предприниматься попытки повторного получения токена, если сервис возвращает ошибку, код состояния которой указан в параметре Http error codes (можно указать несколько кодов состояния через запятую).

Consumer (advanced)

Название	Описание
Exchange Pattern	Шаблон обмена сообщений определяет тип взаимодействия между потребителем и поставщиком в контексте маршрутизации сообщений: InOnly — Потребитель отправляет запрос без ожидания ответа от поставщика. Этот шаблон подходит для сценариев, когда важно только доставить сообщение, а подтверждение его получения не требуется. InOut — Потребитель отправляет запрос и ожидает получить ответ от поставщика. Это стандартный шаблон обмена для операций, требующих подтверждения успешного выполнения или получения результата обработки запроса. InOptionalOut — Потребитель отправляет запрос и может ожидать ответ, но получение ответа является необязательным. Этот шаблон используется в случаях, когда ответ на запрос может быть полезен, но не критически важен для продолжения работы потребителя.

Название

Описание

Exchange Pattern

Шаблон обмена сообщений определяет тип взаимодействия между потребителем и поставщиком в контексте маршрутизации сообщений:

InOnly — Потребитель отправляет запрос без ожидания ответа от поставщика. Этот шаблон подходит для сценариев, когда важно только доставить сообщение, а подтверждение его получения не требуется.

InOut — Потребитель отправляет запрос и ожидает получить ответ от поставщика. Это стандартный шаблон обмена для операций, требующих подтверждения успешного выполнения или получения результата обработки запроса.

InOptionalOut — Потребитель отправляет запрос и может ожидать ответ, но получение ответа является необязательным. Этот шаблон используется в случаях, когда ответ на запрос может быть полезен, но не критически важен для продолжения работы потребителя.

Создать клиент

Для создания REST-клиента:

Перейдите в раздел Сервисы и Клиенты.
Откройте вкладку Services and Clients.
Нажмите на кнопку "Add Service".
В появившемся окне выберите REST-client и нажмите "Next".

Заполните необходимые параметры.

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

General:
- Object Id: укажите уникальный идентификатор клиента.
Main:
- Absolute address: укажите полный URL REST-сервиса (например, http://localhost:8181/cxf/rest-service), по которому будут отправляться запросы.
- OpenApi schema: загрузите YAML- или JSON-файл, описывающий ресурс. На его основе будет создан клиент.
Security (при необходимости):
Настройте параметры аутентификации, если REST-сервис использует JAAS.

Подробнее о создании и настройке REST-сервисов.

Укажите:
- Auth Username — имя пользователя для аутентификации.
- Auth Password — пароль для аутентификации.
OAuth (при необходимости):

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

Активируйте чек-бокс "Enable OAuth".
Укажите параметры авторизации, если REST-сервис использует OAuth. Пример настройки и валидации OAuth Introspect с использованием REST API.
Выберите Grant Type:
- Password
  
  Заполнение обязательных параметров:
  - URL Token — укажите URL для получения токена.
  - Client Id — укажите идентификатор клиента.
  - Client Secret — укажите секретный ключ клиента.
  - Username — укажите имя пользователя.
  - Password — укажите пароль пользователя.
    
    Следующие параметры конфигурации обязательны, но при отсутствии особых требований их можно оставить без изменений:
  - Pre get token: получение токена перед выполнением основной операции.
  - Pre refresh: обновление токена перед выполнением основной операции.
  - Parse Response: обработка ответа сервера после выполнения запроса.
- Client Credentials
  
  Заполнение обязательных параметров:
  - URL Token — укажите URL для получения токена.
  - Client Id — укажите идентификатор клиента.
  - Client Secret — укажите секретный ключ клиента.
    
    Следующие параметры конфигурации обязательны, но при отсутствии особых требований их можно оставить без изменений:
  - Pre get token: получение токена перед выполнением основной операции.
  - Pre refresh: обновление токена перед выполнением основной операции.
  - Parse response: обработка ответа сервера после выполнения запроса.

После заполнения всех необходимых параметров нажмите кнопку "Add" для сохранения настроек и создания REST-клиента.

После успешного создания REST-клиента автоматически создается выходной коннектор клиента.

После подключения выходного коннектора клиента к профилю системы в параметрах pre-output коннектора отображается конфигурация маршрутов операций, доступных через REST-клиент.

Она включает:

Тег <m:set-operation> - определяющий вызываемую REST-клиентом операцию.

Пример:
```
<m:set-operation>deleteToById</m:set-operation>
```
Шаблон параметра пути.

Пример:
```
<setProperty name="NTX_CLIENT_pet_id">
    <simple>undefined</simple>
</setProperty>
```
Свойство NTX_CLIENT_pet_id используется для подстановки значения в переменную пути {pet_id} (path: /pets/{pet_id}; verb: DELETE; operationId: deleteToById). Тег <simple> — задает значение, которое присваивается указанному свойству. Значение по умолчанию undefined указывает, что параметр не задан.

Просмотреть список созданных клиентов

Перейдите в раздел Сервисы и Клиенты, затем откройте вкладку Services and Clients.
На этой вкладке вы увидите таблицу с информацией о созданных клиентах и сервисах.

Таблица содержит следующие столбцы:

Name: уникальное имя созданного клиента.
Status: текущий статус клиента.
Например, "Active" или "Resolved".
Actions: содержит кнопки для управления клиентом: Start (запуск клиента), Stop (остановка клиента), Edit (редактирование свойств клиента).
- View Properties: просмотр свойств клиента.
- Uninstall: удаление клиента.
  
  Если вы хотите найти конкретный клиент по имени или статусу, используйте фильтр. Введите имя клиента или выберите нужный статус в соответствующем поле фильтра. Таблица автоматически обновится, чтобы показать только результаты соответствующие поиску.

Остановить клиент

На вкладке Services and Clients в строке соответствующего клиента найдите столбец "Actions", в котором находятся кнопки управления клиентом.
Нажмите кнопку Stop.
Клиент будет остановлен. Появится подтверждающее сообщение о том, что операция выполнена успешно: "Operation Succeeded!".
В столбце "Status" клиента должно отображаться "Resolved", подтверждая успешную остановку.

Запустить клиент

На вкладке Services and Clients в строке соответствующего клиента найдите столбец "Actions", в котором находятся кнопки управления клиентом.
Нажмите кнопку Start.
Клиент будет запущен. Появится подтверждающее сообщение о том, что операция выполнена успешно: "Operation Succeeded!".
В столбце "Status" клиента должно отображаться "Active", подтверждая успешный запуск.

Удалить клиент

На вкладке Services в строке соответствующего клиента найдите столбец "Actions", в котором находятся кнопки управления клиентом .
Нажмите кнопку Uninstall.
Появится сообщение с просьбой подтвердить удаление клиента. Убедитесь, что вы действительно хотите удалить клиент, так как эту операцию нельзя отменить.
Подтвердите удаление, выбрав Confirm или отмените удаление, выбрав Cancel.
В случае подтверждения появится подтверждающее сообщение о том, что операция выполнена успешно: "Operation Succeeded!".
Клиент удален. Он больше не будет отображаться в списке клиентов.