Клиент Web (SOAP) сервиса

Создание клиента SOAP-сервиса

ВидЭлемента: КлиентSoapСервиса
Ид: f65ac26f-0351-48cd-bc93-751912e05bc1
Имя: КлиентСервисаМагазина
ОбластьВидимости: ВПроекте
UrlПоУмолчанию: http://myserver:9090/applications/SOAPServis/api/service
ВерсияSoap: Soap_1_1

В проект необходимо загрузить WSDL-описание сервиса. Для этого в панели Свойства, в поле URL WSDL Soap-сервиса, следует указать HTTP-адрес описания сервиса (часто это адрес сервиса с дополнительным параметром ?wsdl) и нажать кнопку Загрузить в проект. При этом будет выполнен GET-запрос по указанному адресу и полученная WSDL схема будет загружена в проект.

Тип <Имя-клиента-soap-сервиса>

В среде разработки на основе WSDL, полученного от SOAP-сервиса, будет создан тип <Имя-клиента-soap-сервиса>. Этот тип содержит методы, соответствующие операциям сервиса, и структуры для передачи параметров и возвращаемых значений. Имя этого типа совпадает с именем элемента проекта. Например, для клиента SOAP-сервиса с именем КлиентСервисаМагазина будет создан тип КлиентСервисаМагазина

Правила формирования имен

Имена структур данных и методов генерируются на основе описания разных секций WSDL. Если указанное в WSDL имя не является валидным идентификатором встроенного языка, то имя формируется путем замены непригодных символов на символ подчеркивание (например, «field-1» превратится в «field_1»). Уникальность имен обеспечивается добавлением в конец увеличивающегося счетчика. Если полученное имя в результате замены будет состоять только из подчеркиваний и цифр, то будет использован префикс «Structure/Структура» для структуры, «Field/Поле» — для поля структуры, «Method/Метод» — для метода сервиса, «Exception/Исключение» — для исключений, «Enum/Перечисление» — для перечислений.

Генерация типов встроенного языка на основе содержимого секции wsdl:types

Для каждого элемента, описанного в секции wsdl:types, в типе КлиентSoapСервиса создается структура. Имя структуры определяется по имени типа в WSDL схеме с учетом вышеуказанных ограничений. Полное имя типа структуры — <Имя-элемента>.<Имя-cтруктуры>. Для всех элементов и атрибутов, описанных в схемах типов, генерируется поле структуры. Имя поля определяется по имени типа в схеме с учетом вышеуказанных ограничений. Тип поля определяется следующим образом:

Для каждой операции, описанной в секциях wsdl:portType / wsdl:operation, в типе будут созданы:

• Метод <ИмяМетодаСервиса> с именем, сформированным по описанным выше правилам. Параметры метода создаются на основе схемы WSDL. Дополнительно добавляется параметр с именем ПараметрЗаголовков, в котором разработчик может передать дополнительные данные в метод НастроитьЗаголовкиSoap<ИмяМетодаСервиса>.
• Обработчик с именем НастроитьЗаголовкиSoap<ИмяМетодаСервиса> функционального типа. Прикладной разработчик может определить обработчик в модуле элемента и написать в нем код формирования элементов секции Header SOAP сообщения.
• Обработчик с именем ОбработатьЗаголовкиSoap<ИмяМетодаСервиса> функционального типа. Прикладной разработчик может определить обработчик в модуле элемента и написать в нем код чтения элементов секции Header SOAP сообщения.
• Свойство с именем ПередЗапросом<ИмяМетодаСервиса> функционального типа. Значение свойства — метод, который позволяет настроить свойства HTTP-запроса, выполняемого к сервису при вызове метода <ИмяМетодаСервиса>. Например, позволяет задать заголовки для неподдерживаемых способов аутентификации. В параметре обработчику передается полностью подготовленный платформой запрос. Прикладной разработчик может настроить свойства запроса, например, определить его заголовки, но не может его выполнить. При попытке вызвать метод Выполнить выбрасывается исключение. Если установлено значение Неопределено, то выполняется запрос, подготовленный .
• Для SOAP-ошибок, описанных в WSDL, генерируются:
  1. Исключение. Базовый тип — ИсключениеВызоваSoapСервиса. Имя исключения формируется из имени XML-типа ошибки с учетом правил формирования имен.
  2. Структура с деталями ошибки. Имя структуры формируется из имени XML-типа ошибки с постфиксом Detail с учетом правил формирования имен.

// Методы-процедуры (не возвращают результат):
<ИмяМетодаПродедурыСервиса>(<параметры по WSDL>, ПараметрЗаголовков: Объект? = Неопределено): ОтветSoap

// Методы-функции (возвращают результат):
<ИмяМетодаФункцииСервиса>(<параметры по WSDL>, ПараметрЗаголовков: Объект? = Неопределено): ОтветФункцииSoap<ТипРезультата>

где ТипРезультата — тип структуры, сгенерированной для хранения результата, возвращаемого методом-функцией SOAP-сервиса.

Вызов операций SOAP-сервиса

новый <Имя-клиента-soap-сервиса>(КлиентHttp: КлиентHttp?=Неопределено)

знч Аутентификация = новый АутентификацияHttp("Пользователь", "Пароль")
знч Url = "https://адрес/путь/к/ресурсу"
пер ПодготовленныйКлиентHttp = КлиентHttp.САутентификацией(Аутентификация).СБазовымUrl(Url)
    
знч Клиент = новый КлиентСервисаМагазина(ПодготовленныйКлиентHttp)

знч Клиент = новый КлиентСервисаМагазина()

знч Товар = новый КлиентСервисаМагазина.Товар("МойТовар", 100)

знч ОтветСервиса = Клиент.ДобавитьВКаталог(Товар)

знч Каталог = ОтветСервиса.Результат
знч КоличествоТоваровКаталога = ОтветСервиса.Результат.Количество

При вызове операций SOAP-сервиса может потребоваться передать информацию, используемую для проверки прав доступа к сервису. Для этого часто используется стандарт Web Service Security, который определяет набор стандартных SOAP-заголовков для аутентификации и шифрования. Если для операции в сервисе реализована проверка доступа через WSS-токен UsernameToken, тогда для вызова операции клиенту требуется передать сервису SOAP-заголовок с именем пользователя и паролем. Это можно сделать в обработчике НастроитьЗаголовкиSoap<ИмяМетодаСервиса> (подробнее).

При вызове метода, соответствующего операции внешнего SOAP-сервиса, происходит следующее:

• Переданные в метод значения параметров сериализуются, после чего формируется секция Body SOAP сообщения;
• При наличии, вызывается обработчик НастроитьЗаголовкиSoap<ИмяМетодаСервиса>. Формируется секция Headers SOAP сообщения;
• Сформированное SOAP сообщение помещается в тело HTTP запроса;
• При наличии, вызывается обработчик ПередЗапросом<ИмяМетодаСервиса>, которому передается подготовленный HTTP запрос;
• Выполняется HTTP запрос, и происходит синхронный вызов метода SOAP-сервиса;
• При наличии, вызывается обработчик ОбработатьЗаголовкиSoap<ИмяМетодаСервиса>. Он возвращает значение, которое будет записано в свойство Заголовки результата типа ОтветSoap (для операции-процедуры) или типа ОтветФункцииSoap (для операции-функции);
• В зависимости от кода возврата и наличия в ответе секции Fault, в вызывающий код возвращается результат или выбрасывает исключение. При наличии в SOAP-ответе секции Fault выбрасывается исключение ИсключениеВызоваSoapСервиса.В ином случае выбрасывается ИсключениеHttp. Выброшенные исключения SOAP-сервиса можно обработать во встроенном языке (пример).

Модуль клиента SOAP-сервиса