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

«1С:Исполнитель» предоставляет возможность вызывать внешний Web (SOAP) сервис и удобно обрабатывать полученные ответы. Для этого предназначен элемент проекта Клиент Soap Сервиса:

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

Для реализации клиента SOAP-сервиса вам следует создать элемент проекта Клиент Soap Сервиса и определить у него следующие свойства:

1. UrlПоУмолчанию — URL, по которому по умолчанию будет выполняться запрос к SOAP-сервису. Можно выполнять запросы по адресу, отличающемуся от UrlПоУмолчанию. В этом случае, при создании объекта КлиентSoapСервиса в конструктор требуется передать параметр — подготовленный КлиентHttp.
2. ВерсияSoap — версия SOAP, используемая при формировании исходящих и интерпретации входящих SOAP сообщений. Поддерживаются версии SOAP 1.1 и 1.2. По-умолчанию — SOAP 1.1.

Пример:

ВидЭлемента: Клиент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 схема будет загружена в проект.

При загрузке будет выполнена генерация типов встроенного языка, соответствующих WSDL-описанию сервиса. В типе клиента с именем элемента проекта будут сгенерированы методы для вызова операций сервиса.

дополнительно

При повторной загрузке типы встроенного языка генерируются заново, и могут быть внесены несовместимые изменения, если 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 схеме	Тип поля структуры
anyType / anySimpleType	Объект
string / anyURI / QName / NOTATION / normalizedString / token / language / NMTOKEN / NMTOKENS / Name / NCName / ID / IDREF / IDREFS / ENTITY / ENTITIES	Строка
boolean	Булево
decimal / float / double / integer / nonPositiveInteger / negativeInteger / long / int / short / byte / nonNegativeInteger / unsignedLong / unsignedInt / unsignedShort / unsignedByte / positiveInteger	Число
dateTime	ДатаВремя
time	Время
date	Дата
duration	Длительность
gYearMonth	Дата (в которой день всегда 1, а год и месяц заданы)
gMonthDay	Дата (в которой год всегда текущий, а месяц и день заданы)
gYear	Число (соответствующее году)
gMonth	Число (соответствующее месяцу)
gDay	Число (в диапазоне от 1 до 31)
hexBinarybase64Binary	Байты
simpleType	В зависимости от базового типа (см. в таблице выше)
complexType	Структура соответствующего типа

Также во внимание принимаются ограничения minOccurs и maxOccurs:

minOccurs	maxOccurs	Тип поля структуры
не задано или 1	не задано или 1	Тип из схемы
0	не задано или 1	Тип из схемы или Неопределено
0	unbounded или конкретное значение больше 1	Массив<Тип из схемы>?
не задано или конкретное значение больше 0	unbounded или конкретное значение больше 1	Массив<Тип из схемы>

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

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

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

В общем виде методы, сгенерированные по WSDL описанию, выглядят следующим образом:

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

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

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

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

Чтобы вызвать какую-либо операцию сервиса, следует создать экземпляр типа <Имя-клиента-soap-сервиса>. Он создается с помощью конструктора:

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

В качестве параметра конструктору передается значение типа КлиентHttp. Вы можете передать в него все необходимые настройки для выполнения HTTP-запроса. Например:

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

Если значение параметра Неопределено, то используется значение типа КлиентHttp с настройками по умолчанию. Например:

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

После того как создан экземпляр типа <Имя-клиента-soap-сервиса>, вы можете вызывать операции SOAP-сервиса из встроенного языка. Если в WSDL-описании SOAP-сервиса есть типы (например, структура Товар), которые передаются в качестве параметров в операции сервиса, то получить к ним доступ из встроенного языка можно следующим образом:

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

Вызвать операцию SOAP-сервиса можно следующим образом:

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

Если операция возвращает какие-либо значения, вы можете получить результат вызова операции:

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

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

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

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

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

В проекте модуль, расширяющий тип <Имя-клиента-soap-сервиса>, называется модулем клиента SOAP-сервиса. Он исполняется на сервере.

Дополнительно для каждой операции сервиса в модуле клиента SOAP-сервиса вы можете создать:

• Обработчик записи заголовка SOAP-сообщения. Это опциональный обработчик для настройки элемента Header исходящего SOAP-сообщения для клиента сервиса версии SOAP 1.1 (1.2 соответственно). В качестве параметров получает значения, переданные при вызове метода <ИмяМетодаСервиса>. Данный обработчик вызывается автоматически перед выполнением запроса к SOAP сервису. В теле метода вы можете вызывать метод ЗаписьSoap_1_1.СоздатьЗаголовок (ЗаписьSoap_1_2.СоздатьЗаголовок) для создания заголовка (пример).

  // Для ВерсияSoap==Soap_1_1
  НастроитьЗаголовкиSoap<ИмяМетодаСервиса>(<параметры по WSDL>, ЗаписьSoap: ЗаписьSoap_1_1, ПараметрЗаголовков: Объект?)
  
  // Для ВерсияSoap==Soap_1_2
  НастроитьЗаголовкиSoap<ИмяМетодаСервиса>(<параметры по WSDL>, ЗаписьSoap: ЗаписьSoap_1_2, ПараметрЗаголовков: Объект?)

• Обработчик чтения заголовка SOAP-сообщения. Это опциональный обработчик для чтения заголовков ответа SOAP-сервиса в виде XML. Вызывается «1С:Исполнителем» при получении ответа от SOAP-сервиса. Элемент Header ответа сервиса передается в метод через параметр Заголовок. Возвращаемое значение — прочитанные заголовки (пример).

  ОбработатьЗаголовкиSoap<ИмяМетодаСервиса>(Заголовок: ЧтениеXml): Объект?