Руководство прикладного разработчика#

Системные требования#

Требования к окружению для использования компонента приведены в документе Руководство по установке в разделе «Системные требования».

Подключение и конфигурирование#

Подключение#

Для подключения компонента используется публичный API.

Для подключения необходимо:

Уточнить у бизнес-администратора тенанта значение заголовка api-user-key.
Подать заявку администраторам стенда сопровождения среды на добавление клиентских сертификатов и заголовка запроса subsystemcode. Если несколько клиентских систем интегрируются под одним сертификатом, то в запрос клиента можно добавить заголовок subsystemcode, он будет учитываться в мониторинге, и также появится возможность настройки rateLimit на данный заголовок.
После выполнения предыдущих пунктов используйте заголовки API api-user-key и subsystemcode, а также сертификат при создании/выполнении запроса.

Более детально можно ознакомиться в документе Справочники API.

Конфигурация параметров#

Конфигурация параметров запуска#

Описание параметров:

Параметр	Краткое описание	Тип
product360.starter.client.app-api.url	URL до REST-API APP-API	STRING
keycloak.auth-server-url	Адрес до сервера Keycloak	STRING
spring.datasource.jdbcUrl	Адрес мастера БД	STRING
standin.datasource.jdbcUrl:	Адрес стенда БД	STRING
spring.profiles.active:	Активные профиля для запуска	STRING
extend.keycloak.proxy:	Прокси адрес сервера Keycloak	STRING
keycloak.enabled:	Необходимость авторизоваться в опциональном компоненте KeyCloak.SE (KCSE) продукта Platform V IAM SE (IAM)	STRING
spring.datasource.username:	Имя пользователя БД	STRING
standin.datasource.driver-class-name:	Драйвер БД для подключения	STRING
extend.clipas.tech.user:	ТУЗ для работы	STRING
SSL_KEYSTORE_LOCATION:	Путь до keystore Kafka	STRING
SSL_TRUSTSTRE_LOCATION:	Путь до трансфера Kafka	STRING
standin.module.id	Имя модуля в ПЖ	STRING
module.id:	Имя модуля в системе логирования	STRING
standin.cloud.client.zone-id:	Зона ПЖ	STRING
standin.cloud.client.stub:	Флаг заглушки ПЖ	STRING
standin.cloud.client.kafka.bootstrapServers:	Адреса серверов Kafka ПЖ	STRING
AUDIT_HOST	URL API системы аудита	STRING
AUDIT_USER	Пользователь для отправки в систему аудита	STRING
SSL_IDENTIFICATION_ALGORITHM	Алгоритм идентификации для Kafka ПЖ	STRING
product360.starter.client.auth-api.url	URL REST-API APP-API	STRING

Конфигурация кеша#

Описание параметров:

Параметр	Краткое описание	Тип
ufsdictionary.module.cache.ttl	Время жизни кеша платформенного модуля	LONG

Конфигурация мониторинга#

Описание параметров мониторинга приведено в разделе «События мониторинга» документа Руководство по системному администрированию.

Миграция на текущую версию#

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

Изменения в конфигурации каждой версии описаны в разделе «Конфигурация» документа Руководство по установке.

Быстрый старт#

Необходимо подключить компонент PD36 в соответствии с разделом Подключение и конфигурирование настоящего документа.

Убедитесь, что выполнены все условия, указанные в документе Руководство по установке компонента PD36 в разделе Подготовка окружения:

Развернута и настроена система управления базами данных.
На сервере развернуто необходимое программное обеспечение (клиент OC, клиент для работы с PostgreSQL, Docker CE, система оркестрации контейнеризированных приложений).
Созданы docker-образы.
Выделен проект системы оркестрации контейнеризированных приложений.
Произведена настройка проекта системы оркестрации контейнеризированных приложений.
Выделена VM системы управления базами данных.
Произведена первоначальная настройка системы управления базами данных.
Выпущены сертификаты клиентские/серверные для:
- Istio (ingress, egress) при использовании;
- подключения к PostgreSQL по SSL при необходимости;
- ОТТ при необходимости.
Произведен Deploy в системе оркестрации контейнеризированных приложений.
Подготовлено окружение в соответствии с типовой инструкцией по настройке Job (Deploy, Service) при установке через Installer.

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

Дальнейшее использование программного компонента описано в разделе «Использование программного компонента».

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

Описание API компонента можно найти в формате openapi в документе Справочники API.

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

App-api:

https://\<stand-url\>/app-api/swagger-ui.html

Auth-api:

https://\<stand-url\>/auth-api/swagger-ui.html

Datamart-api:

https://\<stand-url\>/datamart-api/swagger-ui.html

Inner-connector-api:

https://\<stand-url\>/inner-connector-api/swagger-ui.html

Contract-external-api:

https://\<stand-url\>/inner-connector-api/external/v1/product-offers/<код профиля импорта>

Mdm-api:

https://\<stand-url\>/mdm-api/swagger-ui.html

Примечание

\<stand-url\> наименование домена необходимо уточнить у администратора стенда.

Использование компонента оператором с помощью UI описано в документе «Руководство оператора».

Загрузка DSL-скриптов#

В компоненте реализована возможность загружать скрипты для DSL-преобразований, используя Jenkins pipeline.

Groovy-файл pipeline (DSL_Deploy.groovy) входит в состав дистрибутива. Для выполнения развертывания необходимо:

Добавить DSL_Deploy.groovy в подключенный к Jenkins SCM-репозиторий. Загрузка происходит путем отправки POST-запроса на URL …/inner-connector-api/external/dsl/create по HTTPS mTLS маршруту с аутентификацией по сертификату и приватному ключу, а также авторизацией в приложении по API-ключу.
Заполнить параметры:
- nexusSecrets — название Jenkins-секрета, используемого для доступа в Nexus;
- configuration — параметры Secman (Vault plugin);
- secretCertPath — путь к секрету с сертификатом и приватным ключом в Secman.
Внутри секрета ожидаются Key/value-пары с ключами dsl-mTLS.key и dsl-mTLS.crt — base64 encoded приватный ключ и клиентский сертификат соответственно.
Создать pipeline из этого файла. Пререквизитом для запуска pipeline является наличие в Nexus артефакта в виде ZIP-архива, содержащего внутри себя (в любом месте) целевой DSL-скрипт для deploy (1 запуск — 1 скрипт).

Каждый DSL-скрипт может быть загружен 1 раз, повторный запуск не приведет к изменению данных, а pipeline возвратит ошибку. Если требуется обновить его содержание, необходимо создать новый скрипт с отличным от предыдущего именем (версионирование через имя).

При запуске pipeline необходимо заполнить параметры:
- distrURL — полный URL до дистрибутива с DSL в Nexus формата https://nexus-url.ru/path/to/distrib.zip;
- DSLFilePath — полный путь до DSL-файла (с названием и расширением) относительно корня дистрибутива. Пример: folder/folder2/dsl_example.json;
Предупреждение

Pipeline не поддерживает работу с вложенными архивами. Путь до файла должен содержать только папки и сам файл.
- endpointURL — полный URL endpoint для загрузки (https://url.ru/inner-connector-api/external/dsl/create);
- apiKey — API-ключ пользователя компонента PD36 для загрузки DSL (должен иметь права на загрузку DSL — выдаются на странице создания ключа).

Часто встречающиеся проблемы и пути их устранения#

Ошибка получения от компонента целевого контура канала#

При ошибке получения от компонента целевого контура канала, в который должен быть перенаправлен пользователь, проверьте корректность и работоспособность настройки, а также наличие сетевого доступа. Также сверьтесь со страницей swagger приложения, все ли требуемые параметры заполнены корректно и в соответствии со swagger.

Ошибки 401-403#

В случае получения ошибок 401-403 проверьте корректность логина и пароля, а также наличие их в системе авторизации (компонент KeyCloak.SE (KCSE) продукта Platform V IAM SE (IAM)).