HTTP
Referência do driver HTTP: ler ciclicamente endpoints HTTP e HTTPS como tags, credenciais, mapeamento de caminho, interpretação do corpo, escritas por PUT e tipos.
O driver HTTP lê ciclicamente endpoints HTTP genéricos como tags: um sensor de LAN com um servidor web minúsculo, um gateway que publica leituras em URLs fixas, um serviço seu. É o driver em modo cliente mais simples do produto: o Ganter Lab conecta ao equipamento com requisições GET simples e lê o corpo de cada resposta como um valor.
Duas propriedades traçam o limite do que ele serve:
- O transporte é o que o endereço declara. Um dispositivo cujo host está escrito
https://hostalcança o serviço dele por TLS; um host escrito sozinho é HTTP simples. De um jeito ou de outro o driver envia a credencial do dispositivo, um usuário e uma senha como HTTP Basic ou um token bearer, em toda requisição. O que os drivers AVEVA PI e Redfish ainda acrescentam para esses dois serviços é o vocabulário deles: caminhos PI e WebIds, árvores de recursos do Redfish, que este driver desconhece. - O corpo inteiro da resposta é o valor. O driver não é um extrator de campo JSON: uma tag numérica espera que o corpo seja o número puro.
Campos de conexão
| Campo | O que é | Formato | Padrão |
|---|---|---|---|
| Host | O nome de host ou endereço IP do endpoint. Escrito https://host, ele é alcançado por TLS, que é o que mantém uma credencial fora do cabo; um host sozinho é HTTP simples. |
Nome de host, IP, ou qualquer um dos dois com http:// ou https:// na frente |
vazio |
| Porta | A porta TCP. Zero significa a porta em que o transporte responde: 80 simples, 443 por HTTPS. | número de porta | 0 |
| Caminho do recurso | Um prefixo de caminho opcional posto na frente do caminho de toda tag, por exemplo api/v2. Em branco não prefixa nada. |
texto de caminho | em branco |
| Usuário | Conta para autenticação HTTP Basic, usada só quando nenhum token bearer está definido. Vazio (e sem token) deixa as requisições anônimas. | Texto livre | vazio |
| Senha | A senha que acompanha o usuário. Protegida em repouso por usuário do Windows; um segredo digitado sob outra conta do Windows aparece como ilegível e precisa ser digitado de novo. | Texto livre | vazio |
| Token bearer | Um token enviado como Authorization: Bearer … em toda requisição. Quando definido, ele prevalece sobre o par usuário e senha. Protegido em repouso do mesmo jeito. |
Texto do token | vazio |
Ao conectar, o driver verifica o endpoint com uma requisição HEAD ao endereço configurado, host mais caminho do recurso, recorrendo a GET quando o HEAD não está implementado; um endereço que responde com sucesso a qualquer um dos dois conta como alcançável. Um serviço cuja raiz responde 404 enquanto a API dele responde normalmente está, portanto, online, desde que o caminho do recurso aponte para a API. Em HTTPS, o certificado TLS do serviço precisa passar pela validação normal de certificados do Windows. Uma credencial num endereço que não declara TLS viaja sem criptografia, e a estação diz isso no diário do conector quando o dispositivo conecta. Cada requisição recebe dez segundos: um endpoint que aceita a conexão e depois não diz nada custa uma leitura, não o dispositivo inteiro, porque as outras tags do dispositivo são lidas na mesma passada. O intervalo de leitura é configurável: o padrão do dispositivo (1000 ms) vale para toda tag que não declare o próprio.
Endereçamento da tag
O campo Caminho da tag é o caminho da URL relativo ao caminho do recurso do dispositivo:
| Campo | O que faz | Valores | Padrão |
|---|---|---|---|
| Caminho | O caminho requisitado por esta tag. A URL completa é <transport>://<host>:<port>/<resource path>/<path>. |
Texto livre (obrigatório) | vazio |
Exemplo: host 192.168.0.40, caminho do recurso api, caminho da tag sensors/temp lê
http://192.168.0.40/api/sensors/temp.
Leituras
Cada ciclo faz GET na URL da tag e interpreta o corpo inteiro da resposta pelo tipo de dado declarado da tag:
| Tipo | Corpo aceito |
|---|---|
| Float | Um número, em formato invariante (21.5, ponto decimal, sem separador de milhar) |
| Int32 | Um inteiro (42) |
| Boolean | true ou false |
| String | Qualquer coisa; o corpo é o valor tal como está (um documento JSON chega como o texto bruto dele) |
Um corpo que o tipo declarado não consegue interpretar, ou um código de status que não é de sucesso, lê como leitura que falhou: a tag vai a qualidade ruim e a política de falha de leitura dela decide o que é apresentado, como descrito na página Connector.
Escritas
Tags com modo de acesso gravável escrevem com PUT na mesma URL: o corpo é
o valor em JSON, enviado com o tipo de conteúdo application/json. Um número vai como
literal puro (42.5), um booleano como true ou false, e texto vai entre aspas
("automatic"). O endpoint decide o que fazer com isso; um status que não é de sucesso
lê como escrita que falhou. Como em todo o resto, a caixa de escrita recebe o valor de engenharia e os
estágios de conversão da tag são revertidos antes de o valor bruto ir para o barramento, como descrito
na página Connector.
Tipos de dado suportados
Boolean, Int32, Float e String.
Comandos
Uma tag lê um valor; um comando pede ao serviço que ele faça algo. Declare cada um no dispositivo, no cartão Comandos da página dele: um nome, o caminho a que ele é enviado por POST (sob o endereço do próprio dispositivo, exatamente como o caminho de uma tag) e, opcionalmente, o nome do único valor que ele recebe. O verbo Executar da linha o envia e relata o que o serviço respondeu, e o comando também vira um método no dispositivo, dentro do espaço de endereços OPC UA desta estação, então qualquer coisa que consiga chamar um método consegue dispará-lo. O valor que você digita é enviado como corpo da requisição, tal como foi escrito.
O que o serviço responde é o resultado do comando. Um status que o serviço devolve fora da faixa de sucesso é o serviço recusando o comando, não a conexão falhando: a recusa nomeia o status e cita o que o serviço disse junto ("HTTP 500: the burner is locked out"), e nada mais no dispositivo é perturbado por isso.
Descoberta
O driver não tem varredura de descoberta. Adicione cada endpoint por host e cada valor pelo caminho dele; o fluxo de adicionar um dispositivo está descrito na página Connector.