Gerenciamento pela API HTTP

Tudo o que a interface web faz, o nó sabe fazer por uma requisição de fora: a API HTTP lê e altera a configuração do serviço em funcionamento e devolve o seu estado. Junto com a interface web, são as únicas interfaces que aplicam uma alteração imediatamente e informam o resultado.

A página dá uma visão geral: onde fica a API, como ela é organizada, como chegam os erros e em que difere de editar o arquivo de configuração. A referência de cada requisição e de cada chave está em documentos separados (Documentos de referência); aqui ela não é repetida.

Acesso

A API responde no mesmo servidor web que a interface de administração. Na configuração fornecida é a porta 8808; se nenhuma porta estiver indicada nas configurações, o serviço usa o valor interno 43971. A porta TLS é 43981, mas logo após a instalação o TLS está desligado e essa porta não é escutada (Configurações iniciais). A API não tem endereço nem prefixo próprio do tipo /api.

• HTTP e HTTPS são equivalentes. O redirecionamento da porta aberta para TLS afeta apenas as páginas da interface; as requisições da API continuam funcionando por ambos os protocolos.

• A autenticação é HTTP Digest, com as mesmas contas da interface web e os mesmos papéis: Admin — acesso total, Restricted admin — ler tudo e pausar um fluxo, sua entrada ou sua saída, Viewer — somente leitura. Uma gravação feita fora do próprio papel é recusada. Em lugar da senha, a sessão pode ser apresentada com uma chave de login automático — cookie, cabeçalho X-Auth-Token ou parâmetro ?auth-token=.

• As requisições do próprio nó não são autenticadas. Uma chamada que chegou pela interface de loopback (127.0.0.1, ::1) passa sem Digest e recebe o papel Admin. Isso não pode ser desligado; não existe configuração para tal. A concessão tem limites: ela não pode ser reivindicada de fora do nó — atribuir-se um endereço de loopback por um cabeçalho não funciona — e é retirada para uma requisição entre origens, pois do contrário uma página web aberta no nó comandaria toda a API através do 127.0.0.1 sem credencial alguma.

  Há uma única consequência diante da qual agir: qualquer processo no nó dispõe da configuração sem senha. Se um proxy reverso for colocado à frente da API, aponte-o para um endereço não loopback do mesmo nó — então a autenticação funciona normalmente. Um proxy que acessa o 127.0.0.1 distribui acesso total a todos cujas requisições ele repassa.

• Há apenas dois métodos — GET e POST. A qualquer outro método chega a resposta «método não suportado»; a exceção é a requisição prévia OPTIONS do navegador, à qual o servidor responde com uma permissão se a origem da requisição for admitida.

Aviso

O papel restringe apenas a escrita. A verificação do papel é feita para as requisições POST; a leitura não é restringida por nada, e os valores voltam como estão, sem mascaramento. Uma conta com o papel Viewer vê todas as senhas, os segredos do Meshwork, as frases secretas dos transportes e as chaves de proteção de conteúdo — e exportar uma cópia de segurança das configurações também é uma leitura, ou seja, toda a configuração em uma única requisição. O papel Viewer limita a possibilidade de alterar o nó, não o acesso aos seus segredos: crie-o sabendo disso.

A distribuição dos fluxos e do guia de programação funciona em portas próprias e não gerencia as configurações (Configurações iniciais).

De que a API é composta

Família	Finalidade
/config/…	Leitura e alteração da configuração. A árvore de requisições repete, no essencial, a estrutura do arquivo de configuração: uma seção do arquivo é um nó da árvore (Estrutura do documento). Há divergências: o array de armazenamentos do arquivo é endereçado como /config/dvr-storage e os conjuntos de canais do guia de programação como /config/epg-channel-set, embora no arquivo eles fiquem dentro de dvr-storage-list e de epg-server.
/data/…	O estado do serviço em funcionamento, sobretudo para leitura: os fluxos e suas cadeias, o equipamento, o guia de programação, o monitor do sistema, o log, as informações da licença. Algumas requisições alteram o estado — zerar as estatísticas, iniciar uma varredura, baixar um alerta; dessas, apenas uma altera a configuração: retirar um peer Meshwork da visão geral do domínio. Há exemplos prontos de requisições em Grelha diária em JSON e Assistente de reclamações.
/schema/…	Listas de referência em formato JSON, somente para leitura: os tipos de entrada e de saída suportados por esta compilação, os idiomas, as placas de recepção e os dispositivos de transcodificação encontrados, a escala de importância e os códigos de alarme. Não têm relação com o arquivo de esquema das configurações (Verificação pelo JSON Schema).
Endereços avulsos	Algumas requisições de serviço fora dessas árvores: reiniciar o serviço, exportar e restaurar uma cópia de segurança das configurações, a lista de interfaces de rede, encerrar a sessão.

Como chegam os erros

Um erro de nível de aplicação é devolvido pela API com código HTTP 200 e um campo result diferente de zero no corpo da resposta: um valor fora da faixa, uma verificação recusada, uma tentativa de gravar uma chave imutável, a recusa de gravar uma chave inacessível a esse papel.

Um script que verifica apenas o código HTTP tomará, portanto, todas essas recusas por sucessos, uma após a outra. Analise o corpo da resposta.

Códigos diferentes de 200 também ocorrem, mas significam outra coisa: 401 — a autenticação não passou, 403 — o papel não é admitido à própria requisição, 404 — não existe tal requisição, 405 — o método não é suportado. Uma recusa por papel chega, assim, de duas maneiras diferentes: a requisição inteira é rejeitada com o código 403, enquanto uma chave isolada não admitida volta em uma resposta comum com um result diferente de zero.

Um valor fora da faixa permitida a API rejeita. É nisso que ela difere da leitura do arquivo de configuração, onde esse valor é levado ao limite da faixa (É aceito, mas não como pretendia quem editou).

Uma chave desconhecida a API não rejeita: ela é ignorada exatamente como na leitura do arquivo, a resposta chega com result 0 e o único rastro fica no log do nó. Por isso um erro de digitação no nome de uma chave também não é visto aqui — os nomes das chaves são verificados de antemão pelo esquema (Verificação pelo JSON Schema).

Alterações que exigem um reinício

Duas alterações só entram em vigor após reiniciar o serviço: a ativação da licença e a restauração das configurações a partir de uma cópia de segurança. Nenhuma das duas deixa o reinício a critério do operador: aceito o arquivo, o serviço se reinicia sozinho depois de cerca de quatro segundos — não dá para adiar, e durante o reinício o nó fica indisponível. As respostas dessas duas requisições não trazem o campo reboot; nas respostas JSON da API de configuração ele significa que o nó já está indo para o reinício, e não que o reinício aguarda um comando. Do mesmo modo, por si só, reinicia-se o nó cuja licença expirou. Reiniciar o serviço por vontade própria é possível com uma requisição separada, pela interface web ou com o comando sudo systemctl restart pss.

Alterar as portas de escuta e ligar o TLS não exigem reiniciar o serviço: ele fecha o socket de escuta e o abre de novo, e não haverá campo reboot na resposta. As conexões abertas nessa porta são rompidas nesse momento, e daí em diante é preciso conectar-se já na nova porta.

A API ou o arquivo de configuração

	HTTP API	O arquivo pss.json
Quando entra em vigor	Imediatamente	A partir da próxima inicialização do serviço
Estado do serviço	Em funcionamento	Parado
Resultado	É devolvido na resposta	Visível apenas no log após a inicialização
Valor fora da faixa	É rejeitado	É levado ao limite
Chave desconhecida	Ignorada em silêncio, result 0	Ignorada em silêncio, a menos que se leia o log
Para que é conveniente	Alterações pontuais, automação, observação	Edições em massa, transferência das configurações entre nós e versões

Editar o arquivo de um serviço em funcionamento é inútil e perigoso: o serviço sobrescreve o pss.json com o que mantém na memória, e faz isso conforme o seu próprio cronograma — a edição desaparecerá sem uma única mensagem. Pare o serviço e verifique o arquivo pelo esquema antes de iniciá-lo; o procedimento está em Editar, verificar e transferir as configurações.

Documentos de referência

Documento	Conteúdo
http_config_api.txt	A referência da API de configuração: o protocolo, as operações, a árvore /config e a descrição item a item de cada chave — tipo, restrições, valor padrão.
http_data_api.txt	A referência da API de estado e estatísticas: a árvore /data, os formatos de resposta, as requisições ao log e às bases.
pss_config_file.txt	A referência do formato do arquivo de configuração. A sua exposição para o operador é O arquivo de configuração pss.json.
pss_config_editing.txt	Os procedimentos de edição, verificação e transferência das configurações. A sua exposição é Editar, verificar e transferir as configurações.
pss.schema.json, pss.compat.schema.json	Uma descrição legível por máquina do arquivo de configuração em formato JSON Schema (Verificação pelo JSON Schema).

Os documentos são escritos em inglês. Eles não fazem parte do pacote: não estão no nó e não é preciso procurá-los lá.

Tudo isso está publicado no site da documentação, com um diretório para cada versão do produto:

https://doc2.pstreamer.tv/reference/      quatro documentos de referência
https://doc2.pstreamer.tv/schema/         dois esquemas

Use o diretório da versão que você tem instalada: a referência de outra edição não descreve o seu nó.

Aviso

A compatibilidade retroativa não é garantida. Uma atualização pode alterar tanto a API HTTP quanto o esquema e o formato do arquivo de configuração: a composição e os nomes das chaves, as faixas de valores, a forma das requisições e das respostas. Verifique novamente os scripts que trabalham com a API após cada atualização, e pegue os documentos de referência e o esquema da mesma versão da compilação instalada.

Disso decorrem três regras para quem escreve a sua própria integração:

• Vincule-se à versão para a qual o script foi escrito, e verifique-a na inicialização.

• Leia de volta depois de gravar. Uma chave que já não existe na nova compilação não é recusada, e sim ignorada, e a resposta informa sucesso: justamente a requisição que apanharia esse desaparecimento é a que não o apanha.

• Um atributo ausente na resposta significa «esta versão não o informa», e não zero. Caso contrário, um indicador removido ou renomeado numa atualização transforma-se numa medição verossímil de algo que não existe.