Integração HTTP
O protocolo HTTP integra dispositivos e serviços que utilizam HTTP simples: API REST, serviços cloud com uma API local ou relés de rede simples. Funciona em dois sentidos:
- Pedidos de saída — quando o valor de um widget muda, o HyperVisu envia um pedido (controlo de dispositivo ou chamada de webhook).
- Consulta periódica — o HyperVisu consulta periodicamente um URL e extrai um valor da resposta para um objeto do widget.
Ligações. Ative primeiro HTTP Protocol na página Services (ver «Serviços e protocolos»); está desativado num servidor novo. O HTTP suporta várias ligações: uma por Base URL, cada uma com os seus próprios Poll Interval (seconds), Timeout (ms) e autenticação (ver «Ligações»). O tempo limite é expresso em milissegundos, de 1000 a 120000; se ficar vazio, um pedido espera 30 segundos.
Escolha o Authentication Type exigido pela API. Alterar o tipo limpa todos os campos de credenciais.
| Authentication Type | Dados a fornecer | Forma de envio |
|---|---|---|
| None | Sem credenciais. | Nada é acrescentado. |
| API Key (Header) | Header Name e API Key. | Um cabeçalho com esse nome e a chave. |
| API Key (Query Parameter) | Query Parameter e API Key. | Acrescentados ao URL de cada pedido. |
| Basic Authentication | Username e Password. | O cabeçalho de autorização Basic padrão. |
| Bearer Token | Bearer Token. | O cabeçalho de autorização Bearer padrão. |
| Custom Headers | Uma linha por cabeçalho, com nome e valor; Add Header acrescenta uma linha. | Todas as linhas, em cada pedido. |
Preencha os dois campos de cada par: um par com um campo vazio não é enviado. API Key, Password e Bearer Token são ocultados no editor; os valores introduzidos em Custom Headers são apresentados em texto simples.
Uma ligação HTTP não tem botão Test. O estado permanece State unknown até um objeto associado trocar um pedido; Connected significa então que o último pedido foi aceite e No reply since aparece após um pedido falhado.
📘 Nota: Um intervalo de consulta de
0torna a ligação apenas de escrita — não são feitas consultas, só são enviados pedidos de saída. Um intervalo vazio também significa que o endpoint nunca é consultado: introduza o valor, o60cinzento é apenas uma sugestão.
Associar um objeto. Por objeto, defina Path e HTTP Method e, para valores consultados, como extrair a leitura da resposta com Parse Method e Parse Path:
- JSON — um caminho com sintaxe de pontos e arrays, por exemplo
data.sensors[0].temperature. Um índice negativo como[-1]lê o último elemento; filtros e caracteres universais não são suportados. - Pattern Matching — para respostas que não sejam JSON. Parse Path tem de começar por
PATTERN=, por exemploPATTERN=Temp:\s\v. Alterar o método de análise limpa Parse Path, pelo que deve introduzi-lo depois de escolher o método.
Para pedidos de saída, defina HTTP Method como POST ou PUT e escolha Content Type. Request Body Template é um modelo em que ${value} é substituído pelo valor enviado, por exemplo {"state": ${value}}.
📘 Nota: A consulta periódica envia sempre um GET para o Path do objeto. Um objeto POST ou PUT só envia um pedido quando o seu valor muda.
Exemplo prático — qualidade do ar exterior a partir da API de um sensor local
Um monitor local de qualidade do ar disponibiliza GET http://192.168.1.140/api/current, devolve {"pm25": 8.4, "aqi": 35} e exige a chave API num cabeçalho X-Api-Key.
- Crie uma ligação HTTP: Base URL
http://192.168.1.140, Poll Interval (seconds)60, Timeout (ms)5000, Authentication Type API Key (Header), Header NameX-Api-Key, a chave em API Key (ver «Ligações»). - Em Devices, adicione um widget Analog Input «Qualidade do ar». Em Protocol, selecione a sua ligação HTTP, apresentada com o nome que lhe atribuiu.
- No respetivo objeto de valor, defina Path como
/api/current, mantenha HTTP Method em GET e Parse Method em JSON e introduzaaqiem Parse Path. - Clique em Save object, depois em Apply changes na barra lateral e confirme. A leitura é atualizada a cada minuto; defina as unidades e casas decimais no objeto (ver «Definições de objetos, registo e notificações»).
- Após a consulta seguinte, verifique se a ligação apresenta Connected na página Connections e compare o widget com a resposta real da API.
Associação HTTP
Os objetos HTTP também são configurados na caixa de diálogo de definições do objeto (ver «Definições de objetos, registo e notificações»). A secção HTTP define um pedido por objeto:
| Campo | Descrição |
|---|---|
| Path | Acrescentado ao URL base da ligação (por exemplo weather?q=London). |
| HTTP Method | GET, POST ou PUT. |
| Content Type | Para POST/PUT: JSON, TEXT ou FORM. JSON e FORM definem o cabeçalho de tipo de conteúdo correspondente; TEXT não envia nenhum. |
| Parse Method | JSON — a resposta é JSON e Parse Path identifica o valor. Pattern Matching — a resposta é texto e Parse Path contém um padrão. A ajuda de sintaxe integrada documenta ambos. Alterar o método de análise limpa Parse Path, pelo que deve escolher primeiro o método. |
| Parse Path | Com JSON: um caminho simples — notação por pontos (data.power), índice de array (sensors[0]), índice negativo ([-1] para o último elemento) e prefixo opcional $.. Filtros e caracteres universais não são suportados. Com Pattern Matching: o padrão, que tem de começar por PATTERN= — por exemplo PATTERN=Temp:\s\v. |
| Request Body Template | Para POST/PUT: o corpo a enviar, com ${value} como marcador do valor escrito — por exemplo {"state":${value}}. |
A leitura utiliza o intervalo de consulta da ligação; um intervalo de 0 torna o endpoint apenas de escrita (ver «Ligações»). A consulta periódica envia sempre um GET para o Path do objeto; um objeto POST ou PUT só envia o seu pedido quando o valor muda. O capítulo HTTP inclui um exemplo prático.