Skip to end of metadata
Go to start of metadata

Одним из механизмов обмена, используемым для передачи данных между кассовым сервером и товароучетной системой, является протокол SOAP. Обмен данными через SOAP может использоваться как самостоятельно, так и параллельно с обычным механизмом загрузки справочников. 

Включение сервиса SOAP

Для выполнения загрузки справочников на КС должен быть запущен сервис exchangers-soap-uploadУправление сервисом загрузки справочников осуществляется через параметр UPLOAD_SOAP_START в файле /etc/default/exchangers.

НаименованиеТип данныхВозможные значенияОписаниеПримечания
UPLOAD_SOAP_STARTстроковый
  • yes
  • no
Включение SOAP сервиса загрузки справочников

Имя сервиса: exchangers-soap-upload.

По умолчанию сервис выключен

Пример настройки

Запуск сервиса выполняется автоматически после перезагрузки кассового сервера. Для запуска и остановки сервисов вручную предназначена утилита service. Формат вызова: service <name> <action>, где:

  • name - имя сервиса, над которым выполняется действие;
  • action - выполняемое действие (start, stop, restart).

Настройка обмена через SOAP

Настройка сервиса обмена SOAP осуществляется в конфигурационном файле /opt/exchangers/config/cs/exchangers.ini в секции [SOAP_UPLOAD].

НаименованиеТип данныхВозможные значенияОписаниеПримечания

port

целочисленныйцелое положительное числоПорт для SOAP сервисаПо умолчанию 18080

maxContentLength

целочисленныйцелое положительное число

Максимальный размер тела SOAP запроса в битах

По умолчанию 83886080 (10 MB)

authorize

логический
  • true
  • false

Выполнять проверку логина и пароля при SOAP запросе

По умолчанию false

login

строковый Логин для авторизации SOAP запросаПо умолчанию admin

passwd

строковый Пароль для авторизации SOAP запросаПо умолчанию admin

sessionIdleTimeout

целочисленныйцелое положительное числоВремя простоя сессии, в секундахПо умолчанию 300 секунд

shopCodeIsShopId

логический
  • true
  • false
Использовать идентификаторы вместо кодов магазиновПо умолчанию false

maxCountBackupRequests

целочисленныйцелое положительное числоМаксимальное количество запросов для одного магазина в бэкап директорииПри значении 0 настройка не учитывается

actualCountDaysForBackupRequests

целочисленныйцелое положительное числоКоличество дней, в течение которых запросы в бэкап директории считаются актуальнымиПри значении 0 настройка не учитывается

useSession

логический
  • true
  • false
Использовать сессионную загрузку справочниковПо умолчанию false

useValidation

логический
  • true
  • false
Использовать валидацию SOAP запросовПо умолчанию false
Пример настройки

Данные справочников из АСТУ на КС передаются в виде xml-файлов. Документ xml представляет собой запрос. Актуальная wsdl для формирования запросов расположена по URL http://<хост сервера>:<порт сервера>/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.

Содержимое справочникаЗначения параметров очисткиПоведение
clearclearIfEmptyData
Справочник с даннымиtruetrueДанные данные не будут добавлены в БД, в результате выполнения запроса выводится ошибка "You can use this option "clearIfEmptyData" only with an empty array of objects".
truefalseДанные добавляются в БД с очисткой, в результате выполнения запроса выводится сообщение о количестве загруженных объектов.
falsetrueДанные данные не будут добавлены в БД, в результате выполнения запроса выводится ошибка "You can use this option "clearIfEmptyData" only with an empty array of objects".
falsefalseДанные добавляются в БД без очистки, в результате выполнения запроса выводится сообщение о количестве загруженных объектов.
Пустой справочникtruetrueСправочник очищен, в результате выполнения запроса выводится сообщение "Sent dictionary clear command".
truefalseСправочник не очищен, подтверждение операции не полное, в результате выполнения запроса выводится сообщение "There is no confirmation of a complete cleaning dictionary(clear = true, clearIfEmptyData = true). Dictionary is not cleaned".
falsetrueСправочник не очищен, в результате выполнения запроса выводится сообщение "No entries have been added to queue".
falsefalseСправочник не очищен, в результате выполнения запроса выводится сообщение "No entries have been added to queue".

Сессионная загрузка справочников

Загрузку одного справочника несколькими запросами можно выполнить единой порцией данных при помощи сессионной загрузки справочников. Возможность сессионной загрузки справочников определяется параметром useSession

Если сессионная загрузка справочников разрешена (useSession = true), то для управления сессиями загрузки используются методы:

  • startSession - запуск сессии;
  • stopSession - завершение сессии. Метод должен быть вызван обязательно после окончания отправки справочников, чтобы все переданные части справочника были загружены в БД;
  • rollbackSession - отмена загрузки справочников. Если сессия была открыта, но за время простоя, определяемого параметром sessionIdleTimeout, не было выполнено ни одного вызова, то сессия отменяется со всеми переданными данными.

В рамках одной сессии может выполняться загрузка данных только на один магазин. 

Пример

Для добавления одного справочника товаров, разбитого на 2 запроса, необходимо вызвать по порядку методы:

  1. startSession
  2. addInvents
  3. addInvents
  4. stopSession

Если сессионная загрузка справочников запрещена (useSession = false), то использование методов управления сессией запрещено. При загрузке справочников одному запросу добавления справочника будет соответствовать один справочник.

Icon
Описание работы с SOAP сервисом загрузки справочников под ОС Windows приведено в справочной информации, для получения которой необходимо в консоли выполнить команду:
python C:\opt\exchangers\src\upload\fam\cs\winUploadSoapService.py
Icon
SOAP клиент может быть сгенерирован на основании wsdl.

Особенности использования протокола SOAP

Протокол SOAP базируется на обмене сообщениями между клиентом и сервером. Каждое сообщение содержит информацию о данных, которые передаются из АСТУ в БД кассового сервера. SOAP описывает структуру сообщения при помощи XML-схем. На кассовом сервере расположен документ WSDL, содержащий данные о расположении сервиса, типах данных передаваемых объектов и операции, которые могут быть выполнены при обращении к нему.

Документ wsdl расположен по адресу http://<хост сервера>:18080/soap/?wsdl и состоит из следующих элементов:

ЭлементОписаниеПримечания
portTypeМетоды, предоставляемые веб-сервисом 
types

Типы данных, используемые сервисом

 
messageСообщения, используемые при обмене 
bindingПротоколы связи, используемые веб-сервисом 
serviceИспользуемые адреса 

Веб-сервис, предоставляя возможность вызова какого-либо метода, дает возможность клиентам узнать какие параметры для этого метода используются. На основании этого принципа любой SOAP-клиент, обращаясь к wsdl документу, строит внутреннюю структуру запроса для загрузки справочников.

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

Поля и объекты с пометкой <!--Optional:–> не обязательны для заполнения и могут быть удалены из запроса. 

Объекты с пометкой <!--Zero or more repetitions:–> могут повторяться в запросе, т.е. одним запросом можно загрузить справочник с несколькими разными объектами, например, товарами, у каждого из которых указываются свои параметры.

Пример soap-запроса
Icon

Команды SOAP соответствуют командам AIF, отличительной особенностью является суффикс "s" у большинства команд SOAP.

  • No labels