Обогащение данных ONU

GetOLT умеет дополнять записи ONU данными абонента — номером договора, логином, ФИО, адресом и идентификаторами услуги/договора — из систем, которые уже есть у оператора. Это позволяет видеть «кто стоит за этой ONU» без переключения на сторонние системы.

Обогащение работает по совпадению MAC-адреса: GetOLT нормализует MAC зарегистрированной ONU и ищет его среди данных, которые отдаёт источник. Найдено — данные появляются в карточке ONU.

Типы источников

Источник обогащения настраивается через Админка → Обогащение. Поддерживаются три типа — выбираете под то, что доступно у вас:

Тип источника	Когда использовать
Произвольный SQL	У вас есть прямой доступ к БД биллинга/АБС (MySQL, MariaDB, PostgreSQL). Регулярное обновление по расписанию.
REST API	Доступ к данным только через HTTP API биллинга/CRM. Без прямого доступа к БД. Регулярное обновление по расписанию.
Разовый CSV-импорт	Нужно подгрузить выгрузку один раз, без повторения по расписанию.

Общее для всех типов:

• Совпадение всегда по MAC-адресу; обновляются до шести полей карточки абонента: номер договора, логин, ФИО, адрес, serviceId, contractId.
• Перед применением доступен предпросмотр: GetOLT покажет, что именно будет записано, не трогая ваши системы.
• GetOLT работает read-only по отношению к вашим данным — он только читает.
• ONU, отредактированные вручную, не перезаписываются (см. раздел «Ручные правки не перетираются» ниже).

---

Источник: внешняя БД (SQL)

[ GetOLT ] ── SELECT по MAC ──> [ ваша БД ]
                                     │
                              совпадение MAC → договор, логин, ФИО, адрес
                                     │
                         ← данные подставляются в карточку ONU

Поддерживаемые СУБД

СУБД	Поддержка
MySQL 5.7+ / 8.x	да
MariaDB 10.3+	да
PostgreSQL 12+	да

Настройка SQL-источника

1. Откройте Админка → Обогащение (раздел «Админка» — в выпадающем меню профиля справа вверху).
2. Нажмите «Добавить источник» и выберите тип «Произвольный SQL».
3. Заполните параметры подключения:
   • СУБД — выберите из списка (MySQL/MariaDB/PostgreSQL).
   • Хост — адрес сервера БД (например db.company.local).
   • Порт — 3306 для MySQL/MariaDB, 5432 для PostgreSQL.
   • Имя БД — название схемы/базы данных.
   • Пользователь и Пароль — учётные данные read-only пользователя.
4. Напишите SELECT-запрос (подробнее ниже).
5. Укажите маппинг колонок — какая колонка результата соответствует каждому полю GetOLT.
6. Нажмите «Предпросмотр», убедитесь, что данные отображаются корректно.
7. Сохраните — источник сразу включается и встаёт в расписание (см. ниже).

Запрос SELECT и маппинг колонок

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

SELECT
  onu_mac      AS mac_onu,
  device_mac   AS mac_user,
  contract_no  AS dogovor,
  user_login   AS login,
  full_name    AS fio,
  address      AS addr,
  service_id   AS service_id,
  contract_id  AS contract_id
FROM subscribers

Используйте AS, чтобы задать имена колонок удобным образом — GetOLT ссылается на них через маппинг.

Маппинг колонок

После написания запроса укажите, какая колонка результата соответствует каждому полю:

Поле GetOLT	Колонка в примере	Обязательность
MAC ONU	mac_onu	обязательно
MAC пользователя	mac_user	опционально
Номер договора	dogovor	опционально
Логин	login	опционально
ФИО	fio	опционально
Адрес	addr	опционально
serviceId	service_id	опционально
contractId	contract_id	опционально

Обязательна только колонка MAC ONU — по ней GetOLT ищет совпадение. Остальные поля подставляются в карточку ONU по мере наличия.

Заметка

Если в вашей базе другие имена колонок — переименуйте их через AS прямо в запросе. В маппинге указываете то имя, которое вернул ваш SELECT, — не исходное имя в таблице.

Допустимые форматы MAC-адреса

GetOLT нормализует MAC автоматически — источник может хранить его в любом из перечисленных форматов:

Формат	Пример
Без разделителей	aabbccddeeff
Через двоеточие	aa:bb:cc:dd:ee:ff
Через дефис	aa-bb-cc-dd-ee-ff
3-блочный, дефис	aaaa-bbbb-cccc
3-блочный, точка	aaaa.bbbb.cccc
Бинарный столбец	бинарные 6 байт (столбец типа BINARY(6)) — см. пример ниже

Регистр (верхний/нижний) и пробелы значения не имеют — GetOLT приведёт к единому виду перед сравнением.

Если MAC хранится в нестандартном виде (например как BINARY(6) или с нестандартными разделителями), приведите его к hex прямо в запросе:

SELECT
  LOWER(HEX(onu_mac_binary)) AS mac_onu,
  ...
FROM subscribers

Заметка

Это работает в MySQL/MariaDB. В PostgreSQL аналог — encode(onu_mac_binary, 'hex').

Безопасность и требования

• Только SELECT — любой запрос, содержащий INSERT, UPDATE, DELETE или DDL-команды, GetOLT отклонит до выполнения. Это защита от случайной записи в вашу базу.
• Read-only пользователь — заведите отдельную учётную запись в вашей СУБД с правами только на чтение нужных таблиц или представлений. GetOLT не требует привилегий на запись.
• Пароль хранится в зашифрованном виде в базе данных GetOLT — в UI он не отображается после сохранения.
• Сетевая связность — хост GetOLT должен достигать вашего сервера БД по нужному порту (обычно 3306 или 5432). Если БД в закрытой сети — настройте сетевой маршрут или туннель заранее.

Осторожно

Не используйте административный аккаунт СУБД для подключения. Минимальные права — SELECT на конкретные таблицы или представление, из которого берёте данные.

---

Источник: REST API

Если прямого доступа к БД нет, а данные абонентов доступны через HTTP API биллинга или CRM — используйте источник типа REST API. Он настраивается полностью через форму, без написания кода, и покрывает типовые случаи: разные способы авторизации, произвольную форму JSON-ответа и две модели забора данных.

Две модели забора (режим fetchMode)

Режим	Как работает	Когда выбирать
По списку MAC (lookup)	GetOLT отправляет в API список MAC-адресов своих ONU пачками, API возвращает абонентов только по этим MAC.	Основной сценарий. API умеет искать абонентов по списку MAC.
Полная выгрузка (bulk)	API отдаёт всех абонентов (с пагинацией), совпадение по MAC GetOLT считает локально.	API не умеет фильтровать по MAC и отдаёт весь список.

В режиме lookup MAC отправляются пачками; размер пачки и формат MAC в запросе (с разделителями/без, верхний/нижний регистр) задаются в форме под ваш API. В режиме bulk настраивается тип пагинации (по номеру страницы, по смещению или по курсору) — GetOLT обходит страницы до конца.

Авторизация

Поддерживаются распространённые схемы — выбираете в поле «Тип авторизации»:

Тип	Что подставляется в запрос
Без авторизации	ничего
Bearer-токен	заголовок Authorization: Bearer <токен>
API-ключ в заголовке	произвольный заголовок (имя задаёте), значение — токен
Basic	логин и пароль (HTTP Basic)
API-ключ в query	параметр строки запроса (имя задаёте), значение — токен

Токены и пароли хранятся в зашифрованном виде и не показываются в UI после сохранения.

Маппинг полей по JSON-путям

Ответ API может быть любой формы — вы указываете, по какому пути в JSON лежит каждое поле:

• Путь к массиву записей (rootPath) — где в ответе лежит список абонентов (например data.subscribers); пусто, если ответ сам по себе массив.
• Для каждого поля абонента — путь внутри одной записи, через точку для вложенности: mac, device.mac, account.login, customer.fio и т.д.

Обязателен только путь к MAC ONU — по нему идёт совпадение. Остальные поля (MAC пользователя, номер договора, логин, ФИО, адрес, serviceId, contractId) подставляются по мере наличия. После предпросмотра форма подсказывает доступные пути из реального ответа — выбираете из списка, а не печатаете вручную.

Настройка REST API-источника

1. Откройте Админка → Обогащение, нажмите «Добавить источник» и выберите тип «REST API».
2. В группе «Подключение» укажите URL, режим забора (lookup/bulk), при необходимости — HTTP-метод и таймауты.
3. В группе «Аутентификация» выберите тип и заполните токен/логин — лишние поля скрываются автоматически.
4. Заполните параметры выбранного режима (список MAC или пагинация).
5. Нажмите «Проверить источник» — GetOLT сделает пробный запрос и покажет, что вернул API и какие поля доступны.
6. Сопоставьте поля абонента с путями в ответе (см. выше).
7. Сохраните.

Осторожно

Источник REST API нельзя сохранить, пока не прошёл тест подключения. При сохранении GetOLT делает контрольный запрос к API и проверяет код ответа и форму JSON. Если API недоступен или ответ не соответствует указанному пути к массиву — источник не сохранится, а форма покажет ошибку с кодом ответа. Это защищает от заведомо нерабочей конфигурации.

---

Расписание и запуск

Это поведение общее для источников SQL и REST API (разовый CSV-импорт по расписанию не повторяется).

• Источник включается сразу при создании и встаёт в расписание. Сразу после сохранения он виден в разделе «Планировщики» и работает по cron.
• Cron задаётся выражением из 6 полей (секунды минуты часы день месяц день-недели) в поле «Cron» формы. Например, 0 0 3 * * * означает «каждый день в 03:00».
• Если поле Cron оставить пустым, источник получает расписание по умолчанию (раз в сутки ночью) — он всё равно включён и будет запускаться. Это не «ручной режим».
• Запустить вручную в любой момент можно кнопкой «Запустить» на странице источника.
• Поставить на паузу источник можно позже: откройте «Править» и снимите галку «Включён».

---

Разовый импорт из CSV

Кроме повторяемых источников (SQL и REST API), поля абонента в olt_onu можно обогатить разово — загрузив CSV-выгрузку из биллинга или АБС. Импорт применяется один раз и по расписанию не повторяется (для регулярного обновления используйте SQL- или REST API-источник).

Откройте Админка → Обогащение → Разовый импорт CSV и выполните три шага:

1. Загрузка. Выберите файл и параметры:

   • Кодировка — UTF-8 (по умолчанию) или Windows-1251 (частый формат выгрузок).
   • Разделитель — авто-определение, запятая, точка с запятой или табуляция.
   • Первая строка — заголовки — снимите галочку, если в файле сразу данные (колонки будут названы col1, col2, …).

   Нажмите «Разобрать файл».

2. Сопоставление колонок. Для каждого поля выберите соответствующую колонку файла: MAC ONU (обязательно), MAC пользователя, номер договора, логин, ФИО, адрес, serviceId, contractId.

3. Проверка и применение. Нажмите «Проверить» — GetOLT покажет, сколько строк валидно, сколько пропущено (нет корректного MAC) и сколько совпадёт с ONU. Нажмите «Применить» для записи изменений в olt_onu.

Заметка

Импорт обновляет только сопоставленные непустые поля у совпавших ONU. Поля, для которых вы не указали колонку (или в строке они пустые), сохраняют прежнее значение — обогащение их не очищает. Чтобы изменить поле — сопоставьте его колонку с непустым значением.

Поддерживаются те же форматы MAC, что описаны выше в разделе «Допустимые форматы MAC-адреса». Строки без корректного MAC пропускаются.

Ручные правки не перетираются

Данные абонента у конкретной ONU можно заполнить или поправить вручную — карандашом в таблице ONU на карточке OLT (см. UI: основные сценарии). Такая ONU помечается значком замка и исключается из обогащения — ни один источник (SQL, REST API, разовый CSV-импорт) её не затронет. Это удобно для единичных абонентов, которых нет в общей выгрузке, или для ручной корректировки.

Чтобы вернуть ONU под автоматическое обогащение — откройте окно правки и снимите галочку «Защитить от автообогащения».

---

Если у вас нетипичная схема хранения (несколько источников на один оператор, миграция между системами, нестандартный формат MAC) — напишите в support@getolt.online или в Telegram @getolt_pub: настройка под конкретную схему займёт обычно не более одного сеанса поддержки.