Настройка интеграции с веб-сервисами

Интеграция REST и SOAP сервисов позволяет объединить функциональность и данные, предоставляемые различными сервисами, и использовать их вместе в одном приложении или системе.

После успешной интеграции с веб-сервисом предоставляется широкий спектр возможностей для эффективного использования полученных данных в различных бизнес-процессах. Вот несколько примеров применения:

1. Создание и обновление записей: можно использовать полученные данные для автоматического создания новых записей или обновления существующих записей. Например, если веб-сервис предоставляет информацию о клиентах, вы можете автоматически создавать профили клиентов на основе этих данных.
2. Бизнес-логика: полученные данные могут быть использованы для выполнения различных операций. Например, если веб-сервис предоставляет информацию о товарах, вы можете использовать эти данные для расчета цен, скидок или доступности товаров.
3. Автоматизация процессов: данные, полученные от веб-сервиса, могут быть интегрированы в автоматизированные процессы. Например, если веб-сервис предоставляет информацию о доставке, вы можете автоматически отслеживать статус доставки и информировать клиентов о ее прогрессе.

Алгоритм настройки

Интеграция пользовательских веб-сервисов в системе осуществляется с помощью инструментов low-code, что значительно упрощает настройку и использование.

Настройка интеграций с веб-сервисами выполняется в разделе «Веб-сервисы», в который можно перейти несколькими способами:

• Дизайнер системы  → блок «Импорт и интеграции» → раздел «Настройка интеграции с веб-сервисами»;
• Рабочее место «Конструктор» → раздел «Веб-сервисы».

Общая процедура настройки интеграции с веб-сервисом включает следующие шаги:

1. Создание веб-сервиса и настройка методов и свойств:
   • В разделе «Веб-сервисы» можно добавить веб-сервис и указать его свойства, такие как URL-адрес, имя, описание и другие параметры;
   • Для REST-сервисов можно настроить методы запросов (GET, POST, PUT, DELETE) и указать соответствующие URL-пути, параметры запроса, заголовки и тело запроса;
   • Для SOAP-сервисов можно добавить WSDL-описание сервиса и автоматически сгенерировать соответствующие методы и параметры.
2. Если веб-сервис требует аутентификации, можно настроить соответствующие параметры, такие как тип аутентификации, логин, пароль, токены и другие данные, необходимые для успешного подключения к сервису.
3. Проверка интеграции с веб-сервисом:
• После настройки можно выполнить проверку интеграции, которая позволяет убедиться, что система успешно подключается к веб-сервису и может получать ответы от него;
• В процессе проверки можно указать тестовые данные запроса для получения ответа от веб-сервиса.

Интеграция SOAP веб-сервиса

Пример. Настроим интеграцию с сервисом «http://www.dneonline.com/calculator.asmx», чтобы автоматически возвращать баланс пользователя текущей сессии и отправлять сообщения адресатам. Обратите внимание, что конкретные детали настройки могут различаться в зависимости от особенностей конкретного SOAP-сервиса и его документации.

Автоматическая конфигурация веб-сервиса

В BPMSoft есть возможность автоматической настройки интеграции с SOAP-сервисом.

WSDL-файл содержит информацию о доступных методах, их параметрах, типах данных и другие детали. Импортирование WSDL-файла в систему позволяет автоматически создать соответствующий сервис в разделе «Веб-сервисы».

Для настройки интеграции:

1. В разделе «Веб-сервисы» нажмите на кнопку «Добавить веб-сервис» и выберите опцию «SOAP сервис».
2. В открывшемся окне «Быстрая настройка SOAP веб-сервиса» выберите файл, нажав на кнопку «Выбрать файл», или укажите ссылку на WSDL-файл, содержащий информацию о структуре сервиса.

Ссылка на WSDL-файл
http://www.dneonline.com/calculator.asmx?WSDL

Рисунок 1 — Окно быстрой настройки

3. После загрузки WSDL-файла или ввода ссылки система перейдет к окну настройки SOAP сервиса. Здесь вы можете выбрать сервис и установить версию SOAP, которые хотите использовать. Также вы можете настроить методы и параметры. Когда настройка будет завершена, нажмите кнопку «Далее».

Рисунок 2 — Окно настройки

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

Рисунок 3 — Выбор значений ответов метода

5. После того как все настройки будут выполнены, нажмите кнопку «Сохранить».

Конфигурация веб-сервиса вручную

При ручной настройке сервиса после пропуска быстрой настройки и изучения документации вам необходимо заполнить поля на странице свойств веб-сервиса. Для этого:

1. Перейдите в раздел «Веб-сервисы».
2. Нажмите «Добавить веб-сервис» и выберите «SOAP сервис».
3. В открывшемся окне «Быстрая настройка SOAP веб-сервиса» нажмите «Пропустить быструю настройку».

Рисунок 4 — Пропуск быстрой настройки SOAP веб-сервиса

4. Изучите документацию веб-сервиса, она должна содержать XML-код.
5. Заполните остальные поля на странице свойств веб-сервиса в соответствии с документацией и требованиями веб-сервиса.
6. Нажмите «Сохранить» для сохранения настроек свойств веб-сервиса.

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

• Название — «Калькулятор»;
• Код в BPMSoft — «BpmCalculatorService»;
• Пространства имен — «http://tempuri.org/»;

Примечание. Необходимо указывать только те пространства, которые используются для методов и их параметров веб-сервиса. Формат задания набора пространств имен следующий: «Префикс пространства имен»:«Пространство имен». Например, если у вас есть два пространства имен: «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 сервиса — «http://www.dneonline.com/calculator.asmx»;

Примечание. Необходимо указать полный адрес вызова веб-сервиса. Этот адрес будет состоять из указанного URI и настроек, указанных на странице настройки метода.

• Повторы вызова при ошибках — по умолчанию «0»;
• Пакет — выберите пакет, в котором хотите сохранить данную интеграцию с веб-сервисом. В списке отображаются доступные для изменения текущим пользователем пакеты.

Рисунок 5 — Страница настройки SOAP-сервиса

Конфигурирование вызова метода

Для настройки метода сервиса:

1. Перейдите на страницу свойств сервиса в разделе «Веб-сервисы».
2. На странице интеграции найдите раздел «Методы», добавьте новый метод.
3. Изучите документацию сервиса и найдите информацию о методе, который вы хотите вызвать. В текущем примере приведен элемент Add.

<s:element name="Add">
	<s:complexType>
		<s:sequence>
			<s:element minOccurs="1" maxOccurs="1" name="intA" type="s:int"/>
			<s:element minOccurs="1" maxOccurs="1" name="intB" type="s:int"/>
		</s:sequence>
	</s:complexType>
</s:element>

4. Заполните свойства, пространство имен и другие параметры, указанные в документации веб-сервиса.

Для настройки вызова метода сервиса заполните следующие поля:

• Название — «Сложение»;
• Код в BPMSoft — «BpmAdd»;
• Код элемента сообщения — «Add»;
• SOAP Action — «http://tempuri.org/Add»;
• Тайм-аут ответа, мс — значение по умолчанию «5000»;
• Использовать аутентификацию — по умолчанию признак снят.

Рисунок 6 — Пример настройки вызова метода

Конфигурирование параметров запроса

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

1. Параметр тела: позволяет отправлять любые типы данных, включая коллекции.
2. Параметр заголовка: заголовки запроса используются для передачи метаданных и дополнительной информации.
3. Параметр cookies: файлы cookie могут использоваться для аутентификации или сохранения состояния.

Выберите соответствующий тип параметра в зависимости от ваших потребностей и документации веб-сервиса. Затем добавьте параметры запроса, указав имя, тип и описание каждого параметра.

При заполнении параметров запроса учитывайте, что поле «Формат передачи пустых значений» определяет каким образом передается пустое значение параметра. Возможны следующие варианты значений:

• По умолчанию: передается стандартное значение по умолчанию для выбранного типа данных. Например, для логического типа передается false, а для строкового — пустая строка ("");
• Не передавать: если параметр пуст, он не включается в передачу;
• Пустая строка: передается пустая строка ("");
• NULL: пустое значение параметра передается как NULL.

Для добавления параметров к запросу «Сложение» сервиса выполните следующие шаги:

1. На вкладке «Параметры вызова» нажмите кнопку «Добавить параметр».
2. Заполните свойства параметра «Первое слагаемое» следующим образом:
   • Название — «Первое слагаемое»;
   • Тип параметра — «Параметр тела»;
   • Путь к элементу — «tem:intA»;
   • Код в BPMSoft — «intA»;
   • Тип данных — «Целое число»;
   • Является массивом — по умолчанию признак снят;
   • Обязательный — по умолчанию признак установлен;
   • Формат передачи пустых значений — «По умолчанию»;
   • Значение по умолчанию — «Константа».

3. Нажмите «ОК».
4. На вкладке «Параметры вызова» нажмите кнопку «Добавить параметр».
5. Заполните свойства параметра «Второе слагаемое» следующим образом:
   • Название — «Второе слагаемое»;
   • Тип параметра — «Параметр тела»;
   • Путь к элементу— «tem:intB»;
   • Код в BPMSoft — «intB»;
   • Тип данных — «Целое число»;
   • Является массивом — по умолчанию признак снят;
   • Обязательный — по умолчанию признак установлен;
   • Формат передачи пустых значений — «По умолчанию»;
   • Значение по умолчанию — «Константа».

6. Нажмите «ОК».

Рисунок 7 — Пример настройки параметров метода

Конфигурирование параметров ответа

Чтобы добавить параметр обработки ответа «Сложение» для веб-сервиса, выполните следующие шаги:

1. В документации веб-сервиса определите формат ответа.

<s:element name="AddResponse">
	<s:complexType>
		<s:sequence>
			<s:element minOccurs="1" maxOccurs="1" name="AddResult" type="s:int"/>
		</s:sequence>
	</s:complexType>
</s:element>

2. Перейдите на вкладку «Обработка ответа».
3. Нажмите кнопку «Добавить параметр».
4. Заполните свойства параметра «Результат сложения» следующим образом:
   • Название — «Результат сложения»;
   • Тип параметра — «Параметр тела»;
   • Путь к элементу — «tem:AddResult»;
   • Код в BPMSoft — «AddResult»;
   • Тип данных — «Целое число»;
   • Является массивом — по умолчанию признак снят;
   • Значение по умолчанию — «Константа».
5. Нажмите «ОК».

Рисунок 8 — Пример настройки параметров ответа

Тестовый запрос

Чтобы проверить настройку интеграции с SOAP-сервисом и получить его ответ в интерфейсе приложения, выполните следующие действия:

1. Перейдите в раздел «Веб-сервисы».
2. Откройте страницу веб-сервиса, с которым вы хотите проверить интеграцию, например, «Калькулятор».
3. На странице с деталями методов настройки интеграции откройте метод «Сложение».
4. На странице настройки метода нажмите кнопку «Отправить тестовый запрос».
5. Задайте значения параметров вызова метода.
6. Нажмите кнопку «Отправить тестовый запрос».
7. После выполнения тестового запроса вы получите ответ от веб-сервиса. Значения параметров ответа будут отображены на вкладке «Параметры ответа» в соответствующих полях. Другие вкладки позволяют просмотреть запрос и ответ на запрос в форматах XML и HTTP (raw).

Интеграция REST веб-сервиса

Пример. Настроим интеграцию с сервисом «country.is», который помогает определить страну, к которой относится IP-адрес.

Добавление веб-сервиса

Для добавления REST-сервиса в систему выполните следующие шаги:

1. Перейдите в раздел «Веб-сервисы».
2. Нажмите «Добавить веб-сервис» и выберите «REST сервис».
3. Введите адрес сервера, предоставляющего REST API. Это значение будет помещено в настройку URI сервиса;

Пример заполнения значений свойств веб-сервиса:
Адрес сервиса — «https://api.country.is»;

Примечание. Необходимо указать полный адрес вызова веб-сервиса. Этот адрес будет состоять из указанного адреса сервиса и настроек, указанных на странице настройки метода.

1. Заполните свойства веб-сервиса:
   • Название — значение, которое будет отображаться в поле «Какой сервис вызывать?» в элементе процесса «Вызвать веб-сервис»;
   • Код — укажите уникальное имя, которое используется разработчиками;
   • URI сервиса — представляет собой уникальный идентификатор ресурса в REST-сервисе. Он включает протокол (например, HTTP или HTTPS), доменное имя или IP-адрес сервера, порт (если отличается от стандартного) и путь к конкретному ресурсу или методу;
   • Повторов вызова при ошибках — определяет количество попыток повторного выполнения запроса к REST-сервису в случае возникновения ошибки или неудачного ответа;
   • Тип — выберите тип веб-сервиса. Значение по умолчанию — «REST»;
   • Пакет — пакет конфигурации BPMSoft, в котором хранится веб-сервис. Для новых веб-сервисов вы можете выбрать пользовательский пакет, доступный для изменения.

Пример заполнения значений свойств веб-сервиса:

• Название — Определение страны по IP;
• Код — BpmCountryByIpService;
• URI сервиса — https://api.country.is;
• Повторов вызова при ошибках — 0;
• Тип —REST;
• Пакет — текущий пакет.

5. После заполнения всех полей нажмите «Сохранить», чтобы добавить REST-сервис и перейти к настройке его методов и аутентификации.

Рисунок 9 — Страница настройки REST-сервиса

Настройка методов веб-сервиса

Для настройки методов веб-сервиса выполните следующие действия:

1. На странице сервиса перейдите на вкладку «Методы».  Нажмите «+» для добавления нового метода.
2. Заполните свойства метода:
   • Название — укажите название метода, которое будет отображаться в поле «Какой сервис вызывать» в области свойств элемента процесса «Вызвать веб-сервис»;
   • Код — укажите уникальное имя, которое используется разработчиками;
   • Адрес метода — указывает на конкретный ресурс или функциональность, доступную через этот метод. Адрес метода обычно состоит из базового URL-адреса сервиса, дополненного путем или параметрами, которые идентифицируют конкретный ресурс или операцию;
   • Полный адрес — представляет собой конкретный URL-адрес, который составляется путем объединения базового URI-адреса сервиса и адреса метода с указанием всех необходимых параметров запроса;
   • Тип запроса — тип запроса указывает на метод HTTP, который будет использоваться при выполнении запроса к REST-сервису;
   • Тайм-аут ответа, мс — определяет максимальное время ожидания ответа от REST-сервиса после отправки запроса. Важно подобрать оптимальное значение тайм-аута. Если значение слишком маленькое, запрос может быть прерван, не дожидаясь ответа. С другой стороны, слишком большое значение тайм-аута может вызывать задержки в обработке запросов, особенно если REST-сервис не отвечает;
   • Использовать аутентификацию — флаг, используется ли аутентификация.

Пример заполнения значений свойств метода:

• Название — Получение страны IP;
• Код — BpmGetCountryByIP;
• Адрес метода — /{ip};
• Полный адрес — https://api.country.is/{ip};

Примечание. Поле «Полный адрес» заполнится автоматически после ввода адреса метода.

• Тип запроса — GET;
• Тайм-аут ответа, мс — 5000;
• Использовать аутентификацию — Нет.

Рисунок 10 — Методы REST-сервиса

Конфигурация параметров запроса

Параметры запроса представляют собой значения, передаваемые вместе с запросом к REST-сервису. Они используются для настройки запроса и передачи дополнительной информации, которая может влиять на обработку и результаты запроса.

Автоматический режим

Чтобы добавить параметры из поля «Адрес метода»:

1. Нажмите кнопку «Быстрая настройка», расположенную в верхней части окна добавления метода.
2. В выпадающем списке выберите «По полю «Адрес метода» или нажмите на кнопку  в поле «Адрес метода».
3. В открывшемся списке выберите необходимые параметры и нажмите кнопку «Сохранить».

Рисунок 11 — Параметры запроса

Параметры будут добавлены в запрос, их можно использовать на шаге бизнес-процесса «Вызвать веб-сервис». Вы можете изменять параметры, например, установить признак «Обязательный» для параметра.

Ручной режим

На вкладке «Параметры вызова» нажмите кнопку «Добавить параметр» и добавьте новый параметр с названием «IP адрес». Заполните свойства параметра следующим образом:

• Название — «IP адрес»;
• Тип параметра — «Параметр запроса»;
• Код в запросе — «ip»;
• Код в BPMSoft — «BpmIP»;
• Обязательный — относится к параметру метода REST-сервиса и указывает, является ли этот параметр обязательным при вызове метода;
• Формат передачи пустых значений – определяет каким образом передается пустое значение параметра. Возможны следующие варианты значений:
  • По умолчанию: передается стандартное значение по умолчанию для выбранного типа данных. Например, для логического типа передается false, а для строкового — пустая строка ("");
  • Не передавать: если параметр пуст, он не включается в передачу;
  • Пустая строка: передается пустая строка ("");
  • NULL: пустое значение параметра передается как NULL.
• Значение по умолчанию — относится к параметру метода REST-сервиса и предоставляет значение, которое будет использоваться в случае, если для данного параметра не будет предоставлено явное значение при вызове метода.

Это позволит использовать параметр «Широта» при вызове веб-сервиса и передавать его значение в запросе для аутентификации или иных целей, связанных с доступом к сервису.

Рисунок 12 — Настройка ручных параметров запроса

Конфигурация параметров ответа

Ответ в формате JSON представляет собой структурированные данные, возвращаемые REST-сервисом в ответ на запрос. JSON (JavaScript Object Notation) является универсальным форматом обмена данными, основанным на синтаксисе JavaScript.

Когда запрос отправляется к REST-сервису, он обрабатывает запрос и возвращает данные в формате JSON. Ответ может содержать различные типы данных, такие как строки, числа, массивы и объекты. Формат JSON облегчает чтение и обработку данных, поскольку он представлен в виде иерархической структуры, состоящей из ключей и соответствующих значений.

Автоматический режим

Для конфигурации параметров ответа в формате JSON:

1. Нажмите на кнопку «Быстрая настройка».
2. В блоке «По примеру ответа» выберите пункт «Пример в формате JSON».
3. Введите JSON-код ответа сервера. Например:

Пример в формате JSON
{"ip":"5.255.255.242","country":"RU"}

4. Нажмите на кнопку «Далее».

После этого откроется список параметров, которые могут быть добавлены в ответ.

Рисунок 13 — Конфигурация параметров ответа

Выберите необходимые параметры и нажмите кнопку «Сохранить». Настройка тела ответа позволяет BPMSoft правильно обработать полученные данные и использовать их в различных бизнес-задачах. Обратитесь к документации или спецификации API REST-сервиса для получения подробной информации о структуре и формате тела ответа, чтобы настроить его соответствующим образом в BPMSoft.

Ручной режим

Для добавления параметров обработки ответа выполните следующие действия:

1. На вкладке «Обработка ответа» нажмите кнопку «Добавить параметр».
2. Добавьте параметр «Код страны» с указанными свойствами:
   • Название — «Код страны»;
   • Тип параметра — «Параметр тела»;
   • Путь к элементу (JSONPath) — « $.country »;
   • Код в BPMSoft — «BpmCountryCode»;
   • Тип данных — «Текст»;
   • Является массивом — по умолчанию признак снят;
   • Значение по умолчанию — «Константа».

Рисунок 14 — Конфигурация параметров ответа вручную

Тестовый запрос

Для проверки корректности настройки интеграции с REST-сервисом, выполните следующие действия:

1. Откройте страницу созданного веб-сервиса.
2. На странице методов настройки интеграции с веб-сервисом откройте тестируемый метод.
3. На странице настройки метода нажмите на кнопку «Отправить тестовый запрос».
4. Нажмите на кнопку «Отправить запрос».

После выполнения запроса веб-сервис предоставит ответ, а значения параметров ответа будут отображены на вкладке «Параметры ответа». На других вкладках можно ознакомиться с запросом и ответом в форматах JSON и HTTP (raw).

Рисунок 15 — Пример ответа запроса

Рекомендуем изучить

Отслеживание выполнения методов веб-сервиса