Одним из механизмов обмена, используемым для передачи данных между кассовым сервером и товароучетной системой, является протокол SOAP. Обмен данными через SOAP может использоваться как самостоятельно, так и параллельно с обычным механизмом загрузки справочников.
Для выполнения загрузки справочников на базе Ubuntu 18.04 на КС необходимо:
Для сервиса exchangers-soap-upload
в директории /etc/default/
необходимо вручную создать пустой файл:
touch exchangers-soap-upload |
Запустить сервис с помощью команды:
systemctl start exchangers-soap-upload |
Просмотреть статус сервиса можно командой:
systemctl status exchangers-soap-upload |
После старта сервис будет работать даже после перезагрузки.
Настройка сервиса обмена SOAP осуществляется в конфигурационном файле /opt/exchangers/config/cs/exchangers.ini
в секции [SOAP_UPLOAD]
.
Наименование | Тип данных | Возможные значения | Описание | Примечания |
---|---|---|---|---|
port | целочисленный | целое положительное число | Порт для SOAP сервиса | По умолчанию 18080 |
maxContentLength | целочисленный | целое положительное число | Максимальный размер тела SOAP запроса в битах | По умолчанию |
authorize | логический |
| Выполнять проверку логина и пароля при SOAP запросе | По умолчанию false |
login | строковый | Логин для авторизации SOAP запроса | По умолчанию admin | |
passwd | строковый | Пароль для авторизации SOAP запроса | По умолчанию admin | |
sessionIdleTimeout | целочисленный | целое положительное число | Время простоя сессии, в секундах | По умолчанию 300 |
shopCodeIsShopId | логический |
| Использовать идентификаторы вместо кодов магазинов | По умолчанию false |
maxCountBackupRequests | целочисленный | целое положительное число | Максимальное количество запросов для одного магазина в бэкап директории | При значении 0 настройка не учитывается |
actualCountDaysForBackupRequests | целочисленный | целое положительное число | Количество дней, в течение которых запросы в бэкап директории считаются актуальными | При значении 0 настройка не учитывается |
useSession | логический |
| Использовать сессионную загрузку справочников | По умолчанию false |
useValidation | логический |
| Использовать валидацию SOAP запросов | По умолчанию false |
singleShopSession | логический |
| В один момент времени разрешать грузить только один справочник в магазин при использовании сессионного режима | По умолчанию false |
multiprocessing | логический |
| Многопоточный режим загрузки через SOAP сервис | По умолчанию false |
[SOAP_UPLOAD] ; Порт для SOAP сервиса port = 18080 ; Максимальный размер тела SOAP запроса в битах. По умолчанию 83886080 (10 MB) maxContentLength=83886080 ; Проверять логин и пароль при SOAP запросе. По умолчанию - False authorize = False ; Логин для авторизации SOAP запроса. По умолчанию - admin login = admin ; Пароль для авторизации SOAP запроса. По умолчанию - admin passwd = admin ; Время простоя сессии (в секундах). Если истекло время, указанное в данной настройке, ; после последнего запроса внутри сессии, то вся сессия отменится. По умолчанию - 300 сек sessionIdleTimeout = 300 ; Являются ли коды магазинов, которые передают в запросе идентификаторами магазинов. По умолчанию - False shopCodeIsShopId = False ; Максимальное количество архивов запросов для одного магазина в бэкап директории (устаревшие архивы будут удаляться) ; Если указать значение 0, то данная настройка учитываться не будет maxCountBackupRequests = 0 ; Количество дней актуальности архивов запросов для одного магазина в бэкап директории (устаревшие архивы будут удаляться) ; Если указать значение 0, то данная настройка учитываться не будет actualCountDaysForBackupRequests = 3 ; Использовать сессионную загрузку справочников. По умолчанию - False useSession = False ; Использовать валидацию SOAP запросов. По умолчанию - False useValidation = False ; В один момент времени разрешать грузить только один справочник в магазин при использовании сессионного режима singleShopSession = False ; Многопоточный режим загрузки через SOAP сервис multiprocessing = False |
Данные справочников из АСТУ на КС передаются в виде xml
-файлов. Документ xml
представляет собой запрос. Актуальная wsdl
для формирования запросов расположена по URL
http://<хост сервера>:18080/soap?wsdl
.
SOAP запрос может представлять:
Все SOAP запросы отправляются на порт сервиса, указанный в настройках. Каждый справочник следует загружать отдельно. Справочник может содержать некоторое количество объектов. Если объектов одного типа слишком много, то запрос необходимо разбить на несколько таким образом, чтобы тело запроса не превышало порога, заданного параметром maxContentLength
.
Архивы запросов на загрузку справочников хранятся помагазинно в директории /opt/exchangers/logs/SOAP_BACKUP
. Количество архивных запросов и количество дней, в течение которых запросы остаются актуальными, определяется параметрами maxCountBackupRequests
и actualCountDaysForBackupRequests
соответственно. Устаревшие запросы удаляются. Если параметры не определены, то в директории хранятся все переданные запросы.
SOAP запрос на добавление объектов может включать 4 параметра:
SOAP запрос на удаление объектов может включать 3 параметра:
В параметре <код магазина>
может быть указан:
Правила использования кодов или идентификаторов задаются параметром shopCodeIsShopId
.
При загрузке справочников используются методы добавления и удаления объектов. Команда clear
не является самостоятельным методом, а используется в качестве параметра метода add
:
clear = true
производится предварительная очистка перед загрузкой данных справочника,clear = false
данные справочника будут добавлены к существующим.Параметр clearIfEmptyData
предназначен для очистки справочников и используется только при значении параметра clear = true
и загрузке пустого справочника. В таблице приведено описание поведения при других значениях параметров clear
и clearIfEmptyData
.
Содержимое справочника | Значения параметров | Поведение | |
---|---|---|---|
clear | clearIfEmptyData | ||
Справочник с данными | true | true | Данные данные не будут добавлены в БД, в результате выполнения запроса выводится ошибка "You can use this option "clearIfEmptyData" only with an empty array of objects" |
true | false | Данные добавляются в БД с очисткой, в результате выполнения запроса выводится сообщение о количестве загруженных объектов | |
false | true | Данные данные не будут добавлены в БД, в результате выполнения запроса выводится ошибка "You can use this option "clearIfEmptyData" only with an empty array of objects" | |
false | false | Данные добавляются в БД без очистки, в результате выполнения запроса выводится сообщение о количестве загруженных объектов | |
Пустой справочник | true | true | Справочник очищен, в результате выполнения запроса выводится сообщение "Sent dictionary clear command" |
true | false | Справочник не очищен, подтверждение операции не полное, в результате выполнения запроса выводится сообщение "There is no confirmation of a complete cleaning dictionary(clear = true, clearIfEmptyData = true). Dictionary is not cleaned" | |
false | true | Справочник не очищен, в результате выполнения запроса выводится сообщение "No entries have been added to queue" | |
false | false | Справочник не очищен, в результате выполнения запроса выводится сообщение "No entries have been added to queue" |
Загрузку одного справочника несколькими запросами можно выполнить единой порцией данных при помощи сессионной загрузки справочников. Возможность сессионной загрузки справочников определяется параметром useSession
. Загрузка в один момент времени только одного справочника в один магазин задается параметром singleShopSession
.
Если сессионная загрузка справочников разрешена (useSession = true
), то для управления сессиями загрузки используются методы:
startSession
– запуск сессии.stopSession
– завершение сессии. Метод должен быть вызван обязательно после окончания отправки справочников, чтобы все переданные части справочника были загружены в БД.rollbackSession
– отмена загрузки справочников. Если сессия была открыта, но за время простоя, определяемого параметром sessionIdleTimeout
, не было выполнено ни одного вызова, то сессия отменяется со всеми переданными данными.В рамках одной сессии может выполняться загрузка данных только на один магазин.
Для добавления одного справочника товаров, разбитого на 2 запроса, необходимо вызвать по порядку методы:
|
Если сессионная загрузка справочников запрещена (useSession = false
), то использование методов управления сессиями будет недоступно. При загрузке справочников одному запросу добавления справочника будет соответствовать один справочник.
SOAP клиент может быть сгенерирован на основании wsdl . |
Команды SOAP соответствуют командам |
Протокол SOAP базируется на обмене сообщениями между клиентом и сервером. Каждое сообщение содержит информацию о данных, которые передаются из АСТУ в БД кассового сервера. SOAP описывает структуру сообщения при помощи XML-схем. На кассовом сервере расположен документ wsdl
, содержащий данные о расположении сервиса, типах данных передаваемых объектов и операции, которые могут быть выполнены при обращении к нему.
Документ wsdl
расположен по адресу http://<хост сервера>:18080/soap/?wsdl
и состоит из следующих элементов:
Элемент | Описание |
---|---|
portType | Методы, предоставляемые веб-сервисом |
types | Типы данных, используемые сервисом |
message | Сообщения, используемые при обмене |
binding | Протоколы связи, используемые веб-сервисом |
service | Используемые адреса |
Веб-сервис, предоставляя возможность вызова какого-либо метода, дает возможность клиентам узнать, какие параметры для этого метода используются. На основании этого принципа любой SOAP-клиент, обращаясь к wsdl
-документу, строит внутреннюю структуру запроса для загрузки справочников.
В качестве параметров запроса могут передаваться простые типы, объекты и коллекции объектов. Описание объекта сводится к описанию всех его полей.
Поля и объекты с пометкой <!--Optional:–>
не обязательны для заполнения и могут быть удалены из запроса.
Объекты с пометкой <!--Zero or more repetitions:–>
могут повторяться в запросе, т.е. одним запросом можно загрузить справочник с несколькими разными объектами, например, товарами, у каждого из которых указываются свои параметры.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:aif="http://aif.soap.exchange.artix.su"> <soapenv:Header/> <soapenv:Body> <aif:addAlcoCodes> <!--Optional:--> <aif:alcocodes> <!--Zero or more repetitions:--> <aif:AlcoCode> <!--Optional:--> <aif:alcocode>112233</aif:alcocode> </aif:AlcoCode> <aif:AlcoCode> <!--Optional:--> <aif:alcocode>334499</aif:alcocode> </aif:AlcoCode> </aif:alcocodes> <!--Optional:--> <aif:shopCode>15</aif:shopCode> <!--Optional:--> <aif:clear>0</aif:clear> <!--Optional:--> <aif:dictionaryId>46</aif:dictionaryId> </aif:addAlcoCodes> </soapenv:Body> </soapenv:Envelope> |