API de categorias

Use categorias e grupos para organizar os streams nas playlists e na interface web, e para controlar quais streams cada usuário pode assistir. Uma categoria contém uma lista ordenada de grupos, como News e Movies em Genre. Um stream pode pertencer a no máximo um grupo em cada categoria.

• Para ler as categorias, baixe a configuração e veja o array categories. A ordem nesse array é a ordem de exibição.
• Para atribuir um stream a um grupo, defina o campo groups dele, que associa nomes de categorias a nomes de grupos, e envie o stream completo com set-stream.
• Para adicionar, alterar ou remover categorias e grupos, use set-category.

Sobre autenticação e caminhos de controle personalizados, veja Como chamar métodos da API.

Definir categoria

Adiciona, atualiza ou remove uma categoria com os grupos dela.

POST/control/set-category

admin

Request

idnumber

Índice atual da categoria, a partir de 0. Obrigatório para atualizar ou remover uma categoria. Omita para adicionar uma categoria.

categoryobjectrequired

Objeto completo da categoria. Para remover a categoria, envie {"remove": true}.

category.namestring

Nome da categoria. Obrigatório para adicionar ou atualizar uma categoria. Siga as regras de nomes.

category.groupsarray

Lista completa de grupos. Omitir este campo apaga todos os grupos da categoria.

category.groups[i].namestring

Nome do grupo. Obrigatório em todas as entradas, exceto em um marcador de remoção.

category.groups[i].removeboolean

Defina como true no lugar de name para remover o grupo nesta posição. Os grupos seguintes mantêm as suas posições.

category.removeboolean

Defina como true para remover a categoria indicada por id.

reorderstring[]Since 260922

Nova ordem dos grupos. Inclua cada nome de grupo enviado exatamente uma vez.

forceboolean

Permite remover a categoria mesmo que a lista de pacotes de um usuário fique vazia. Padrão: false.

Response

set-categorystring

ok em caso de sucesso, er se o comando for rejeitado.

errorstring

Presente junto com er. Veja Erros.

streamsarray

id e name dos streams alterados. Omitido quando não há alterações de streams a informar.

usersstring[]

Logins dos registros de usuários alterados. Só renomear ou remover uma categoria pode alterar usuários. Com o erro package list would be left empty, lista os usuários que impedem a remoção.

Índice da categoria

id é o índice da categoria no array categories, a partir de 0. Com Genre e Language nessa ordem, Genre tem id: 0 e Language tem id: 1. Os streams e as configurações de usuário se referem às categorias pelo nome.

Leia a lista atual antes de editar: remover uma categoria desloca os índices das categorias seguintes. Um índice desatualizado pode selecionar outra categoria ou retornar category not found.

Regras de nomes

As mesmas regras valem para nomes de categorias e de grupos:

• Letras, dígitos, espaços e - _ . & + /. Letras de qualquer alfabeto valem, então Кино é um nome como qualquer outro.
• De 1 a 64 caracteres, sem espaço no início nem no fim.
• Os nomes de grupos devem ser únicos dentro de uma categoria, e os nomes de categorias, únicos na lista.

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

Erros

Um comando rejeitado também retorna HTTP 200, com "set-category": "er" e o motivo em error:

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

A validação acontece antes de as alterações serem aplicadas. Um comando rejeitado não altera nada.

Erro	Como corrigir
category is required	Inclua um objeto category.
id must be a number	Envie um índice de categoria numérico.
id is required to remove a category	Inclua o índice atual da categoria.
category not found	Leia as categorias atuais e use um índice que exista.
category name is required	Inclua category.name como string ao adicionar ou atualizar. A remoção não precisa de nome.
category name is not valid	Siga as regras de nomes.
category name already exists	Dê à categoria um nome que nenhuma outra categoria da lista use.
group name is not valid (groups[i])	Corrija o nome do grupo indicado seguindo as regras de nomes.
duplicate group name (groups[i])	Dê a cada grupo um nome diferente dentro da categoria.
reorder must be an array of group names	Envie reorder como um array de strings.
reorder must name every group of the category once	Inclua cada nome de grupo enviado exatamente uma vez, sem nomes extras.
package list would be left empty	Atualize os pacotes dos usuários listados ou permita explicitamente o acesso sem restrições com force: true.

Para erros de autenticação e HTTP, veja Respostas da API.

Adicionar uma categoria

Crie Genre com dois grupos. O nome da categoria deve ser único. Envie o nome e os grupos sem id:

Request

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

Response

{ "set-category": "ok" }

A categoria é adicionada ao final de categories. Para preencher os grupos, atribua streams a eles.

Atualizar uma categoria

Envie o id atual e o objeto completo da categoria. Use isso para mudar o nome da categoria e para todas as alterações de grupos abaixo.

Cuidado

Uma atualização substitui o objeto da categoria. Sempre inclua os grupos que você quer manter. Omitir groups esvazia a lista e remove as atribuições de streams aos grupos que ela definia.

Os grupos são identificados pela posição: mudar um nome renomeia o grupo naquela posição. Para mudar só a ordem de exibição, use reorder.

Renomear uma categoria

Renomeie Genre (id: 0) para Content e mantenha os grupos. As diferenças nas versões antigas estão em Compatibilidade de versões.

Request

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

Response

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

As atribuições de streams e as referências em settings.playlist_arrange, users[*].packages e users[*].interface.arrange passam para Content. A resposta lista o stream alterado a001.

Adicionar um grupo

Adicione Sport ao final de Genre (id: 0). Novos grupos vão para o final para manter as posições existentes. Para colocá-lo em outro lugar, use reorder.

Request

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

Response

{ "set-category": "ok" }

O grupo é adicionado. Nenhum stream muda.

Renomear um grupo

Renomeie News em Genre (id: 0) para Headlines:

Request

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

Response

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

Os streams de News passam para Headlines. A resposta lista o stream alterado a001.

Remover um grupo

Remova Movies de Genre (id: 0) com um marcador na posição dele:

Request

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

Response

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

Os streams de Movies perdem a atribuição em Genre. A resposta lista o stream alterado a001.

Enviar só News, Sport neste exemplo renomearia Movies para Sport e removeria as atribuições ao terceiro grupo original. O marcador mantém os grupos seguintes nas posições originais enquanto a atualização é aplicada.

Para remover o último grupo, omita a entrada dele. Para remover todos os grupos, envie "groups": []. Remover uma atribuição não apaga o stream.

Reordenar grupos

Mova Sport para o início de Genre (id: 0). Mantenha category.groups na ordem salva e coloque a nova ordem em reorder. Requer a versão 260922 ou posterior.

Request

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

Response

{ "set-category": "ok" }

Só a ordem dos grupos muda. As atribuições de streams continuam as mesmas.

reorder deve conter cada nome de grupo enviado exatamente uma vez.

Remover uma categoria

Remova Genre (id: 0). Os streams em si são mantidos:

Request

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

Response

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

A categoria, as atribuições de streams a ela e as referências em settings.playlist_arrange, users[*].packages e users[*].interface.arrange são removidas. A resposta lista o stream alterado a001. O índice de cada categoria seguinte diminui em 1.

Remover uma categoria usada em pacotes de usuários

A lista packages de um usuário contém nomes de categorias. Uma lista vazia dá acesso a todos os streams. Se a remoção da categoria deixar vazia a lista de pacotes de algum usuário, a requisição é rejeitada:

Request

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

Response

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

Nada é alterado.

Atualize os pacotes dos usuários listados antes de tentar de novo. Se o acesso sem restrições for intencional, repita a remoção com force no nível superior:

Request

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

Response

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

A categoria é removida. O usuário operator agora tem "packages": [] e pode assistir a todos os streams.

Atualizações da configuração e eventos

A configuração é salva depois de uma alteração bem-sucedida. Os clientes WebSocket recebem set-stream para cada stream cuja atribuição mudou e, em seguida, set-category.

Compatibilidade de versões

reorder requer a versão 260922 ou posterior. As versões anteriores ignoram esse campo: o exemplo de reordenação acima não muda nelas a ordem dos grupos nem as atribuições.

As versões antigas também diferem nestes pontos:

• force é ignorado, então os clientes não podem contar com a proteção da lista de pacotes descrita acima.
• As respostas não trazem streams nem users.
• Nomes rejeitados pela validação descrita acima podem ser aceitos.
• Renomear e remover categorias atualiza as atribuições de streams, mas não altera as referências nas configurações e nos registros de usuários.