API de Categorías

Usa categorías y grupos para organizar los streams en las listas de reproducción y en la interfaz web, y para controlar qué streams puede ver un usuario. Una categoría contiene una lista ordenada de grupos, como News y Movies en Genre. Un stream puede pertenecer como máximo a un grupo de cada categoría.

• Para leer las categorías, descarga la configuración y mira su array categories. El orden de este array es el orden de visualización.
• Para asignar un stream a un grupo, define su campo groups, que asocia nombres de categoría con nombres de grupo, y envía el stream completo con set-stream.
• Para añadir, cambiar o eliminar categorías y grupos, usa set-category.

Consulta Cómo llamar métodos de la API para la autenticación y las rutas de control personalizadas.

Establecer categoría

Añade, actualiza o elimina una categoría con sus grupos.

POST/control/set-category

admin

Solicitud

idnumber

Índice actual de la categoría, empezando en 0. Obligatorio para actualizar o eliminar una categoría. Omítelo para añadir una categoría.

categoryobjectobligatorio

Objeto de categoría completo. Para eliminar la categoría, envía {"remove": true}.

category.namestring

Nombre de la categoría. Obligatorio para añadir o actualizar una categoría. Sigue las reglas de nombres.

category.groupsarray

Lista completa de grupos. Si la omites, se borran todos los grupos de la categoría.

category.groups[i].namestring

Nombre del grupo. Obligatorio en cada entrada, salvo en un marcador de eliminación.

category.groups[i].removeboolean

Ponlo en true en lugar de name para eliminar el grupo en esta posición. Los grupos siguientes conservan sus posiciones.

category.removeboolean

Ponlo en true para eliminar la categoría indicada por id.

reorderstring[]Desde 260922

Nuevo orden de los grupos. Incluye cada nombre de grupo enviado exactamente una vez.

forceboolean

Permite eliminar la categoría aunque deje vacía la lista de paquetes de un usuario. Predeterminado: false.

Respuesta

set-categorystring

ok si tiene éxito, er si el comando se rechaza.

errorstring

Presente con er. Consulta Errores.

streamsarray

id y name de los streams modificados. Se omite cuando no hay cambios de streams que informar.

usersstring[]

Logins de los registros de usuario modificados. Solo renombrar o eliminar una categoría puede modificar usuarios. Con el error package list would be left empty, lista los usuarios que bloquean la eliminación.

Índice de categoría

id es el índice de la categoría en el array categories, empezando en 0. Con Genre y Language en este orden, Genre tiene id: 0 y Language tiene id: 1. Los streams y la configuración de usuarios hacen referencia a las categorías por su nombre.

Lee la lista actual antes de editar: al eliminar una categoría, los índices posteriores se desplazan. Un índice desactualizado puede seleccionar otra categoría o devolver category not found.

Reglas de nombres

Las mismas reglas se aplican a los nombres de categorías y de grupos:

• Letras, dígitos, espacios y - _ . & + /. Valen letras de cualquier alfabeto, así que Кино es un nombre como cualquier otro.
• De 1 a 64 caracteres, sin espacios al principio ni al final.
• Los nombres de grupo deben ser únicos dentro de una categoría, y los nombres de categoría, únicos en la lista.

Ejemplos válidos: News, Sport 24, HD-Channels, Movies_EN, News & Sport, 24/7, Кино.

Errores

Un comando rechazado también devuelve HTTP 200, con "set-category": "er" y el motivo en error:

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

La validación se hace antes de aplicar los cambios. Un comando rechazado no cambia nada.

Error	Cómo solucionarlo
category is required	Incluye un objeto category.
id must be a number	Envía un índice de categoría numérico.
id is required to remove a category	Incluye el índice actual de la categoría.
category not found	Lee las categorías actuales y usa un índice que exista.
category name is required	Incluye category.name como cadena al añadir o actualizar. Para eliminar no hace falta nombre.
category name is not valid	Sigue las reglas de nombres.
category name already exists	Usa un nombre que no tenga ninguna otra categoría de la lista.
group name is not valid (groups[i])	Corrige el nombre del grupo indicado según las reglas de nombres.
duplicate group name (groups[i])	Da a cada grupo un nombre distinto dentro de la categoría.
reorder must be an array of group names	Envía reorder como un array de cadenas.
reorder must name every group of the category once	Incluye cada nombre de grupo enviado exactamente una vez, sin nombres de más.
package list would be left empty	Actualiza los paquetes de los usuarios listados o permite explícitamente el acceso sin restricciones con force: true.

Para los errores de autenticación y HTTP, consulta Respuestas de la API.

Añadir una categoría

Crea Genre con dos grupos. El nombre de la categoría debe ser único. Envía el nombre y los grupos sin id:

Solicitud

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

Respuesta

{ "set-category": "ok" }

La categoría se añade al final de categories. Para llenar sus grupos, asígnales streams.

Actualizar una categoría

Envía su id actual y el objeto de categoría completo. Úsalo para cambiar el nombre de la categoría y para todos los cambios de grupos que se describen abajo.

Precaución

Una actualización reemplaza el objeto de la categoría. Incluye siempre los grupos que quieras conservar. Si omites groups, se vacía la lista y se eliminan las asignaciones de streams a sus grupos definidos.

Los grupos se identifican por su posición: cambiar un nombre renombra el grupo que está en esa posición. Para cambiar solo el orden de visualización, usa reorder.

Renombrar una categoría

Renombra Genre (id: 0) a Content y conserva sus grupos. Consulta Compatibilidad de versiones para ver las diferencias en versiones anteriores.

Solicitud

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

Respuesta

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

Las asignaciones de streams y las referencias en settings.playlist_arrange, users[*].packages y users[*].interface.arrange pasan a Content. La respuesta lista el stream modificado a001.

Añadir un grupo

Añade Sport al final de Genre (id: 0). Los grupos nuevos van al final para mantener las posiciones existentes. Para colocarlo en otro sitio, usa reorder.

Solicitud

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

Respuesta

{ "set-category": "ok" }

El grupo se añade. Ningún stream cambia.

Renombrar un grupo

Renombra News en Genre (id: 0) a Headlines:

Solicitud

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

Respuesta

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

Los streams de News pasan a Headlines. La respuesta lista el stream modificado a001.

Eliminar un grupo

Elimina Movies de Genre (id: 0) con un marcador en su posición:

Solicitud

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

Respuesta

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

Los streams de Movies pierden su asignación en Genre. La respuesta lista el stream modificado a001.

Si en este ejemplo envías solo News y Sport, el grupo Movies se renombra a Sport y se eliminan las asignaciones al tercer grupo original. El marcador mantiene los grupos siguientes en sus posiciones originales mientras se aplica la actualización.

Para eliminar el último grupo, omite su entrada. Para eliminar todos los grupos, envía "groups": []. Eliminar una asignación no elimina el stream.

Reordenar grupos

Mueve Sport al principio de Genre (id: 0). Mantén category.groups en su orden guardado y pon el nuevo orden en reorder. Requiere la versión 260922 o posterior.

Solicitud

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

Respuesta

{ "set-category": "ok" }

Solo cambia el orden de los grupos. Las asignaciones de streams no cambian.

reorder debe contener cada nombre de grupo enviado exactamente una vez.

Eliminar una categoría

Elimina Genre (id: 0). Los streams se conservan:

Solicitud

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

Respuesta

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

Se eliminan la categoría, las asignaciones de streams a ella y las referencias en settings.playlist_arrange, users[*].packages y users[*].interface.arrange. La respuesta lista el stream modificado a001. Las categorías posteriores suben un índice.

Eliminar una categoría usada en paquetes de usuarios

La lista packages de un usuario contiene nombres de categorías. Una lista vacía da acceso a todos los streams. Si al eliminar la categoría la lista de paquetes de un usuario queda vacía, la solicitud se rechaza:

Solicitud

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

Respuesta

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

No se cambia nada.

Actualiza los paquetes de los usuarios listados antes de reintentar o, si quieres dar acceso sin restricciones, repite la eliminación con force en el nivel superior:

Solicitud

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

Respuesta

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

La categoría se elimina. El usuario operator ahora tiene "packages": [] y puede ver todos los streams.

Actualización de la configuración y eventos

La configuración se guarda después de un cambio correcto. Los clientes WebSocket reciben set-stream por cada stream cuya asignación cambió y, después, set-category.

Compatibilidad de versiones

reorder requiere la versión 260922 o posterior. Las versiones anteriores lo ignoran; el ejemplo de reordenación de arriba deja sin cambios el orden de sus grupos y las asignaciones.

Las versiones anteriores también se diferencian en lo siguiente:

• force se ignora, así que los clientes no pueden contar con la protección de la lista de paquetes descrita arriba.
• Las respuestas omiten streams y users.
• Pueden aceptarse nombres que la validación descrita arriba rechaza.
• Renombrar o eliminar una categoría actualiza las asignaciones de streams, pero deja sin cambios las referencias en los ajustes y en los registros de usuarios.