Привет, Хабр!
С вами снова Илья Вязников, инженер сопровождения СОФРОС. Продолжаю делится практическими приёмами и полезными настройками платформы.
При интеграции с REST API часто возникает ситуация, когда идентификатор объекта нужно передавать не в теле запроса и не в query-параметрах, а непосредственно в URL.
Например:
PATCH /users/12345
или
PUT /documents/987/status
Такой подход используется во многих CRM, ECM-системах, банковских и государственных API.
Сегодня, разберём, как реализовать подобную интеграцию в DATAREON Platform с помощью шаблона пути и параметров обработчика.
Когда это может понадобиться
Несколько типичных сценариев:
Обновление контакта во внешней CRM по адресу /api/contacts/{id};
Изменение статуса документа по адресу /documents/{docId}/status;
Интеграция с внешними REST API, структура которых строго определена поставщиком.
Во всех этих случаях путь запроса должен формироваться динамически на основе данных сообщения.
Как это работает в DATAREON Platform
Рассмотрим реальный пример: обработчик, который отправляет обновления пользователя во внешнюю систему.
Шаг 1. Шаблон пути
Создадим обработчик типа «Веб-клиент».
В настройках обработчика (вкладка Основные) в поле Шаблон пути указываем:
/endpoint/v1/users/{id}Здесь {id} — параметр, значение которого будет подставлено при выполнении обработчика.
Название параметра должно совпадать с именем параметра обработчика. Регистр символов также имеет значение. (можно использовать userId, externalId, documentNumber и т.д.).
Шаг 2. Объявление параметра
Переходим на вкладку Параметры обработчика и добавляем параметр:
Наименование: id
Тип: int (или string, в зависимости от внешней системы)
Если параметр используется в шаблоне пути веб-обработчика расширенного REST API, необходимо пометить его как обязательный. При отсутствии значения платформа не сможет корректно сформировать URL и вернет ошибку.
После этого параметр станет доступен в коде обработчика и при вызове из бизнес-процесса.
Шаг 3. Присвоение значения параметру
Здесь есть два удобных варианта.
Вариант А - из типа данных.
Если идентификатор уже присутствует в сообщении, можно присвоить его в коде обработчика:
На вкладке Код обработчика пишем простое присвоение:
id = Ваш_Тип_Данных.id; // или externalId, userId и т.д.В результате при выполнении обработчика значение будет подставлено в URL.
Вариант Б - напрямую из бизнес-процесса
Если нужного поля нет в типе данных или значение формируется динамически на этапе процесса, его можно передать в локальную переменную обработчика при вызове шага отправки из бизнес-процесса.
Для примера покажу передачу id из InitMessage:
В блоке Отправка указываем обработчик, в котором создана переменная id.
Открываем локальные переменные обработчика.
Связываем поле id из контекста процесса (InitMessage.id, переменная процесса и т.д.). с переменной обработчика, для передачи значения из процесса в обработчик.
Таким образом, платформа подставит значение в плейсхолдер при формировании запроса.
Например:
Шаблон:
/endpoint/v1/users/{id}
Значение параметра:
id = 12345
Итоговый запрос:
/endpoint/v1/users/12345
Что происходит во время выполнения
При запуске обработчика DATAREON Platform:
Берёт шаблон пути.
Получает значения параметров обработчика.
Подставляет их в шаблон URL.
Формирует итоговый адрес запроса.
Выполняет HTTP-вызов внешней системы.
Практические советы
Используйте понятные имена параметров:
/users/{userId}
/orders/{orderId}
/documents/{documentGuid}
Если идентификатор представляет собой UUID или строковый код, используйте тип String.
В одном URL можно использовать несколько параметров: /api/v1/orders/{orderId}/positions/{positionId}
После настройки рекомендуется проверить сформированный URL в журнале выполнения обработчика и убедиться, что все параметры подставляются корректно.
Итог
Шаблон пути в DATAREON Platform позволяет формировать URL динамически и передавать в него значения из сообщений или бизнес-процессов.
Это упрощает интеграцию с REST API, где идентификаторы объектов являются частью адреса запроса, и избавляет от необходимости создавать дополнительные преобразования данных только ради формирования URL.