Поддержка модуля с версии 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. |
Принцип работы
- Eltex-PCRF отправляет данные о начале и окончании всех сессий пользователей в шину данных Kafka. В шину данных летит информация о сессиях всех клиентов, всех пользователей.
- Kafka может раздавать данные произвольному числу клиентов. Все клиенты подписываются на topic сообщений. К Kafka можно подключать как клиентов, выполняющих различные действия над одними данными (то есть сервисы разных типов) так и несколько сущностей одного сервиса для повышения пропускной способности и резервирования;
- Eltex-Mcdonalds забирает сообщения из Kafka, проводит валидацию (заполнение обязательный полей) и фильтрацию данных (по домену) и отправляет данные в McD-API. Eltex-Mcdonalds отправляет данные только о пользователях давших согласие на получение рекламной рассылки. Фильтрация данных настраивается только по домену. В системе должен быть создан корневой гостевой домен клиента mcdonalds. Для подключения к API фронт-системе необходимо использовать токен;
- Сообщения передаются в режиме реального времени, чтобы иметь возможность сразу же обработать эту информацию и скорректировать стратегию коммуникации с пользователем. Для уменьшения трафика передаются только события старта и окончания сессии;
- Согласие на получение рекламных материалов указывается на портале при регистрации.
Описание McD-API
Для отправки данных используются два метода:
Базовый 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.
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 будет доступен другим приложениям.
Создание, изменение topic'а
Для управления параметрами 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
Установка eltex-mcdonalds
Сервис устанавливается с помощью пакетного менеджера командой
apt install eltex-mcdonalds
Настройка
Настройка Captive portal
Следует помнить, что в McDonald's летит информация только о тех, что дал явное согласие на получение рекламы.
В настройках портала 'Общие', 'Рекламная рассылка' нужно установить 'Спрашивать согласие пользователей на рассылку'.
Параметр 'Обязательное поле' запрещает оказывать услугу тем, что не дал согласие на получение рекламы. Установка этого флага остается на усмотрение заказчика.
Настройка PCRF
Для работы с брокером сообщений 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" |
Настройка eltex-mcdonalds
Конфигурационный файл для настройки доступен по пути /etc/eltex-mcdonalds/application.conf
Пример дефолтной конфигурации:
Параметр | Описание | Значение по умолчанию |
---|---|---|
Параметры 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" |
Докеризация сервиса eltex-mcdonalds
Сервис может быть запущен в 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}
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
Мониторинг
Для понимания работоспособности функционала на ядре доступны следующие механизмы.
PCRF
Доступны Prometheus метрики обработки сообщений.
Метрики, срабатывающие на методе KafkaProducer.send (отправка сообщений в шину данных).
KafkaProducer.sendFailed - счетчик ошибок ;
- KafkaProducer.sendSuccess - счетчик успешной отправки.
eltex-mcdonalds
Вся информация о работе сервиса может быть получена только из лог файлов.