Перейти к содержимому
Cesbo LogoCesbo Astra

API категорий

С помощью категорий и групп можно упорядочить потоки в плейлистах и веб-интерфейсе и ограничить, какие потоки может смотреть пользователь. Категория содержит упорядоченный список групп, например News и Movies в Genre. В каждой категории поток может входить не больше чем в одну группу.

  • Чтобы прочитать категории, скачайте конфигурацию и посмотрите массив categories. Порядок в этом массиве - это порядок отображения.
  • Чтобы добавить поток в группу, задайте его поле groups, где каждому имени категории соответствует имя группы, и отправьте поток целиком через set-stream.
  • Чтобы добавить, изменить или удалить категории и группы, используйте set-category.

Об аутентификации и смене пути к API читайте в разделе Как вызывать методы API.

Задать категорию

Заголовок раздела «Задать категорию»

Добавляет, обновляет или удаляет категорию вместе с её группами.

POST/control/set-category
admin

Запрос

idnumber

Текущий индекс категории, начиная с 0. Нужен, чтобы обновить или удалить категорию. Чтобы добавить категорию, не указывайте его.

categoryobjectобязательный

Полный объект категории. Чтобы удалить категорию, отправьте {"remove": true}.

category.namestring

Имя категории. Обязательно при добавлении и обновлении категории. Соблюдайте правила имён.

category.groupsarray

Полный список групп. Если его не передать, все группы категории удаляются.

category.groups[i].namestring

Имя группы. Обязательно для каждого элемента, кроме маркера удаления.

category.groups[i].removeboolean

Укажите true вместо name, чтобы удалить группу на этой позиции. Следующие группы остаются на своих позициях.

category.removeboolean

Укажите true, чтобы удалить категорию с индексом id.

reorderstring[]С версии 260922

Новый порядок групп. Укажите каждое переданное имя группы ровно один раз.

forceboolean

Разрешает удалить категорию, даже если после этого список пакетов пользователя станет пустым. По умолчанию: false.

Ответ

set-categorystring

ok при успехе, er, если команда отклонена.

errorstring

Есть при er. Подробнее в разделе Ошибки.

streamsarray

id и name изменённых потоков. Не возвращается, если сообщать об изменениях потоков нечего.

usersstring[]

Логины изменённых записей пользователей. Пользователей могут изменить только переименование и удаление категории. С ошибкой package list would be left empty содержит пользователей, из-за которых удаление невозможно.

Индекс категории

Заголовок раздела «Индекс категории»

id - индекс категории в массиве categories, начиная с 0. Если Genre и Language идут в таком порядке, у Genre будет id: 0, а у Language - id: 1. Потоки и настройки пользователей ссылаются на категории по имени.

Перед изменением прочитайте актуальный список: после удаления категории индексы следующих категорий сдвигаются. Устаревший индекс может указать на другую категорию или вернуть category not found.

Правила имён

Заголовок раздела «Правила имён»

Для имён категорий и групп действуют одни и те же правила:

  • Буквы, цифры, пробелы и - _ . & + /. Буквы могут быть из любого алфавита, поэтому Кино - такое же имя, как и остальные.
  • От 1 до 64 символов, без пробела в начале и в конце.
  • Имена групп должны быть уникальными внутри категории, а имена категорий - в списке.

Примеры допустимых имён: News, Sport 24, HD-Channels, Movies_EN, News & Sport, 24/7, Кино.

Ошибки

Заголовок раздела «Ошибки»

Отклонённая команда тоже возвращает HTTP 200, но с "set-category": "er" и причиной в error:

{ "set-category": "er", "error": "category not found" }

Проверка выполняется до применения изменений. Отклонённая команда ничего не меняет.

ОшибкаКак исправить
category is requiredПередайте объект category.
id must be a numberПередайте индекс категории числом.
id is required to remove a categoryУкажите текущий индекс категории.
category not foundПрочитайте актуальный список категорий и укажите существующий индекс.
category name is requiredПри добавлении и обновлении передайте category.name строкой. Для удаления имя не нужно.
category name is not validСоблюдайте правила имён.
category name already existsВыберите имя, которого нет у других категорий в списке.
group name is not valid (groups[i])Исправьте имя указанной группы по правилам имён.
duplicate group name (groups[i])Дайте каждой группе в категории своё имя.
reorder must be an array of group namesПередайте reorder массивом строк.
reorder must name every group of the category onceУкажите каждое переданное имя группы ровно один раз, без лишних имён.
package list would be left emptyИзмените пакеты перечисленных пользователей или явно разрешите неограниченный доступ через force: true.

Ошибки аутентификации и HTTP описаны в разделе Ответы API.

Добавить категорию

Заголовок раздела «Добавить категорию»

Создайте категорию Genre с двумя группами. Имя категории должно быть уникальным. Отправьте имя и группы без id:

Запрос

{
    "cmd": "set-category",
    "category": {
        "name": "Genre",
        "groups": [
            { "name": "News" },
            { "name": "Movies" }
        ]
    }
}

Ответ

{ "set-category": "ok" }

Категория добавляется в конец categories. Чтобы заполнить её группы, добавьте в них потоки.

Обновить категорию

Заголовок раздела «Обновить категорию»

Отправьте текущий id категории и полный объект категории. Так меняется имя категории и выполняются все изменения групп из разделов ниже.

Переименовать категорию

Заголовок раздела «Переименовать категорию»

Переименуйте Genre (id: 0) в Content и сохраните её группы. Отличия в старых версиях описаны в разделе Совместимость версий.

Запрос

{
    "cmd": "set-category",
    "id": 0,
    "category": {
        "name": "Content",
        "groups": [
            { "name": "News" },
            { "name": "Movies" }
        ]
    }
}

Ответ

{
    "set-category": "ok",
    "streams": [
        { "id": "a001", "name": "Channel 1" }
    ]
}

Привязки потоков и ссылки в settings.playlist_arrange, users[*].packages и users[*].interface.arrange переходят на Content. В ответе указан изменённый поток a001.

Добавить группу

Заголовок раздела «Добавить группу»

Добавьте Sport в Genre (id: 0). Новые группы добавляются в конец, чтобы позиции остальных не изменились. Чтобы поставить группу в другое место, используйте reorder.

Запрос

{
    "cmd": "set-category",
    "id": 0,
    "category": {
        "name": "Genre",
        "groups": [
            { "name": "News" },
            { "name": "Movies" },
            { "name": "Sport" }
        ]
    }
}

Ответ

{ "set-category": "ok" }

Группа добавлена. Потоки не меняются.

Переименовать группу

Заголовок раздела «Переименовать группу»

Переименуйте группу News категории Genre (id: 0) в Headlines:

Запрос

{
    "cmd": "set-category",
    "id": 0,
    "category": {
        "name": "Genre",
        "groups": [
            { "name": "Headlines" },
            { "name": "Movies" }
        ]
    }
}

Ответ

{
    "set-category": "ok",
    "streams": [
        { "id": "a001", "name": "Channel 1" }
    ]
}

Потоки из News переходят в Headlines. В ответе указан изменённый поток a001.

Удалить группу

Заголовок раздела «Удалить группу»

Удалите Movies из Genre (id: 0), поставив маркер на её позицию:

Запрос

{
    "cmd": "set-category",
    "id": 0,
    "category": {
        "name": "Genre",
        "groups": [
            { "name": "News" },
            { "remove": true },
            { "name": "Sport" }
        ]
    }
}

Ответ

{
    "set-category": "ok",
    "streams": [
        { "id": "a001", "name": "Channel 1" }
    ]
}

Потоки из Movies теряют привязку к Genre. В ответе указан изменённый поток a001.

Если в этом примере отправить только News, Sport, группа Movies будет переименована в Sport, а привязки к исходной третьей группе удалятся. Маркер сохраняет следующие группы на их исходных позициях, пока применяется обновление.

Чтобы удалить последнюю группу, просто не передавайте её. Чтобы удалить все группы, отправьте "groups": []. При удалении привязки сам поток сохраняется.

Изменить порядок групп

Заголовок раздела «Изменить порядок групп»

Переместите Sport в начало Genre (id: 0). Оставьте category.groups в сохранённом порядке, а новый порядок передайте в reorder. Нужна версия 260922 или новее.

Запрос

{
    "cmd": "set-category",
    "id": 0,
    "category": {
        "name": "Genre",
        "groups": [
            { "name": "News" },
            { "name": "Movies" },
            { "name": "Sport" }
        ]
    },
    "reorder": ["Sport", "News", "Movies"]
}

Ответ

{ "set-category": "ok" }

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

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

Удалить категорию

Заголовок раздела «Удалить категорию»

Удалите Genre (id: 0). Сами потоки сохраняются:

Запрос

{
    "cmd": "set-category",
    "id": 0,
    "category": { "remove": true }
}

Ответ

{
    "set-category": "ok",
    "streams": [
        { "id": "a001", "name": "Channel 1" }
    ]
}

Удаляются категория, привязки потоков к ней и ссылки в settings.playlist_arrange, users[*].packages и users[*].interface.arrange. В ответе указан изменённый поток a001. Индексы следующих категорий уменьшаются на единицу.

Удалить категорию, которая есть в пакетах пользователей

Заголовок раздела «Удалить категорию, которая есть в пакетах пользователей»

Список packages пользователя содержит имена категорий. Пустой список даёт доступ ко всем потокам. Если после удаления категории список пакетов пользователя станет пустым, запрос отклоняется:

Запрос

{
    "cmd": "set-category",
    "id": 0,
    "category": { "remove": true }
}

Ответ

{
    "set-category": "er",
    "error": "package list would be left empty",
    "users": ["operator"]
}

Ничего не меняется.

Перед повторной попыткой измените пакеты перечисленных пользователей. Если неограниченный доступ действительно нужен, повторите удаление с force на верхнем уровне запроса:

Запрос

{
    "cmd": "set-category",
    "id": 0,
    "category": { "remove": true },
    "force": true
}

Ответ

{
    "set-category": "ok",
    "users": ["operator"]
}

Категория удалена. Теперь у пользователя operator пустой список "packages": [], и он может смотреть все потоки.

Сохранение конфигурации и события

Заголовок раздела «Сохранение конфигурации и события»

После успешного изменения конфигурация сохраняется. Клиенты WebSocket получают set-stream для каждого потока, у которого изменилась привязка, а затем set-category.

Совместимость версий

Заголовок раздела «Совместимость версий»

Для reorder нужна версия 260922 или новее. Более ранние версии его игнорируют: пример с изменением порядка выше не меняет в них ни порядок групп, ни привязки.

Старые версии отличаются и в другом:

  • force игнорируется, поэтому клиенты не могут рассчитывать на описанную выше защиту списка пакетов.
  • В ответах нет streams и users.
  • Могут приниматься имена, которые описанная выше проверка отклоняет.
  • Переименование и удаление категории обновляют привязки потоков, но не меняют ссылки в настройках и записях пользователей.
© 2026 Cesbo
Написать намУсловияКонфиденциальность