Поддержка модуля с версии SoftWLC 1.24 прекращена! Последняя стабильная версия eltex-mcdonalds 1.23-124 |
Сервис Eltex-Mcdonalds предназначен для интеграции платформы с системой клиента в рамках API. Клиент хочет копить у себя данные пользователей, которые прошли авторизацию. Нужно синхронно (online) пересылать информацию о старте и завершении пользовательской сессии портальных гостевых клиентов на внешнюю систему через HTTP Rest (JSON) API.
Функционал используется для целей аналитики и принятия решения в процессе подготовки различных акционных механик, в том числе с помощью моделей машинного обучения.
Термин | Описание |
Eltex-Mcdonalds | Eltex сервис, который умеет отправить данные в формате McD-API. |
McD-API | Стороннее McDonald's API, принимающее запросы по HTTP PUT. |
PCRF | Eltex сервис, который знает об услуге все. Он ничего не знает о существовании Mcdonalds. Его задача здесь - отправить универсальные события в шину данных. |
User session value | Данные о сессии пользователя, которыми оперирует PCRF. |
Шина данных | Сервис, отвечающий за передачу потока сообщений потребителям. В качестве шины выбрана Apache Kafka. |
Базовый URL: https://apicrm.mcdonalds.ru/api/v1-1/wifihs, тип запроса PUT.
Метод | Событие |
---|---|
/session/create | Создание сессии пользователя (ACCT START) |
/session/update |
|
Пример передаваемых данных:
# Старт сессии { "session_id": "720575940379279391", "phone": "79123456789", "mac_address_user": "78:02:f8:fa:8f:f4", "session_start": 1616061507, "session_time": 0, "hotspot_identifier": "A8-F9-4B-AB-2F-00", "event_ts": 1616061507, "personal_data_processing_confirm": true, "ts": 1616061508 } # Cтоп сессии { "session_id": "720575940379279391", "phone": "79123456789", "mac_address_user": "78:02:f8:fa:8f:f4", "session_start": 1616061927, "session_stop": 1616063139, "session_time": 1623, "hotspot_identifier": "A8-F9-4B-AB-2F-00", "event_ts": 1616061927, "personal_data_processing_confirm": true, "ts": 1616063140 } |
Полный список полей:
Ключ | Значение | Тип поля | Обязательный /session/create | Обязательный /session/update | Присутствует |
---|---|---|---|---|---|
phone | Телефон в формате E164 без "+" | string | да | нет | RADIUS User-Name |
session_id | Идентификатор сессии | string | да | да | RADIUS Acct-Session-Id |
personal_data_processing_confirm | Факт согласия на обработку ПД (в SoftWLC это Согласие на получение рекламных материалов) | bool | да | нет | MySQL radstat advertising |
hotspot_identifier | Идентификатор точки | string | да | нет | MAC-адрес RADIUS Called-Station-Id |
session_start | Время начала сессии | int (timestamp в секундах) | да | нет | текущее время |
session_stop | Время завершения сессии | int (timestamp в секундах) | нет | да | текущее время |
session_time | Длительность сессии (сек) | int | нет | да | RADIUS Session-Time (PCRF присылает sessionTime, сами не считаем) |
mac_address_user | Mac-адрес пользователя | string | нет | нет | RADIUS Calling-Station-Id |
event_ts | Дата и время начала сессии | int (timestamp в секундах) | да | да | PCRF sessionStart |
Для работы сервисов необходимо подключить их к непосредственно Kafka.
Kafka можно запустить, используя docker-compose:
version: '2' services: zookeeper: container_name: zookeeper image: 'docker.io/bitnami/zookeeper:3-debian-10' ports: - '2181:2181' volumes: - 'zookeeper_data:/bitnami' environment: - ALLOW_ANONYMOUS_LOGIN=yes - ZOO_MAX_SESSION_TIMEOUT=500000 mem_limit: 512m kafka: container_name: kafka image: 'docker.io/bitnami/kafka:2-debian-10' ports: - '9092:9092' volumes: - 'kafka_data:/bitnami' environment: - KAFKA_CFG_ZOOKEEPER_CONNECT=zookeeper:2181 - ALLOW_PLAINTEXT_LISTENER=yes - KAFKA_CFG_LISTENERS=PLAINTEXT://:9092 - KAFKA_CFG_ADVERTISED_LISTENERS=PLAINTEXT://${KAFKA_HOST}:9092 - KAFKA_LOG_RETENTION_CHECK_INTERVALS_MS=3600000 - KAFKA_CFG_AUTO_CREATE_TOPICS_ENABLE=false - KAFKA_DELETE_TOPIC_ENABLE=true mem_limit: 1g depends_on: - zookeeper volumes: zookeeper_data: driver: local kafka_data: driver: local |
где KAFKA_HOST - это IP адрес машины, на которой развернута Kafka, белый IP, по которому сервис Kafka будет доступен другим приложениям.
Для управления параметрами Kafka можно использовать скипты, которые доступны в контейнере с самим сервисом
docker exec -it ${CONTAINER_ID} bash |
где CONTAINER_ID - это ID для bitnami/kafka:2-debian-10 из команды вывода docker ps:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES .... a85321836507 bitnami/kafka:2-debian-10 "/opt/bitnami/script…" 7 days ago Up 7 minutes 0.0.0.0:9092->9092/tcp |
скрипты доступны по пути /opt/bitnami/kafka/bin внутри контейнера
Topic'и Kafka создаются автоматически, когда их начинают использовать, но можно создать вручную
kafka-topics.sh --create --zookeeper zookeeper:2181 --config cleanup.policy=delete --config file.delete.delay.ms=1 --replication-factor 1 --partitions 1 --topic mcd |
Для изменения параметра Topic'а можно использовать следующую команду.
Изменить время хранения сообщений в топике (будет работать автоматическая очистка).
kafka-topics.sh --zookeeper zookeeper:2181 --alter --topic mcd \ --config segment.ms=86400000 kafka-topics.sh --zookeeper zookeeper:2181 --alter --topic mcd \ --config retention.ms=86400000 |
segment.ms - время, которое определяет периодичность перестроения сегмента
retention.ms - время хранения данных в журнале (время за которое consumer должен забрать данные из очереди сообщений)
Изменить число партиций топика (позволяет масштабировать сервис).
kafka-topics.sh --zookeeper zookeeper:2181 --alter --topic mcd \ --partitions 1 |
Можно выполнить все вышеперечисленные настройки одной командой, например:
docker exec ${CONTAINER_ID} sh /opt/bitnami/kafka/bin/kafka-topics.sh --create --bootstrap-server ${KAFKA_HOST}:9092 --replication-factor 1 --partitions 1 --topic mcd --config retention.ms=86400000 --config segment.ms=86400000 --config segment.bytes=209715200 --config cleanup.policy=delete --config file.delete.delay.ms=1 |
Для проверки того что топик был корректно создан можно выполнить команды:
docker exec ${CONTAINER_ID} sh /opt/bitnami/kafka/bin/kafka-topics.sh --bootstrap-server ${KAFKA_HOST}:9092 --list docker exec ${CONTAINER_ID} sh /opt/bitnami/kafka/bin/kafka-configs.sh --bootstrap-server ${KAFKA_HOST}:9092 --describe --all --entity-type topics --entity-name ${TOPIC_NAME} |
${KAFKA_HOST} - адрес хоста, на котором запущена кафка
${TOPIC_NAME} - имя топика, в нашем случае - mcd
Сервис устанавливается с помощью пакетного менеджера командой
apt install eltex-mcdonalds |
Следует помнить, что в McDonald's летит информация только о тех, что дал явное согласие на получение рекламы.
В настройках портала 'Общие', 'Рекламная рассылка' нужно установить 'Спрашивать согласие пользователей на рассылку'.
Параметр 'Обязательное поле' запрещает оказывать услугу тем, что не дал согласие на получение рекламы. Установка этого флага остается на усмотрение заказчика.
Для работы с брокером сообщений Kafka, в конфигурационный файл /etc/eltex-pcrf/eltex-pcrf.json добавлен блок параметров "kafka".
Пример дефолтной конфигурации:
"kafka": { "bootstrap.servers": "localhost:9092", "mcd.enabled": false, "linger.ms": "1000", "topic": "mcd", "max.block.ms": "5000", "acks": "1" } |
Параметр | Описание | Значение по умолчанию |
---|---|---|
bootstrap.servers | Адрес Kafka сервера. | "localhost:9092" |
mcd.enabled | Параметр, отвечающий за использование отправки в Kafka. То есть по умолчанию этот функционал отключен. | false |
linger.ms | Устанавливает искусственную задержку отправки сообщений для буферизации пакетов Kafka, мс. | "1000" |
topic | Имя топика Kafka, в который будет происходить отправка. | "mcd" |
max.block.ms | Время на формирование блока данных для Kafka (получение метаданных и аллокации буфера), мс. Сериализация данных, ожидание ответа на запрос в это таймаут не входят. | "5000" |
acks | Количество подтверждений от сервера о доставке сообщения. Может быть установлен в значение "0" для отправки без подтверждения. | "1" |
Конфигурационный файл для настройки доступен по пути /etc/eltex-mcdonalds/application.conf
Пример дефолтной конфигурации:
mcd { baseUrl: "http://localhost:5555" requestTimeoutMs: 5000 connectTimeoutMs: 5000 socketTimeoutMs: 5000 rootDomain: "mcd.root" appToken: "token" pollPeriodMs: 1000 chunkSize: 100 kafkaTopic: "mcd" } kafka { bootstrap.servers: "localhost:9092" group.id: "mcd" auto.offset.reset: "latest" } |
Параметр | Описание | Значение по умолчанию |
---|---|---|
Параметры Eltex-mcdonalds | ||
baseUrl | URL McD-API назначения для отправки данных. | "http://localhost:5555" |
requestTimeoutMs | Таймаут запроса к серверу назначения, мс. | 5000 |
connectTimeoutMs | Таймаут установки соединения с сервером назначения, мс. | 5000 |
socketTimeoutMs | Таймаут отправки/получения пакетов, мс. | 5000 |
rootDomain | Фильтр по домену для входящих сообщений от Kafka. | |
appToken | Токен для обращения к внешнему серверу. | "" |
pollPeriodMs | Параметр настраивающий период отправки сообщений по API McDonalds, мс. | 10000 |
chunkSize | Максимальный размер (число сессий) порции передачи данных в McDonalds API. | 100 |
kafkaTopic | Имя топика Kafka из которого Eltex-mcdonalds читает сообщения. | "mcd" |
Параметры доступа к Kafka | ||
bootstrap.servers | Адрес Kafka сервера. | "127.0.0.1:9092" |
group.id | Группа к которой принадлежит потребитель сообщений. Разные сущности сервиса одного типа должны иметь одинаковый group.id, что дает возможность резервирования и масштабирования сервиса) | "mcd" |
auto.offset.reset | Параметр определяет, какие сообщения необходимо загружать из топика. Может принимать значения:
| "latest" |
Сервис может быть запущен в docker-контейнере. Для этого необходимо подготовить файл с переменными окружения .env и docker-compose.yml.
version: "3" services: eltex-mcdonalds: container_name: eltex-mcdonalds image: hub.eltex-co.ru/softwlc/eltex-mcdonalds:1.21-<tag> # Ограничиваем контейнеру потребление ОЗУ mem_limit: 128m environment: # Адрес шлюза McDonalds к которому обращается сервис - CONFIG_FORCE_mcd_baseUrl=${MCD_BASE_URL} - CONFIG_FORCE_mcd_requestTimeoutMs=${MCD_REQUEST_TIMEOUT_MS} - CONFIG_FORCE_mcd_connectTimeoutMs=${MCD_CONNECT_TIMEOUT_MS} - CONFIG_FORCE_mcd_socketTimeoutMs=${MCD_SOCKET_TIMEOUT_MS} # Фильтр по домену для входящих сообщений от Kafka - CONFIG_FORCE_mcd_rootDomain=${MCD_ROOT_DOMAIN} # Токен, для обращения к шлюзу McDonalds - CONFIG_FORCE_mcd_appToken=${MCD_APP_TOKEN} - CONFIG_FORCE_mcd_pollPeriodMs=${MCD_POLL_PERIOD_MS} - CONFIG_FORCE_mcd_chunkSize=${MCD_CHUNK_SIZE} # Название Kafka-топика - CONFIG_FORCE_mcd_kafkaTopic=${MCD_KAFKA_TOPIC} # Адрес сервера Kafka - CONFIG_FORCE_kafka_bootstrap_servers=${MCD_KAFKA_BOOTSTRAP_SERVERS} # Имя группы (необязательно) - CONFIG_FORCE_kafka_group_id=${MCD_KAFKA_GROUP_ID} - CONFIG_FORCE_kafka_auto_offset_reset=${MCD_KAFKA_AUTO_OFFSET_RESET} # Уровень логирования сервиса - MCD_LOG_LEVEL=${MCD_LOG_LEVEL} |
Вместо <tag> необходимо указать актуальную версию, которую можно посмотреть по ссылке. |
MCD_BASE_URL=http://localhost:5555 MCD_REQUEST_TIMEOUT_MS=5000 MCD_CONNECT_TIMEOUT_MS=5000 MCD_SOCKET_TIMEOUT_MS=5000 MCD_ROOT_DOMAIN=root MCD_APP_TOKEN=token MCD_POLL_PERIOD_MS=1000 MCD_CHUNK_SIZE=100 MCD_KAFKA_TOPIC=mcd MCD_KAFKA_BOOTSTRAP_SERVERS=localhost:9092 MCD_KAFKA_GROUP_ID=mcd MCD_KAFKA_AUTO_OFFSET_RESET=latest MCD_LOG_LEVEL=info |
Файлы .env и docker-compose.yml должны находиться в одной папке. Контейнер запускается командой:
docker-compose up |
Для понимания работоспособности функционала на ядре доступны следующие механизмы.
Доступны Prometheus метрики обработки сообщений.
Метрики, срабатывающие на методе KafkaProducer.send (отправка сообщений в шину данных).
KafkaProducer.sendFailed - счетчик ошибок ;
Вся информация о работе сервиса может быть получена только из лог файлов.