Настройка интеграции с веб-сервисами
Интеграция REST и SOAP сервисов позволяет объединить функциональность и данные, предоставляемые различными сервисами, и использовать их вместе в одном приложении или системе.
После успешной интеграции с веб-сервисом предоставляется широкий спектр возможностей для эффективного использования полученных данных в различных бизнес-процессах. Вот несколько примеров применения:
- Создание и обновление записей: можно использовать полученные данные для автоматического создания новых записей или обновления существующих записей. Например, если веб-сервис предоставляет информацию о клиентах, вы можете автоматически создавать профили клиентов на основе этих данных.
- Бизнес-логика: полученные данные могут быть использованы для выполнения различных операций. Например, если веб-сервис предоставляет информацию о товарах, вы можете использовать эти данные для расчета цен, скидок или доступности товаров.
- Автоматизация процессов: данные, полученные от веб-сервиса, могут быть интегрированы в автоматизированные процессы. Например, если веб-сервис предоставляет информацию о доставке, вы можете автоматически отслеживать статус доставки и информировать клиентов о ее прогрессе.
Алгоритм настройки
Интеграция пользовательских веб-сервисов в системе осуществляется с помощью инструментов low-code, что значительно упрощает настройку и использование.
Настройка интеграций с веб-сервисами выполняется в разделе «Веб-сервисы», в который можно перейти несколькими способами:
- Дизайнер системы
→ блок «Импорт и интеграции» → раздел «Настройка интеграции с веб-сервисами»; - Рабочее место «Конструктор» → раздел «Веб-сервисы».
Общая процедура настройки интеграции с веб-сервисом включает следующие шаги:
- Создание веб-сервиса и настройка методов и свойств:
- В разделе «Веб-сервисы» можно добавить веб-сервис и указать его свойства, такие как URL-адрес, имя, описание и другие параметры;
- Для REST-сервисов можно настроить методы запросов (GET, POST, PUT, DELETE) и указать соответствующие URL-пути, параметры запроса, заголовки и тело запроса;
- Для SOAP-сервисов можно добавить WSDL-описание сервиса и автоматически сгенерировать соответствующие методы и параметры.
- Если веб-сервис требует аутентификации, можно настроить соответствующие параметры, такие как тип аутентификации, логин, пароль, токены и другие данные, необходимые для успешного подключения к сервису.
- Проверка интеграции с веб-сервисом:
- После настройки можно выполнить проверку интеграции, которая позволяет убедиться, что система успешно подключается к веб-сервису и может получать ответы от него;
- В процессе проверки можно указать тестовые данные запроса для получения ответа от веб-сервиса.
Интеграция SOAP веб-сервиса
Пример. Настроим интеграцию с сервисом «devinotele.com», чтобы автоматически возвращать баланс пользователя текущей сессии и отправлять сообщения адресатам. Обратите внимание, что конкретные детали настройки могут различаться в зависимости от особенностей конкретного SOAP-сервиса и его документации.
Автоматическая конфигурация веб-сервиса
В BPMSoft есть возможность автоматической настройки интеграцию с SOAP-сервисом.
WSDL-файл содержит информацию о доступных методах, их параметрах, типах данных и другие детали. Импортирование WSDL-файла в систему позволяет автоматически создать соответствующий сервис в разделе «Веб-сервисы».
Для настройки интеграции:
- В разделе «Веб-сервисы» нажмите на кнопку «Добавить веб-сервис» и выберите опцию «SOAP сервис».
- В открывшемся окне «Быстрая настройка SOAP веб-сервиса» выберите файл, нажав на кнопку «Выбрать файл», или укажите ссылку на WSDL-файл, содержащий информацию о структуре сервиса.
Рисунок 1 — Окно быстрой настройки
- После загрузки WSDL-файла или ввода ссылки, система перейдет к окну настройки SOAP сервиса. Здесь вы можете выбрать сервис и установить версию SOAP, которые хотите использовать. Также вы можете настроить методы и параметры. Когда настройка будет завершена, нажмите кнопку «Далее».
Рисунок 2 — Окно настройки
- В окне настройки SOAP сервиса вы можете выбрать необходимые значения ответов методов, которые будут приходить от веб-сервиса.
Рисунок 3 — Выбор значений ответов методов
- После того как все настройки будут выполнены, нажмите кнопку «Сохранить».
Конфигурация веб-сервиса вручную
При ручной настройке сервиса после пропуска быстрой настройки и изучения документации вам необходимо заполнить поля на странице свойств веб-сервиса. Для этого:
- Перейдите в раздел «Веб-сервисы».
- Нажмите «Добавить веб-сервис» и выберите «SOAP сервис».
- В открывшемся окне «Быстрая настройка SOAP веб-сервиса» нажмите «Пропустить быструю настройку».
Рисунок 4 — Пропуск быстрой настройки SOAP веб-сервиса
- Изучите документацию веб-сервиса, она должна содержать XML-код.
- Заполните поля на странице свойств веб-сервиса в соответствии с документацией и требованиями веб-сервиса.
- Нажмите «Сохранить» для сохранения настроек свойств веб-сервиса.
Ниже представлены значения, которые можно использовать при заполнении полей страницы свойств веб-сервиса:
- Название — «Сервис отправки SMS сообщений»;
- Код — «UsrSendSMS»;
- Пространства имен — «http://schemas.xmlsoap.org/wsdl/mime/». Необходимо указывать только те, которые используются для методов и их параметров веб-сервиса. Формат задания набора пространств имен следующий: «Префикс пространства имен»:«Пространство имен».
Например, если у вас есть два пространства имен: «soapenc» с пространством имен «http://schemas.xmlsoap.org/soap/encoding/» и «mime» с пространством имен «http://schemas.xmlsoap.org/wsdl/mime/», то вы можете указать их следующим образом: «soapenc:http://schemas.xmlsoap.org/soap/encoding/;mime:http://schemas.xmlsoap.org/wsdl/mime/».
Если у вас только одно пространство имен, например, «http://schemas.xmlsoap.org/wsdl/mime/», то его можно указать без префикса; - URI сервиса — «https://ws.devinotele.com/SmsServicev2.asmx?WSDL». Необходимо указать полный адрес вызова веб-сервиса. Этот адрес будет состоять из указанного URI и настроек, указанных на странице настройки метода;
- Повторы вызова при ошибках — по умолчанию «0»;
- Пакет — выберите пакет, в котором хотите сохранить данную интеграцию с веб-сервисом. В списке доступные для изменения текущим пользователем пакеты.
Рисунок 5 — Страница настройки SOAP-сервиса
Конфигурирование вызова метода
Для настройки метода сервиса:
- Перейдите на страницу свойств сервиса в разделе «Веб-сервисы».
- На странице интеграции найдите раздел «Методы», добавьте новый метод.
- Изучите документацию сервиса и найдите информацию о методе, который вы хотите вызвать. В текущем примере приведен элемент GetBalance.
<wsdl:types>
<s:element name="GetBalance">
<s:complexType>
<s:sequence>
<s:element minOccurs="0" maxOccurs="1" name="login" type="s:string"/>
<s:element minOccurs="0" maxOccurs="1" name="password" type="s:string"/>
</s:sequence>
</s:complexType>
</s:element>
</wsdl:types>
- Заполните свойства, пространство имен и другие параметры, указанные в документации веб-сервиса.
Для настройки вызова метода сервиса заполните следующие поля
- Название — «Проверить Баланс»;
- Код — «UsrGetBalance»;
- Код элемента сообщения — «GetBalance»;
- SOAP Action — «http://ws.devinosms.com/GetBalance»;
- Тайм-аут ответа, мс — по умолчанию «5000»;
- Использовать аутентификацию — по умолчанию признак снят.
Рисунок 6 — Пример настройки вызова метода
Конфигурирование параметров запроса
Для настройки запроса к веб-сервису необходимо выбрать тип параметра:
- Параметр тела: позволяет отправлять любые типы данных, включая коллекции.
- Параметр заголовка: заголовки запроса используются для передачи метаданных и дополнительной информации.
- Параметр cookies: файлы cookie могут использоваться для аутентификации или сохранения состояния.
Выберите соответствующий тип параметра в зависимости от ваших потребностей и документации веб-сервиса. Затем добавьте параметры запроса, указав имя, тип и описание каждого параметра.
При заполнении параметров запроса учитывайте, что поле «Формат передачи пустых значений» определяет каким образом передается пустое значение параметра. Возможны следующие варианты значений:
- По умолчанию: передается стандартное значение по умолчанию для выбранного типа данных. Например, для логического типа передается false, а для строкового — пустая строка ("");
- Не передавать: если параметр пуст, он не включается в передачу;
- Пустая строка: передается пустая строка ("");
- NULL: пустое значение параметра передается как NULL.
- На вкладке «Параметры вызова» нажмите кнопку «Добавить параметр».
- Заполните свойства параметра «Логин» следующим образом:
- Название — «Логин»;
- Тип параметра — «Параметр тела»;
- Путь к элементу — «tem:login»;
- Код в BPMSoft — «UsrLogin»;
- Тип данных — «Текст»;
- Является массивом — по умолчанию признак снят;
- Обязательный — по умолчанию признак установлен;
- Формат передачи пустых значений — «По умолчанию»;
- Значение по умолчанию — «Константа».
Чтобы добавить параметр запроса «Пароль» для вашего веб-сервиса, выполните следующие шаги:
- На вкладке «Параметры вызова» нажмите кнопку «Добавить параметр».
- Заполните свойства параметра «Пароль» следующим образом:
- Название — «Пароль»;
- Тип параметра — «Параметр тела»;
- Путь к элементу — «tem:password»;
- Код в BPMSoft — «UsrPassword»;
- Тип данных — «Текст»;
- Является массивом — по умолчанию признак снят;
- Обязательный — по умолчанию признак установлен;
- Формат передачи пустых значений — «По умолчанию»;
- Значение по умолчанию — «Константа».
Рисунок 7 — Пример настройки параметров метода
Конфигурирование параметров ответа
Чтобы добавить параметр обработки ответа «Проверить Баланс» для веб-сервиса, выполните следующие шаги:
- В документации веб-сервиса определите формат ответа.
<wsdl:types>
<s:element name="GetBalance">
<s:complexType>
<s:sequence>
<s:element minOccurs="0" maxOccurs="1" name="login" type="s:string"/>
<s:element minOccurs="0" maxOccurs="1" name="password" type="s:string"/>
</s:sequence>
</s:complexType>
</s:element>
<s:element name="GetBalanceResponse">
<s:complexType>
<s:sequence>
<s:element minOccurs="1" maxOccurs="1" name="GetBalanceResult" type="s:decimal"/>
</s:sequence>
</s:complexType>
</s:element>
</wsdl:types>
- Перейдите на вкладку «Обработка ответа».
- Нажмите кнопку «Добавить параметр».
- Заполните свойства параметра «Баланс» следующим образом:
- Название — «Баланс»;
- Тип параметра — «Параметр тела»;
- Путь к элементу — «tem:GetBalanceResult»;
- Код в BPMSoft — «UsrGetBalanceResult»;
- Тип данных — «Дробное число»;
- Является массивом — по умолчанию признак снят;
- Формат передачи пустых значений — «По умолчанию»;
- Значение по умолчанию — «Константа».
Рисунок 8 — Пример настройки параметров ответа
Тестовый запрос
Чтобы проверить настройку интеграции с SOAP-сервисом и получить его ответ в интерфейсе приложения, выполните следующие действия:
- Перейдите в раздел «Веб-сервисы».
- Откройте страницу веб-сервиса, с которым вы хотите проверить интеграцию, например, «Сервис отправки SMS сообщений».
- На странице с деталями методов настройки интеграции откройте метод «Проверить баланс».
- На странице настройки метода нажмите кнопку «Отправить тестовый запрос».
- Задайте значения параметров вызова метода.
- Нажмите кнопку «Отправить запрос».
- После выполнения тестового запроса вы получите ответ от веб-сервиса. Значения параметров ответа будут отображены на вкладке «Параметры ответа» в соответствующих полях. Другие вкладки позволяют просмотреть запрос и ответ на запрос в форматах XML и HTTP (raw).
Вы сможете оценить, как работает ваша интеграция с SOAP-сервисом и убедиться, что получаете ожидаемые значения в ответе от сервиса.
Интеграция REST веб-сервиса
Пример. Настроим интеграцию с сервисом «apilayer.net», чтобы возвращать текущий валютный курс.
Конфигурация свойств и методов веб-сервиса
Параметры запроса представляют собой значения, передаваемые вместе с запросом к REST-сервису. Они используются для настройки запроса и передачи дополнительной информации, которая может влиять на обработку и результаты запроса.
Автоматический режим
Чтобы добавить параметры из поля «Полный адрес»:
- Нажмите кнопку «Быстрая настройка», расположенную в верхней части окна добавления метода.
- В выпадающем списке выберите «По полю «Адрес метода»».
- В открывшемся списке выберите необходимые параметры и нажмите кнопку «Сохранить».
Рисунок 9 — Параметры запроса
Параметры будут добавлены в запрос, их можно использовать на шаге бизнес-процесса «Вызвать веб-сервис». Вы можете изменять параметры, например, установить признак «Обязательный» для параметра «Access_key».
Ручной режим
Добавление веб-сервиса
Для добавления REST-сервиса в систему выполните следующие шаги:
- Перейдите в раздел «Веб-сервисы».
- Нажмите «Добавить веб-сервис» и выберите «REST сервис».
- Заполните свойства веб-сервиса:
- Название — значение, которое будет отображаться в поле «Какой сервис вызывать?» в элементе процесса «Вызвать веб-сервис». Например, «Курсы обмена валют»;
- Код — укажите уникальное имя, которое используется разработчиками;
- URI сервиса (Uniform Resource Identifier) — представляет собой уникальный идентификатор ресурса в REST-сервисе. Он включает протокол (например, HTTP или HTTPS), доменное имя или IP-адрес сервера, порт (если отличается от стандартного) и путь к конкретному ресурсу или методу. Например, «http://apilayer.net/api/live»;
- Повторов вызова при ошибках — определяет количество попыток повторного выполнения запроса к REST-сервису в случае возникновения ошибки или неудачного ответа;
- Тип — выберите тип веб-сервиса. Значение по умолчанию — «REST»;
- Пакет — пакет конфигурации BPMSoft, в котором хранится веб-сервис. Для новых веб-сервисов вы можете выбрать пользовательский пакет, доступный для изменения.
- После заполнения всех полей нажмите «Сохранить», чтобы добавить REST-сервис и перейти к настройке его методов и аутентификации.
Рисунок 10 — Страница настройки REST-сервиса
Настройка методов веб-сервиса
Для настройки методов веб-сервиса выполните следующие действия:
- На странице сервиса перейдите на вкладку «Методы».
- Заполните свойства метода:
- Название — укажите название метода, которое будет отображаться в поле «Какой сервис вызывать» в области свойств элемента процесса «Вызвать веб-сервис»;
- Код — укажите уникальное имя, которое используется разработчиками;
- Адрес метода — указывает на конкретный ресурс или функциональность, доступную через этот метод. Адрес метода обычно состоит из базового URL-адреса сервиса, дополненного путем или параметрами, которые идентифицируют конкретный ресурс или операцию;
- Полный адрес — представляет собой конкретный URL-адрес, который составляется путем объединения базового URL-адреса сервиса и адреса метода с указанием всех необходимых параметров запроса;
- Тип запроса — тип запроса указывает на метод HTTP, который будет использоваться при выполнении запроса к REST-сервису;
- Тайм-аут ответа, мс — определяет максимальное время ожидания ответа от REST-сервиса после отправки запроса. Важно подобрать оптимальное значение тайм-аута. Если значение слишком маленькое, запрос может быть прерван, не дожидаясь ответа. С другой стороны, слишком большое значение тайм-аута может вызывать задержки в обработке запросов, особенно если REST-сервис не отвечает;
- Использовать аутентификацию — флаг, используется ли аутентификация.
Рисунок 11 — Методы REST сервиса
Конфигурация параметров запроса
Ручной режим
На вкладке «Параметры вызова» нажмите кнопку «Добавить параметр» и добавьте новый параметр с названием «API ключ». Заполните свойства параметра следующим образом:
- Название — «API ключ»;
- Тип параметра — «Параметр запроса»;
- Код в запросе — «access_key»;
- Код в BPMSoft — «UsrAccesskey»;
- Обязательный — относится к параметру метода REST-сервиса и указывает, является ли этот параметр обязательным при вызове метода;
- Формат передачи пустых значений — определяет каким образом передается пустое значение параметра. Возможны следующие варианты значений:
- По умолчанию: передается стандартное значение по умолчанию для выбранного типа данных. Например, для логического типа передается false, а для строкового — пустая строка ("");
- Не передавать: если параметр пуст, он не включается в передачу;
- Пустая строка: передается пустая строка ("");
- NULL: пустое значение параметра передается как NULL.
- Значение по умолчанию — относится к параметру метода REST-сервиса и предоставляет значение, которое будет использоваться в случае, если для данного параметра не будет предоставлено явное значение при вызове метода.
Это позволит использовать параметр «API ключ» при вызове веб-сервиса и передавать его значение в запросе для аутентификации или иных целей, связанных с доступом к сервису.
Рисунок 12 — Настройка ручных параметров запроса
Конфигурация параметров ответа
Ответ в формате JSON представляет собой структурированные данные, возвращаемые REST-сервисом в ответ на запрос. JSON (JavaScript Object Notation) является универсальным форматом обмена данными, основанным на синтаксисе JavaScript.
Когда запрос отправляется к REST-сервису, он обрабатывает запрос и возвращает данные в формате JSON. Ответ может содержать различные типы данных, такие как строки, числа, массивы и объекты. Формат JSON облегчает чтение и обработку данных, поскольку он представлен в виде иерархической структуры, состоящей из ключей и соответствующих значений.
Автоматический режим
Для настройки параметров ответа в формате JSON:
- Нажмите кнопку «Быстрая настройка».
- В блоке меню «По примеру ответа» выберите «Пример в формате JSON».
- Введите JSON-код ответа сервера.
- Нажмите кнопку «Далее».
После этого откроется список параметров, которые могут быть добавлены в ответ.
Рисунок 13 — Конфигурация параметров ответа
Выберите необходимые параметры и нажмите кнопку «Сохранить». Настройка тела ответа позволяет BPMSoft правильно обработать полученные данные и использовать их в различных бизнес-задачах. Обратитесь к документации или спецификации API REST-сервиса для получения более подробной информации о структуре и формате тела ответа, чтобы настроить его соответствующим образом в BPMSoft.
Ручной режим
Для добавления параметров обработки ответа выполните следующие действия:
- На вкладке «Обработка ответа» нажмите кнопку «Добавить параметр».
- Добавьте параметр «Базовая валюта» с указанными свойствами:
- Название — «USD/RUB»;
- Тип параметра — «Параметр тела»;
- Путь к элементу (JSONPath) — «$.quotes.USDRUB»;
- Код в BPMSoft — «UsrBaseCurrency»;
- Тип данных — «Дробное число»;
- Является массивом — по умолчанию признак снят;
- Формат передачи пустых значений — «По умолчанию»
- Значение по умолчанию — «Константа».
Рисунок 14 — Конфигурация параметров ответа вручную
Тестовый запрос
Чтобы проверить настройку интеграции с REST-сервисом, выполните следующие действия:
- Откройте страницу созданного веб-сервиса.
- На странице методов настройки интеграции с веб-сервисом откройте метод «Получить курсы обмена».
- На странице настройки метода нажмите «Отправить тестовый запрос».
- Задайте значения параметров вызова метода:
- API ключ — 5g****************************41.
- Нажмите на кнопку «Отправить запрос».
После выполнения запроса веб-сервис предоставит ответ, а значения параметров ответа будут отображены на вкладке «Параметры ответа». На других вкладках можно ознакомиться с запросом и ответом в форматах JSON и HTTP (raw).
Рисунок 15 — Пример ответа запроса
