Клиент 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/soap-service-app/api/service
ВерсияSoap: Soap\_1\_1

Загрузка WSDL-описания SOAP-сервиса

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

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

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

При повторной загрузке типы встроенного языка генерируются заново, и могут быть внесены несовместимые изменения, если WSDL-описание сервиса изменилось.

Загрузка WSDL-описания из файла

Если WSDL-описание недоступно по HTTP или для доступа требуется авторизация или настройка прокси, вы можете загрузить описание сервиса из файла. Для этого в навигаторе проекта щелкните правой кнопкой мыши по элементу проекта Клиент SOAP-сервиса и выберите пункт Загрузить WSDL из файла. Выберите нужный файл на компьютере и загрузите его в проект. В навигаторе появится файл с именем ИмяКлиентаSoapСервиса.1.Wsdl, содержащий описание сервиса.

Если в файле есть ссылка на другой WSDL, то вам также необходимо загрузить его в проект. Добавленный файл будет иметь имя ИмяКлиентаSoapСервиса.2.Wsdl.

Если в файле есть ссылка на XSD-схему, добавьте ее в проект следующим образом: щелкните правой кнопкой мыши по элементу проекта Клиент SOAP-сервиса и выберите пункт Загрузить XSD из файла.

Вы можете отредактировать загруженные файлы в среде разработки, обновить их из файла или удалить. Переименовать файлы нельзя, так как иначе «1С:Шина» не сможет прочитать их содержимое в элемент проекта.

Тип «ИмяКлиентаSoapСервиса»

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

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

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

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

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

Тип в 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): Объект?