Описание ecos-edi-ftps-lib
1. Назначение
Библиотека ecos-edi-ftps-lib предназначена для обмена EDI-сообщениями с контрагентами через FTP- или FTPS-сервер. Описание сверено с версией 1.8.0.
Общий принцип работы:
Контрагент помещает сообщения во входные папки. При запуске настроенной синхронизации библиотека обходит подходящие каталоги и обрабатывает оставшиеся в них файлы. Поиск в подкаталогах управляется отдельным флагом. Постоянного курсора и отдельной проверки, что файл ранее не обрабатывался, в этой библиотеке нет; подробнее — в разделе 4.
Для отправки библиотека записывает EDI-сообщение в папку, из которой его забирает контрагент; подробнее — в разделе 3.
2. Настройка интеграции
Перед созданием настроек установите совместимый OSGi-бандл по инструкции загрузки пакетов. Загрузку выполняйте от имени системного администратора. При старте бандл регистрирует FTP API, сервис синхронизации и listener событий ящика; при остановке снимает эти регистрации.
В POM версии 1.8.0 заданы Camel 3.11.2, ecos-osgi-loader 2.0.0, ecos-edi-commons 2.9.0 и Commons Net 3.6 со scope provided. Принимающее приложение должно предоставлять совместимые API, OSGi-экспорты и необходимые EDI-сервисы в Spring-контексте. Совместимость этой версии бандла с современным окружением на Camel 4 здесь не подтверждена.
Для настройки создайте сущности ecos-credentials, ecos-data-sources, edi-box и ecos-sync. Названия полей и скриншоты ниже относятся к показанной поставке интерфейса; в другой версии формы могут отличаться.
2.1. Создание ecos-credentials сущности
Тут все стандартно, создаем через журнал ecos-credentials запись, в которой указываем логин и пароль для подключения к FTP-серверу.
2.2. Создание ecos-data-sources сущности
Создайте сущность FTP Data source. Задайте идентификатор и понятное название; ссылку на эту запись затем укажите в ящике.
Важны host, port и protocol:
Поле |
Описание |
|---|---|
|
Имя или адрес FTP/FTPS-сервера, доступного из микросервиса интеграций. |
|
Явно укажите фактический порт сервера. В версии 1.8.0 при пустом поле код выбирает 22, а не 21; не полагайтесь на это значение для своего FTP/FTPS-сервера. |
|
Поддерживаются FTP и FTPS. SFTP не поддерживается; значение порта 22 не включает работу по SSH. |
Для подключения должны быть заполнены host, распознанный protocol, положительный port и непустые логин и пароль в связанной записи credentials. Передача файлов выполняется в бинарном и пассивном режиме. Для FTPS библиотека запрашивает защищённый канал данных через PBSZ 0 и PROT P; параметры TLS и доверия сертификатам проверяйте на целевом сервере.
2.3. Создание edi-box сущности
Создаем сущность «FTP box».
Самая основная часть конфигурации именно тут. Тут существует 3 раздела. В верхнем разделе:
Поле |
Описание |
|---|---|
|
Указываем любой (или оставляем пустым и оно само сгенерится при создании). |
|
Любое человеко-читаемое название для этого ящика. |
|
Указываем созданный в 2.2 датасорс. |
|
Указываем созданные в 2.1 креды. |
В разделе Box configuration задайте идентификатор собственного ящика. GLN организации — один из вариантов. Код извлекает идентификатор из OurId.attributes в порядке id → boxId → gln, выбирая первое непустое значение. Он используется для поиска настроенного ящика с провайдером EdiProviderType.FTP без учёта регистра.
Этот идентификатор отличается от локального ID записи edi-box. При исходящей отправке значения OurId запроса должны разрешаться в нужный настроенный ящик. Если заполнено несколько атрибутов, приоритет имеет id, затем boxId, затем gln.
Раздел Other:
Поле |
Описание |
|---|---|
|
Шаблон пути, по которому будут отправляться исходящие сообщения. Подробнее в п.3. |
|
Обязательный шаблон пути поиска входящих файлов ( |
|
Чекбокс с говорящим названием, который означает, что мы должны искать документы не только в папке, полностью соответствующей конфигу выше, но и в поддиректориях. |
|
Обязательно выберите |
|
Для |
|
Для |
Папки success/error разместите вне области входного поиска. При включённом обходе подкаталогов специального исключения этих папок нет: перемещённые файлы могут снова попасть в обработку, если соответствуют шаблону.
2.4. Создание ecos-sync сущности
Общий пример создания синхронизации приведён в разделе Настройка получения событий с ящиком Контур.Диадок. Для FTP выберите edi-box из п.2.3 и настройте расписание запуска.
В конфигурации передачи событий обязательно укажите stateServiceConfig.endpoint — endpoint получателя, который умеет обрабатывать события с провайдером FTP и типом EDI_RECEIVED_MESSAGE. Пример настройки Диадока не подтверждает поддержку FTP произвольным маршрутом. Гарантии дальнейшей обработки зависят от реализации EdiStateService и выбранного endpoint.
3. Принципы работы при отправке сообщений
В конфигурации задаются пути внутри FTP-пространства пользователя. Библиотека добавляет ведущий /, если его нет; пустой исходящий путь нормализуется в /. Связь этого корня с файловой системой сервера определяется настройками сервера. Для явного назначения используйте, например, /OUTBOUND.
Переменные исходящего шаблона берутся из EdiXmlRequest библиотеки ecos-edi-commons; см. Описание работы интеграции.
Эта структура состоит из следующих полей:
private OurId ourId;
private CounterpartyId counterpartyId;
private EdiXml ediXml;
private ObjectData data;
где:
Атрибуты
ourIdдоступны какourId.key_from_attributes. Например, для ключейkey1иkey2используютсяourId.key1иourId.key2.Атрибуты
counterpartyIdдоступны какcounterpartyId.key_from_attributes.ediXml.ediDocumentTypeзадаётdocument.typeиdocument.lowerType. Для исходящего сообщения это, например,ORDERSиordersсоответственно.Значения
dataдоступны какaddInfo.key. Ключи и значения с пустым строковым представлением пропускаются.
Вызывающий код заполняет EdiXmlRequest.data до отправки. В версии 1.8.0 библиотека не вызывает FtpCustomAddInfoProvider или FtpCustomAddInfoProviderRegistry; проектную логику подготовки значений реализуйте на стороне отправителя. Пример шаблона:
/${addInfo.counterparty.esk}_S4TEST/OUTBOUND/${document.type}
Это означает, что если в структуре data содержится значение 123456 по ключу counterparty.esk и ediXml.ediDocumentType содержит значение ORDERS, то данное сообщение отправится в следующую папку:
/123456_S4TEST/OUTBOUND/ORDERS/
Можно задать фиксированный путь без переменных, например /OUTBOUND. Тогда все сообщения этого ящика направляются в одну указанную папку.
Например, шаблон:
/${addInfo.path}
Если вызывающий код запишет в request.data ключ path со значением some/path/type/kind/outbound, получится путь:
/some/path/type/kind/outbound
Для отдельного запроса можно переопределить весь шаблон: непустой ключ outboundFolderPathTemplate в request.data имеет приоритет над defaultOutboundFolderPathTemplate ящика. Например:
request.setData(ObjectData.create()
.set("path", "some/path/type/kind/outbound")
.set("outboundFolderPathTemplate", "/${addInfo.path}"));
Неизвестная или пустая переменная без значения по умолчанию вызывает IllegalArgumentException. Для исходящего пути поддерживается форма ${key:default}, например ${addInfo.path:OUTBOUND}.
Для подстановки используется StringSubstitutor из Apache Commons Text с собственным механизмом поиска значений. Эти правила относятся к исходящим путям; входной поиск строит регулярные выражения по правилам раздела 4.1.
Подробнее можно ознакомиться в тестах к либе.
Отправить сообщение можно с помощью интерфейса EdiService, передав ему EdiProviderType.FTP. Доступные методы:
generateEdiXmlделегирует работу зарегистрированномуEdiXmlGeneratorдля FTP и указанного ID контроллера генерации. Этот бандл не регистрирует встроенные генераторы; для успешного вызова генератор должен предоставить другой модуль или проектный код.sendEdiXml(EdiXmlRequest)отправляет сообщение на FTP/FTPS-сервер. ОбязательныediXml, его содержимое, имя файла и массив байтов. Ящик определяется поOurIdзапроса.
Перегрузка sendEdiXml(SignedEdiXmlRequest) не реализована и выбрасывает UnsupportedOperationException. Большинство других операций EdiApiService, включая отправку пакетов и подписей, этим провайдером также не поддерживается.
Сервис EdiService доступен из микросервиса integrations-app.
4. Принципы работы при получении сообщений
Получение сообщения состоит из трёх фаз:
Найти и прочитать файл.
Сформировать событие и передать его в
EdiStateService.Удалить или переместить файл в соответствии с политикой.
4.1. Обход в поиске сообщений
Для поиска используется итератор FtpWalkIterator с очередью файлов и папок. Он продолжает обход между файлами в пределах одного вызова синхронизации. Следующий запуск создаёт новый итератор и снова начинает обход от /; сохранённая позиция между запусками не используется. После возврата политики callback получает EdiSyncState(null).
Итератор использует обязательный Inbound documents folder path template и флаг Search documents in subdirectories из п.2.3. Укажите входной путь с ведущим /; отсутствие шаблона не означает поиск по всему серверу и приводит к ошибке.
Шаблон поиска входящих разбивается на уровни по папкам. То есть, например, шаблон /${addInfo.counterparty.esk}_S4TEST/INBOUND/${document.type} разобьется на 4 части:
/
/${addInfo.counterparty.esk}_S4TEST
/${addInfo.counterparty.esk}_S4TEST/INBOUND
/${addInfo.counterparty.esk}_S4TEST/INBOUND/${document.type}
Части преобразуются в регулярные выражения с именованными группами. Например, для набора типов документов из четырёх значений:
/
/(?<addInfoA1B2C3counterpartyA1B2C3esk>[\w\s-]+)_S4TEST
/(?<addInfoA1B2C3counterpartyA1B2C3esk>[\w\s-]+)_S4TEST/INBOUND
/(?<addInfoA1B2C3counterpartyA1B2C3esk>[\w\s-]+)_S4TEST/INBOUND/(?<documentA1B2C3type>ORDERS|ORDRSP|DESADV|RECADV)
Точки в именах групп заменяются строкой A1B2C3 и восстанавливаются при извлечении значений для события. Для обычной переменной используется выражение [\w\s-]+. Значения document.type и document.lowerType берутся из enum EdiDocumentType зависимости ecos-edi-commons; фактический набор и порядок зависят от её версии.
Важно
Во входном поиске версии 1.8.0 document.lowerType использует те же значения enum, что и document.type, без преобразования в нижний регистр. Регулярные выражения компилируются с учётом регистра. Не рассчитывайте на поиск папки orders только за счёт имени переменной document.lowerType. Это отличается от исходящей подстановки.
Если включён флаг поиска в подкаталогах, к последнему регулярному выражению добавляется .*. Имена файлов и расширения отдельно не фильтруются: для файла проверяется путь содержащей его папки. Папки success/error должны быть вне подходящих путей.
Так же, есть возможность указывать не стандартную регулярку, а свою. Пример -
/${addInfo.counterparty.esk(\d+)}_S4TEST/INBOUND/${document.type}
Алгоритм обхода:
Итератор внутри себя содержит очередь. В эту очередь вносятся файлы или папки, которые нужно будет в будущем посмотреть и проверить на предмет файлов, соответствующих регуляркам.
При первом обращении к новому итератору загрузить в очередь список файлов и папок из
/.Взять следующий элемент и выбрать регулярное выражение для его уровня. Для файла использовать последнее выражение и путь его папки.
Если папка соответствует выражению, добавить её содержимое в начало очереди. Если соответствует файл, прочитать его содержимое и вернуть на обработку. Несоответствующий элемент исключить из очереди.
Продолжить обход до следующего файла или опустошения очереди.
При поиске одного следующего подходящего файла действует защитный предел в 1000 просмотренных элементов, после которого возникает ошибка Endless cycle or too many files. Это не общий лимит числа документов за синхронизацию.
4.2. Обработка сообщения
Из значений групп входного пути формируются OurId, CounterpartyId, тип EDI-документа и data. Например, шаблон /${addInfo.counterparty.esk}_S4TEST/INBOUND/${document.type} передаёт извлечённые значения в данные события. Содержимое XML может дополнить или переопределить часть полей, в том числе GLN получателя и отправителя.
Создаётся Event с типом EDI_RECEIVED_MESSAGE и провайдером FTP. Он содержит один обновлённый документ с состоянием RECEIVED и направлением IN. Событие передаётся в EdiStateService.sendEvent с настройками endpoint из синхронизации; дальнейшая обработка определяется этим получателем. Подробнее о модели — Описание работы интеграции.
4.3. Фиксация обработанного сообщения
После возврата sendEvent без исключения библиотека выполняет действие выбранной Inbound processing policy. Внутри этой библиотеки нет отдельного подтверждения завершения конечной бизнес-обработки: гарантии возврата sendEvent зависят от внешней реализации и endpoint.
Отправка события и операция с FTP-файлом не образуют общую атомарную операцию. Если событие отправлено, а последующее удаление или перемещение не удалось, оставшийся входной файл может быть обработан повторно. Получатель должен учитывать возможность дублей.
4.3.1. Политика MOVE_AFTER_PROCESSING
Сначала вычисляется путь из Inbound documents success folder path template, затем формируется и отправляется событие. После возврата sendEvent без исключения файл перемещается в success-папку.
Исключение при вычислении пути, формировании события, отправке или перемещении вызывает попытку переноса в папку из Inbound documents error folder path template. Поэтому наличие файла в error-папке не доказывает, что событие не было отправлено.
Оба пути являются шаблонами и могут использовать значения, извлечённые из входного пути. Все получающиеся папки назначения необходимо создать заранее и проверить права на переименование: moveFile не создаёт каталоги, в отличие от исходящей отправки.
При ответах FTP 550 или 553 код пытается перенести файл с суффиксом `` (N)`` перед расширением; предусмотрено до 50 попыток. Эти повторы не исправляют отсутствие папки назначения. Если перенос в error-папку тоже не удался, ошибка записывается в лог, а файл может остаться во входной папке.
4.3.2. Политика DELETE_ON_SUCCESS
После возврата sendEvent без исключения файл удаляется с FTP-сервера.
При ошибке формирования события, отправки или удаления исключение записывается в лог; отдельного переноса в error-папку нет. Если файл остался на сервере, следующий запуск может получить его снова.
4.4. Диагностика ошибок
Ошибки внутри обработки отдельного файла обе политики журналируют и поглощают. Поэтому сообщение об успешном завершении синхронизации не гарантирует успех всех файлов: проверяйте сообщения Can not process file for path и, для перемещения, Exception while move file.
Чтение файла происходит в итераторе до вызова защищённого обработчика политики. Ошибка поиска или скачивания может прервать весь текущий обход без попытки перенести этот файл в error-папку. Следующий запуск начинает обход заново; отдельного постоянного состояния обработки файлов в библиотеке нет.