Управление источниками EPG¶

Источники EPG (Electronic Program Guide — электронная программа передач) предоставляют информацию о телепрограмме для каждого канала: названия передач, время начала и окончания, описания, жанры и возрастные рейтинги.

Что такое источник EPG¶

Источник EPG в Catena — это ссылка на внешний XML-файл с расписанием телепередач. Система периодически загружает этот файл и синхронизирует данные о программах для отображения в клиентских приложениях.

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

• Автоматическая синхронизация — регулярная загрузка и обновление программы передач
• Поддержка нескольких источников — разные источники EPG для разных групп каналов
• Мониторинг загрузок — отслеживание статуса и результатов обновления EPG
• Просмотр программ — получение расписания через API для интеграции

Типичный workflow:

1. Создать источник EPG с указанием URL XML-файла
2. Настроить период автоматического обновления
3. Привязать каналы к источнику EPG (в настройках каналов)
4. Система автоматически загружает и обновляет программу передач
5. Абоненты видят актуальную телепрограмму в приложениях

Основные параметры источника EPG¶

Технические параметры¶

Идентификатор источника (EPG Source ID)

• Автоматически генерируется при создании источника
• Формат: base64-кодированный Snowflake ID с заменой символов +/= на -_.
• Пример: aKl9SW3AAAE.
• Используется для программного доступа через API
• Не редактируется после создания

Имя источника (Name)

• Уникальное техническое имя источника EPG
• Используется для идентификации в системе и в настройках каналов
• Примеры: main-epg, sports-epg, xmltv-provider

ID портала (Portal ID)

• Идентификатор портала, к которому принадлежит источник
• Автоматически устанавливается при создании

Параметры загрузки¶

URL источника (URL)

• Полный URL до XML-файла с программой передач
• Поддерживаемые протоколы: HTTP, HTTPS
• Пример: https://epg.example.com/epg.xml
• Обязательное поле

Период обновления (Period)

• Интервал в днях для автоматического обновления EPG
• Пример: 7 — обновлять каждые 7 дней
• Минимальное значение: 1 день
• Если не указан, используется значение по умолчанию
• Система автоматически загружает EPG согласно указанному периоду без необходимости ручного вмешательства

Результат последней загрузки¶

Информация о загрузке (Last Fetch Result)

Поле last_fetch_result содержит информацию о последнем обновлении EPG:

• fetched_at — время последней загрузки (ISO 8601)
• job_id — идентификатор задания загрузки
• status — статус загрузки:
• success — успешно загружено
• error — ошибка загрузки
• timeout — превышено время ожидания
• message — текстовое сообщение о результате
• channels — количество обновлённых каналов
• foundPrograms — количество найденных программ в XML
• importedPrograms — количество импортированных программ
• deletedPrograms — количество удалённых старых программ
• fetchDuration — время загрузки XML в секундах
• importDuration — время импорта данных в секундах

Создание источника EPG¶

Через веб-интерфейс¶

1. Откройте раздел "EPG Sources" в панели управления Catena
2. Нажмите кнопку "Создать источник EPG"

3. Заполните обязательные поля:

4. Name — техническое имя источника (например, main-epg)

5. URL — полный URL до XML-файла с EPG

6. Заполните дополнительные поля (опционально):

7. Period — период обновления в днях (например, 7)

8. Сохраните источник

9. Запустите первичную загрузку через кнопку "Обновить сейчас"

После создания источник получит уникальный ID и будет доступен для привязки к каналам.

Через Management API¶

curl -X POST https://your-catena-domain.com/tv-management/api/v1/epg-sources \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "main-epg",
    "url": "https://epg.example.com/xmltv.xml",
    "period": 7
  }'

Ответ:

{
  "epgSourceId": "eKl9SW3AAAE.",
  "portalId": "pKl9SW3AAAE.",
  "name": "main-epg",
  "url": "https://epg.example.com/xmltv.xml",
  "period": 7,
  "last_fetch_result": null
}

Просмотр списка источников EPG¶

Через веб-интерфейс¶

В разделе "EPG Sources" отображается таблица со всеми источниками:

• Название — имя источника (Name)
• URL — адрес XML-файла
• Период — интервал обновления в днях
• Последнее обновление — дата и время последней загрузки
• Статус — результат последней загрузки (success/error/timeout)
• Программ — количество импортированных программ
• Действия — кнопки обновления, редактирования и удаления

Через Management API¶

Получить список всех источников EPG:

curl -X GET https://your-catena-domain.com/tv-management/api/v1/epg-sources \
  -H "X-Auth-Token: your-api-key"

Ответ:

{
  "epgSources": [
    {
      "epgSourceId": "eKl9SW3AAAE.",
      "portalId": "pKl9SW3AAAE.",
      "name": "main-epg",
      "url": "https://epg.example.com/xmltv.xml",
      "period": 7,
      "last_fetch_result": {
        "epgSourceId": "eKl9SW3AAAE.",
        "fetched_at": "2024-10-16T10:30:00Z",
        "job_id": "job123",
        "status": "success",
        "message": "EPG source fetched successfully",
        "channels": 25,
        "foundPrograms": 5000,
        "importedPrograms": 4950,
        "deletedPrograms": 2100,
        "fetchDuration": 5,
        "importDuration": 12
      }
    }
  ]
}

Получение информации об источнике¶

Через Management API¶

curl -X GET https://your-catena-domain.com/tv-management/api/v1/epg-sources/eKl9SW3AAAE. \
  -H "X-Auth-Token: your-api-key"

Ответ: Аналогичен объекту EPG source из списка.

Редактирование источника EPG¶

Через веб-интерфейс¶

1. Откройте список источников EPG
2. Найдите нужный источник и нажмите кнопку "Редактировать"

3. Измените параметры:

4. Name — техническое имя

5. URL — адрес XML-файла
6. Period — период обновления
7. Сохраните изменения

Примечание: Изменение URL или period не запускает автоматическое обновление — используйте кнопку "Обновить сейчас" для немедленной загрузки.

Через Management API¶

curl -X PUT https://your-catena-domain.com/tv-management/api/v1/epg-sources/eKl9SW3AAAE. \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "main-epg",
    "url": "https://epg.example.com/updated-xmltv.xml",
    "period": 3
  }'

Принудительное обновление EPG¶

Вы можете запустить внеплановое обновление EPG в любой момент.

Через веб-интерфейс¶

1. Откройте список источников EPG
2. Найдите нужный источник
3. Нажмите кнопку "Обновить сейчас"
4. Дождитесь завершения — процесс может занять от нескольких секунд до минут

Через Management API¶

curl -X POST https://your-catena-domain.com/tv-management/api/v1/epg-sources/eKl9SW3AAAE./update \
  -H "X-Auth-Token: your-api-key"

Ответ:

{
  "jobId": "job456"
}

Важно: Обновление выполняется асинхронно. Используйте jobId для отслеживания прогресса или проверьте поле last_fetch_result через некоторое время.

Удаление источника EPG¶

Через веб-интерфейс¶

1. Откройте список источников EPG
2. Найдите источник для удаления
3. Нажмите кнопку "Удалить"
4. Подтвердите удаление

Предупреждение: При удалении источника EPG:

• Все программы из этого источника будут удалены
• Каналы, привязанные к этому источнику, потеряют связь с EPG
• Абоненты перестанут видеть программу передач для этих каналов

Через Management API¶

curl -X DELETE https://your-catena-domain.com/tv-management/api/v1/epg-sources/eKl9SW3AAAE. \
  -H "X-Auth-Token: your-api-key"

Просмотр программ из источника EPG¶

Вы можете получить список программ для анализа или отладки.

Получение программ через API¶

Получить все программы источника:

curl -X GET https://your-catena-domain.com/tv-management/api/v1/epg-sources/eKl9SW3AAAE./programs \
  -H "X-Auth-Token: your-api-key"

Фильтрация по дате:

curl -X GET "https://your-catena-domain.com/tv-management/api/v1/epg-sources/eKl9SW3AAAE./programs?date=2024-10-16" \
  -H "X-Auth-Token: your-api-key"

Фильтрация по каналу:

curl -X GET "https://your-catena-domain.com/tv-management/api/v1/epg-sources/eKl9SW3AAAE./programs?epgChannelName=channel1" \
  -H "X-Auth-Token: your-api-key"

Комбинированная фильтрация:

curl -X GET "https://your-catena-domain.com/tv-management/api/v1/epg-sources/eKl9SW3AAAE./programs?date=2024-10-16&epgChannelName=channel1" \
  -H "X-Auth-Token: your-api-key"

Ответ:

{
  "programs": [
    {
      "programId": "prKl9SW3AAAE.",
      "portalId": "pKl9SW3AAAE.",
      "epgSourceId": "eKl9SW3AAAE.",
      "epgChannelName": "channel1",
      "date": "2024-10-16",
      "start": "2024-10-16T12:00:00Z",
      "end": "2024-10-16T13:00:00Z",
      "title": "Новости",
      "language": "ru",
      "description": "Главные новости дня",
      "genre": "News",
      "rating": "0+"
    }
  ],
  "next": "cursor-for-next-page"
}

Пагинация:

curl -X GET "https://your-catena-domain.com/tv-management/api/v1/epg-sources/eKl9SW3AAAE./programs?cursor=cursor-for-next-page" \
  -H "X-Auth-Token: your-api-key"

Просмотр истории обновлений EPG¶

Catena автоматически сохраняет историю всех обновлений EPG, что позволяет отслеживать успешность загрузок, анализировать проблемы и мониторить работу источников.

Автоматическое обновление EPG¶

Как работает автоматическое обновление:

• Система автоматически запускает обновление EPG согласно параметру period каждого источника
• Обновления выполняются в фоновом режиме без остановки работы системы
• Каждое обновление записывается в историю с полной информацией о результате
• При успешном обновлении новые программы становятся доступны абонентам немедленно

Преимущества автоматического обновления:

• Не требуется ручное вмешательство для поддержания актуальности EPG
• Программа передач всегда остаётся актуальной для абонентов
• Возможность отследить все попытки обновления и выявить проблемы

Просмотр истории через веб-интерфейс¶

На странице источника EPG отображается:

• История последних обновлений — таблица со всеми попытками загрузки
• Дата и время каждого обновления
• Статус — success/error/timeout
• Статистика — количество найденных, импортированных и удалённых программ
• Длительность — время загрузки и импорта данных
• Сообщения об ошибках (если были)

Получение истории через API¶

Получить историю всех обновлений EPG:

curl -X GET https://your-catena-domain.com/tv-management/api/v1/epg-fetches \
  -H "X-Auth-Token: your-api-key"

Фильтрация по конкретному источнику:

curl -X GET "https://your-catena-domain.com/tv-management/api/v1/epg-fetches?epgSourceId=eKl9SW3AAAE." \
  -H "X-Auth-Token: your-api-key"

Пагинация:

curl -X GET "https://your-catena-domain.com/tv-management/api/v1/epg-fetches?cursor=cursor-for-next-page" \
  -H "X-Auth-Token: your-api-key"

Ответ:

{
  "epgFetches": [
    {
      "epgFetchId": "fKl9SW3AAAE.",
      "epgSourceId": "eKl9SW3AAAE.",
      "created_at": "2024-10-16T10:25:00Z",
      "fetched_at": "2024-10-16T10:30:00Z",
      "job_id": "job123",
      "status": "success",
      "message": "EPG source fetched successfully",
      "channels": 25,
      "foundPrograms": 5000,
      "importedPrograms": 4950,
      "deletedPrograms": 2100,
      "fetchDuration": 5,
      "importDuration": 12
    },
    {
      "epgFetchId": "fKl9SW3AAAA.",
      "epgSourceId": "eKl9SW3AAAE.",
      "created_at": "2024-10-09T10:25:00Z",
      "fetched_at": "2024-10-09T10:29:00Z",
      "job_id": "job122",
      "status": "success",
      "message": "EPG source fetched successfully",
      "channels": 25,
      "foundPrograms": 4800,
      "importedPrograms": 4750,
      "deletedPrograms": 1950,
      "fetchDuration": 4,
      "importDuration": 10
    }
  ],
  "next": "cursor-for-next-page"
}

Поля истории обновлений¶

Основные поля записи истории:

• epgFetchId — уникальный идентификатор попытки обновления
• epgSourceId — идентификатор источника EPG
• created_at — время создания задачи на обновление (ISO 8601)
• fetched_at — время фактического завершения загрузки (ISO 8601)
• job_id — идентификатор фонового задания
• status — статус обновления:
• success — успешно загружено и импортировано
• error — произошла ошибка
• timeout — превышено время ожидания
• message — текстовое описание результата
• channels — количество обновлённых каналов
• foundPrograms — всего программ найдено в XML файле
• importedPrograms — программ успешно импортировано в базу
• deletedPrograms — устаревших программ удалено
• fetchDuration — время загрузки XML файла (секунды)
• importDuration — время обработки и импорта данных (секунды)

Анализ истории обновлений¶

Использование истории для мониторинга:

1. Отслеживание стабильности — проверка, что обновления проходят регулярно
2. Выявление проблем — поиск записей со статусом error или timeout
3. Анализ производительности — отслеживание времени загрузки и импорта
4. Контроль качества данных — сравнение количества программ между обновлениями

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

# Проверить последние обновления с ошибками
curl -X GET "https://your-catena-domain.com/tv-management/api/v1/epg-fetches" \
  -H "X-Auth-Token: your-api-key" | jq '.epgFetches[] | select(.status != "success")'

# Получить среднее время импорта для источника
curl -X GET "https://your-catena-domain.com/tv-management/api/v1/epg-fetches?epgSourceId=eKl9SW3AAAE." \
  -H "X-Auth-Token: your-api-key" | jq '[.epgFetches[].importDuration] | add / length'

Привязка каналов к источнику EPG¶

Источник EPG сам по себе не предоставляет программу передач каналам. Необходимо явно указать в настройках каждого канала:

• EPG Source Name — имя источника EPG
• EPG Channel Name — имя канала в XML EPG

Подробнее см. раздел Интеграция каналов с EPG.

Пример настройки канала:

curl -X PUT https://your-catena-domain.com/tv-management/api/v1/channels/cKl9SW3AAAE. \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sport1",
    "title": "Спорт HD",
    "epgSourceName": "main-epg",
    "epgChannelName": "sport-channel-1"
  }'

После этого программа передач из источника main-epg для канала sport-channel-1 будет доступна для канала sport1.

Формат EPG XML¶

Структура XMLTV¶

Catena поддерживает стандартный формат XMLTV. Базовая структура:

<?xml version="1.0" encoding="UTF-8"?>
<tv>
  <!-- Описание каналов -->
  <channel id="channel1">
    <display-name>Первый канал</display-name>
  </channel>

  <!-- Программы -->
  <programme start="20241016120000" stop="20241016130000" channel="channel1">
    <title lang="ru">Новости</title>
    <desc lang="ru">Главные новости дня</desc>
    <category lang="ru">News</category>
    <rating system="age">
      <value>0+</value>
    </rating>
  </programme>
</tv>

Поддерживаемые поля¶

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

• start — время начала (формат: YYYYMMDDHHmmss)
• stop — время окончания
• channel — идентификатор канала (используется для сопоставления)
• title — название передачи

Опциональные поля:

• desc — описание передачи
• category — жанр (News, Sports, Movie и т.д.)
• rating — возрастной рейтинг (0+, 6+, 12+, 16+, 18+)
• lang — язык программы

Типичные сценарии использования¶

Подключение стандартного XMLTV провайдера¶

Задача: Подключить EPG от стороннего провайдера

Шаги:

1. Получите URL XMLTV от провайдера (например, https://provider.com/epg.xml)
2. Создайте источник EPG в Catena с этим URL
3. Установите период обновления 1 день
4. Запустите первичную загрузку
5. Проверьте результат загрузки в last_fetch_result
6. Привяжите каналы к источнику, указав корректные epgChannelName
7. Проверьте отображение программы в клиентских приложениях

Использование нескольких источников EPG¶

Задача: Разные группы каналов берут EPG из разных источников

Пример:

• epg-russia — российские каналы
• epg-europe — европейские каналы
• epg-sports — спортивные каналы от специализированного провайдера

Преимущества:

• Независимое обновление разных групп каналов
• Возможность использовать специализированных провайдеров для определённых тематик
• Изоляция проблем — ошибка в одном источнике не влияет на другие

Мониторинг обновлений EPG¶

Задача: Отслеживать успешность загрузки EPG

Решение через API:

# Получить историю обновлений всех источников
curl -X GET https://your-catena-domain.com/tv-management/api/v1/epg-fetches \
  -H "X-Auth-Token: your-api-key"

# Или получить историю конкретного источника
curl -X GET "https://your-catena-domain.com/tv-management/api/v1/epg-fetches?epgSourceId=eKl9SW3AAAE." \
  -H "X-Auth-Token: your-api-key"

# Проверить status для каждой записи
# Если status != "success" — есть проблема
# Если последнее обновление давно — EPG устарел

Настройка алертов:

• Создайте скрипт проверки истории обновлений EPG
• Запускайте по расписанию (например, каждый час)
• Отправляйте уведомления при ошибках или отсутствии обновлений
• Используйте endpoint /epg-fetches для получения полной истории

Лучшие практики¶

Выбор провайдера EPG¶

Критерии выбора:

• Полнота данных — наличие описаний, жанров, рейтингов
• Актуальность — как часто обновляется EPG
• Охват — поддержка нужных вам каналов
• Надёжность — uptime сервиса, скорость ответа
• Формат — соответствие стандарту XMLTV
• Стоимость — бесплатные vs платные источники

Настройка периода обновления¶

Рекомендации:

• 1 день — для источников с ежедневным обновлением
• 7 дней — для источников с программой на неделю вперёд
• Меньше дня — не рекомендуется, создаёт лишнюю нагрузку

Учитывайте:

• Как часто провайдер обновляет EPG
• Размер XML файла (большие файлы — реже обновлять)
• Нагрузку на ваш сервер

Обработка ошибок¶

Мониторинг:

• Регулярно проверяйте last_fetch_result.status
• Настройте алерты при status = "error" или "timeout"
• Отслеживайте fetched_at — предупреждайте, если EPG не обновлялся >2 дней

При ошибках:

1. Проверьте доступность URL (откройте в браузере)
2. Проверьте формат XML — валидность структуры
3. Проверьте размер файла — возможно, слишком большой
4. Проверьте сетевые настройки сервера (firewall, proxy)

Оптимизация производительности¶

Рекомендации:

• Не загружайте EPG чаще, чем необходимо
• Используйте CDN для распространения EPG XML, если это ваш файл
• Убедитесь, что XML файл сжат (gzip)
• Разделяйте большие EPG на несколько источников по тематикам

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

EPG не загружается¶

Возможные причины:

• URL недоступен или возвращает ошибку
• XML файл имеет неверный формат
• Проблемы с сетью на стороне Catena сервера
• Timeout — файл слишком большой

Решение:

1. Проверьте last_fetch_result.message для деталей ошибки
2. Откройте URL в браузере — проверьте доступность
3. Валидируйте XML через онлайн-валидатор
4. Проверьте размер файла — попробуйте уменьшить
5. Проверьте логи сервера Catena

Программы не отображаются в приложении¶

Возможные причины:

• Канал не привязан к источнику EPG
• Неверно указан epgChannelName в настройках канала
• EPG не обновлялся или загрузка была с ошибкой
• Программы в EPG устарели (прошедшие даты)

Решение:

1. Проверьте настройки канала — epgSourceName и epgChannelName
2. Сравните epgChannelName с идентификатором канала в XML
3. Проверьте last_fetch_result — была ли успешная загрузка
4. Проверьте наличие программ через API /epg-sources/{id}/programs
5. Убедитесь, что в EPG есть программы на текущую/будущую дату

Неполные данные программ¶

Причина: EPG XML не содержит все поля (описания, жанры, рейтинги)

Решение:

• Свяжитесь с провайдером EPG для улучшения данных
• Используйте другого провайдера с более полными данными
• Примите это как есть — базовая информация (название, время) всё равно будет доступна

Несовпадение временных зон¶

Проблема: Время программ отображается неверно

Решение:

1. Убедитесь, что в EPG XML время указано в UTC или с указанием timezone
2. Проверьте настройки timezone на сервере Catena
3. Клиентские приложения должны конвертировать UTC в локальное время пользователя

Дубликаты программ¶

Причина: EPG обновляется, но старые программы не удаляются

Решение:

• Это нормальное поведение при обновлении
• Поле deletedPrograms в last_fetch_result показывает, сколько удалено
• Если дубликаты остаются, это может быть проблема с идентификацией программ в EPG XML

См. также¶

• Управление каналами — привязка каналов к источникам EPG
• Интеграция EPG с каналами — настройка связи
• API Reference — полная документация по API источников EPG