Динамические шаблоны пути в интеграциях: как передавать пользовательские данные в URL через DATAREON Platform

Привет, Хабр!

С вами снова Илья Вязников, инженер сопровождения СОФРОС. Продолжаю делится практическими приёмами и полезными настройками платформы.

При интеграции с 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:

1. Берёт шаблон пути.

2. Получает значения параметров обработчика.

3. Подставляет их в шаблон URL.

4. Формирует итоговый адрес запроса.

5. Выполняет HTTP-вызов внешней системы.

Практические советы

• Используйте понятные имена параметров:

  • /users/{userId}

  • /orders/{orderId}

  • /documents/{documentGuid}

• Если идентификатор представляет собой UUID или строковый код, используйте тип String.

• В одном URL можно использовать несколько параметров: /api/v1/orders/{orderId}/positions/{positionId}

• После настройки рекомендуется проверить сформированный URL в журнале выполнения обработчика и убедиться, что все параметры подставляются корректно.

Итог

Шаблон пути в DATAREON Platform позволяет формировать URL динамически и передавать в него значения из сообщений или бизнес-процессов.

Это упрощает интеграцию с REST API, где идентификаторы объектов являются частью адреса запроса, и избавляет от необходимости создавать дополнительные преобразования данных только ради формирования URL.