Настройка HTTP адаптера

Обзор

HTTP/TCP адаптер для Accelera Flows – модуль для приема HTTP/TCP запросов, трансформации данных через шаблоны Handlebars и публикации событий в RabbitMQ.

Основные возможности

Прием HTTP POST-запросов на эндпоинты /event, / и /batch
Опциональный TCP-сервер для приема JSON-данных
Извлечение данных из входящих сообщений через шаблоны Handlebars
Авторизация по токену
Публикация событий в RabbitMQ с автоматическим переподключением
Батчевая отправка событий

Формат входящих данных

JSON-формат, пример:

{
  "TRANSACTION_DATE": "21-01-2021 11:36:30",
  "ACCOUNT_NUMBER": "123456789",
  "MERCHANT_CITY": "London",
  "MERCHANT_COUNTRY": "UK",
  "MERCHANT_CATEGORY": "5699",
  "TRANSACTION_ID": "123456789",
  "NAME": "John",
  "ID": "100200"
}

Примеры запросов

Отправка события:

curl -X POST "http://127.0.0.1:8000/event" \
     -H "Content-Type: application/json" \
     -H "Authorization: your_token_here" \
     -d '{
       "TRANSACTION_ID": "123456789",
       "ACCOUNT_NUMBER": "123456789",
       "NAME": "John"
     }'

Проверка доступности:

curl http://127.0.0.1:8000/ping
# Ответ: PONG

Батчевая отправка:

curl -X POST "http://127.0.0.1:8000/batch" \
     -H "Content-Type: application/json" \
     -H "Authorization: your_token_here" \
     -d '{
       "count": 10,
       "event": "transaction",
       "flow": "flow_id",
       "context": {"key": "value"}
     }'

Конфигурация

Установка образа

Распакуйте образ приложения из файла:

docker load < flows_http_adapter_{version}.tar.gz

Проверьте загруженный образ:

docker images | grep flows_http_adapter

Docker Compose конфигурация

Создайте файл docker-compose.yaml:

version: '3'

services:
  http_adapter:
    image: flows_http_adapter:2.0.0
    container_name: http_adapter
    network_mode: "host"
    restart: unless-stopped
    environment:
      # Обязательные параметры
      - BROKER_CONNECTION=amqp://username:password@127.0.0.1:5672
      - ID={{TRANSACTION_ID}}
      - EVENT=transaction_event

      # Опциональные параметры
      - PORT=8000
      - LOG_LEVEL=info
      - TOKEN=your_secret_token
      - REDIS_CONNECTION=redis://127.0.0.1:6379

      # Настройка извлечения данных
      - FLOW_ID={{flow}}
      - CONTEXT=accountNumber,{{ACCOUNT_NUMBER}},name,{{NAME}}

      # TCP адаптер (опционально)
      - ENABLE_TCP_ADAPTER=false
      - HOST=127.0.0.1
      - TCP_PORT=9100

Если используете network_mode: bridge:

services:
  http_adapter:
    # ...
    network_mode: "bridge"
    ports:
      - "8000:8000"      # HTTP порт
      - "9100:9100"      # TCP порт (если включен)

Описание переменных окружения

Обязательные параметры

Параметр	Описание	Пример
`BROKER_CONNECTION`	URL подключения к RabbitMQ (можно несколько через запятую)	`amqp://user:pass@host:5672`
`ID`	Шаблон для извлечения ID события	`{{TRANSACTION_ID}}` или `@TRANSACTION_ID`
`EVENT`	Шаблон для извлечения имени события	`transaction_event` или `{{event_type}}`

Опциональные параметры

Параметр	Описание	По умолчанию
`PORT`	Порт HTTP-сервера	`8000`
`LOG_LEVEL`	Уровень логирования (trace, debug, info, warn, error)	`info`
`TOKEN`	Токен для авторизации запросов (передается в заголовке `Authorization`)	не установлен
`REDIS_CONNECTION`	Строка подключения к Redis	не используется
`FLOW_ID`	Шаблон для извлечения идентификатора потока	не установлен
`CONTEXT`	Шаблон для извлечения контекста (см. раздел о контексте)	`{}`

TCP адаптер

Параметр	Описание	По умолчанию
`ENABLE_TCP_ADAPTER`	Включить TCP-сервер	`false`
`HOST`	Хост TCP-сервера	`127.0.0.1`
`TCP_PORT`	Порт TCP-сервера	`9100`

Работа с шаблонами

Адаптер поддерживает два способа извлечения данных:

1. Прямой доступ к полю (префикс **@**):

ID=@TRANSACTION_ID
# Вернет значение поля TRANSACTION_ID напрямую

2. Handlebars шаблоны:

ID={{TRANSACTION_ID}}
EVENT={{eventType}}
# Использует шаблонизатор Handlebars

Примеры использования Handlebars хелперов:

# Преобразование регистра
EVENT={{toLowerCase eventType}}

# Обрезка строки
ID={{substring TRANSACTION_ID 0 10}}

# Замена символов
EVENT={{replace eventType "-" "_"}}

# Работа с датами
CONTEXT=date,{{parseDt TRANSACTION_DATE "DD-MM-YYYY HH:mm:ss" "YYYY-MM-DD"}}

# Математические операции (для массивов)
CONTEXT=average,{{mathAvg values}}

# Разбиение строки на массив
CONTEXT=items,{{toArray itemList ","}}

Настройка контекста (CONTEXT)

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

Вариант 1: Передать все данные как есть

CONTEXT=*

Вариант 2: Маппинг полей (формат: ключ1,значение1,ключ2,значение2)

CONTEXT=accountNumber,{{ACCOUNT_NUMBER}},merchantCity,{{MERCHANT_CITY}},amount,{{AMOUNT}}

Результат будет:

{
  "accountNumber": "123456789",
  "merchantCity": "London",
  "amount": "100.50"
}

Вариант 3: Пустой контекст (по умолчанию)

CONTEXT=
# Результат: {}

Настройка авторизации

Если установлена переменная TOKEN, все запросы к эндпоинтам /event, / и /batch должны содержать заголовок Authorization:

curl -X POST "http://127.0.0.1:8000/event" \
     -H "Authorization: your_secret_token" \
     -H "Content-Type: application/json" \
     -d '{"TRANSACTION_ID": "123"}'

Эндпоинт /ping доступен без авторизации.

Запуск и управление

Запуск адаптера

docker-compose up -d

Или с указанием пути к файлу:

docker-compose -f /path/to/docker-compose.yaml up -d

Просмотр логов

docker logs -f http_adapter

При успешном запуске вы увидите:

HTTP API listening on port 8000

Connection to broker established successfully

Broker event channel created successfully

Остановка адаптера

docker-compose down

Перезапуск

docker-compose restart

Проверка статуса

docker ps | grep http_adapter

Использование TCP адаптера

Включите TCP-сервер в docker-compose.yaml:

environment:
  - ENABLE_TCP_ADAPTER=true
  - HOST=0.0.0.0
  - TCP_PORT=9100

Отправьте JSON через TCP:

echo '{"TRANSACTION_ID":"123","NAME":"John"}' | nc localhost 9100

TCP-сервер использует те же шаблоны извлечения данных (ID, EVENT, CONTEXT), что и HTTP-сервер.

Мониторинг и отладка

Уровни логирования

trace – максимально подробные логи
debug – детальная информация о обработке запросов
info – основные события (запуск, подключения)
warn – предупреждения
error – только ошибки

Статистика событий

Каждые 30 секунд адаптер выводит статистику:

[Adapter events statistic] received: 1250 | sent: 1250

Проверка работоспособности

Проверка HTTP-сервера:

curl http://localhost:8000/ping

Проверка логов подключения к RabbitMQ:

docker logs http_adapter | grep broker

Отправка тестового события:

curl -X POST "http://localhost:8000/event" \
     -H "Content-Type: application/json" \
     -d '{"test":"data"}'

Примеры конфигураций

Минимальная конфигурация

environment:
  - BROKER_CONNECTION=amqp://guest:guest@rabbitmq:5672
  - ID={{id}}
  - EVENT=test_event

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

environment:
  - BROKER_CONNECTION=amqp://user:pass@rabbitmq:5672
  - ID={{TRANSACTION_ID}}
  - EVENT=transaction
  - TOKEN=secret_token_12345
  - LOG_LEVEL=info

Конфигурация с полным маппингом

environment:
  - BROKER_CONNECTION=amqp://user:pass@rabbitmq:5672
  - ID={{TRANSACTION_ID}}
  - EVENT={{toLowerCase eventType}}
  - FLOW_ID={{flow_identifier}}
  - CONTEXT=transactionDate,{{parseDt TRANSACTION_DATE "DD-MM-YYYY HH:mm:ss" "YYYY-MM-DD"}},account,{{ACCOUNT_NUMBER}},merchant,{{MERCHANT_CITY}},category,{{MERCHANT_CATEGORY}}
  - TOKEN=secret_token
  - LOG_LEVEL=debug

Конфигурация с TCP

environment:
  - BROKER_CONNECTION=amqp://user:pass@rabbitmq:5672
  - ID={{id}}
  - EVENT=tcp_event
  - ENABLE_TCP_ADAPTER=true
  - HOST=0.0.0.0
  - TCP_PORT=9100
  - PORT=8000

HTTP API

Сервер по умолчанию запускается на порту 8000 (настраивается через переменную PORT).

Авторизация

Если задана переменная окружения TOKEN, все защищённые эндпоинты требуют заголовок:
Authorization:

Ответ при неверном токене:

Код: 401
Тело: Unauthorized

POST /event

Основной эндпоинт для отправки событий в RabbitMQ.

Требует авторизации: Да (если настроен TOKEN)

Тело запроса: JSON-объект с данными события. Поля извлекаются согласно шаблонам ID, EVENT, FLOW_ID, CONTEXT.

Успешный ответ:

Код: 200
Тело: Received

Ошибка валидации:

Код: 400
Тело:

{"status": false, "error": "<причина>"}

Возможные ошибки:

Id required — не удалось извлечь ID
Event required — не удалось извлечь имя события
Context must be object — контекст не является объектом

POST /

Альтернативный эндпоинт, идентичен /event.

GET /ping

Проверка работоспособности сервера.

Требует авторизации: Нет

Ответ:

Код: 200
Тело: PONG

POST /ping

Проверка работоспособности с логированием тела запроса.

Требует авторизации: Нет

Тело запроса: Любой JSON (опционально)

Ответ:

Код: 200
Тело: PONG

Устранение проблем

Адаптер не запускается

Проверьте логи: docker logs http_adapter
Убедитесь, что порт не занят: netstat -tuln | grep 8000
Проверьте подключение к RabbitMQ

Ошибка подключения к RabbitMQ

Connection to broker error

Решение:

Проверьте доступность RabbitMQ: telnet rabbitmq_host 5672
Проверьте учетные данные в BROKER_CONNECTION
Убедитесь, что сеть настроена правильно

Событие не публикуется

Проверьте:

Логи на уровне debug: LOG_LEVEL=debug
Валидность шаблонов ID, EVENT, CONTEXT
Формат входящего JSON

Ошибка авторизации (401 Unauthorized)

Убедитесь, что заголовок Authorization совпадает со значением TOKEN в конфигурации.

TCP соединение отклоняется

Проверьте, что ENABLE_TCP_ADAPTER=true
Проверьте доступность порта: netstat -tuln | grep 9100
Убедитесь, что HOST=0.0.0.0 для внешних подключений

Настройка HTTP адаптера

На этой странице