# HTTP

> Referencia del driver HTTP: sondear endpoints HTTP y HTTPS como tags, las credenciales, el mapeo de rutas, la interpretación del cuerpo, las escrituras PUT y los tipos.

El driver HTTP sondea **endpoints HTTP genéricos** como tags: un sensor de red local
con un servidor web diminuto, una puerta de enlace que publica lecturas en URL fijas, un
servicio propio. Es el driver en modo cliente más simple del producto: **Ganter Lab se
conecta al equipo** con peticiones GET simples y lee el cuerpo de cada respuesta como un solo
valor.

Dos propiedades trazan la raya alrededor de para qué sirve:

- El transporte es **la elección del propio dispositivo**. Un dispositivo llega a su servicio
  sobre TLS hasta que su casilla **Enviar por HTTP sin cifrar** diga otra cosa, y un host
  escrito con `http://` o `https://` enfrente mueve esa casilla y se guarda como el host
  solito, así que los dos nunca se contradicen.
  De cualquiera de las dos maneras, el driver manda la credencial del dispositivo en cada
  petición, un nombre de usuario con su contraseña como HTTP Basic o un token de portador.
  Lo que los drivers [AVEVA PI](driver-aveva-pi) y [Redfish](driver-redfish) todavía ponen
  para esos dos servicios es su vocabulario: rutas PI y WebId, árboles de recursos de
  Redfish, que este driver no conoce.
- El **cuerpo entero de la respuesta es el valor**. El driver no es un extractor de campos
  JSON: un tag numérico espera que el cuerpo sea el número pelón.

## Los campos de conexión {#connection-fields}

| Campo | Qué es | Formato | Valor inicial |
|---|---|---|---|
| Host o IP | El nombre de host o la dirección IP del endpoint. Un host escrito con `http://` o `https://` enfrente mueve la casilla del transporte de más abajo para que empate, y se guarda sin él. Un puerto escrito después del host (`:8080`) va al campo Puerto y una ruta después de él (`/api`) a la ruta del recurso, así que aquí se puede pegar una dirección completa como `http://192.168.0.5:8080/api`. Una dirección IPv6 conserva sus corchetes. | Nombre de host, IP, o cualquiera de los dos con `http://` o `https://` enfrente | vacío |
| Puerto | El puerto TCP. Un dispositivo nuevo lo deja vacío, y un campo vacío significa el puerto en el que contesta el transporte elegido, 443 sobre HTTPS y 80 sin cifrar: el campo muestra ese puerto en gris y sigue la elección del transporte, que es también como se lee un dispositivo guardado con 0. | de 1 a 65535, o vacío | vacío |
| Ruta del recurso | Un prefijo de ruta opcional que se pone delante de la ruta de **todos** los tags, por ejemplo `api/v2`. En blanco no prefija nada. | texto de ruta | en blanco |
| Enviar por HTTP sin cifrar | Baja este dispositivo, y solo este, de HTTPS a HTTP en claro. Apagado significa HTTPS, que es lo que deja una credencial fuera del cable. El panel declara la consecuencia: sobre HTTP sin cifrar, las solicitudes, y cualquier credencial del dispositivo, viajan sin cifrar. Úselo con un endpoint que no responda por ningún otro transporte. | encendido / apagado | apagado |
| Nombre de usuario | La cuenta para la autenticación **HTTP Basic**, usada solo cuando no hay ningún token de portador puesto. Vacío (y sin token) deja las peticiones anónimas. | Texto libre | vacío |
| Contraseña | La contraseña que va con el nombre de usuario. Protegida en reposo por usuario de Windows; un secreto capturado en otra cuenta de Windows se muestra como ilegible y hay que volver a ingresarlo. | Texto libre | vacía |
| Token de portador | Un token que se envía como `Authorization: Bearer …` en cada petición. Cuando está puesto, **gana** sobre el par de nombre de usuario y contraseña. Se protege en reposo de la misma manera. | Texto del token | vacío |

Al conectarse, el driver verifica el endpoint con una petición HEAD a la **dirección
configurada**, host más ruta del recurso, y cae en GET cuando HEAD no está implementado; una
dirección que conteste bien a cualquiera de las dos cuenta como alcanzable. Por eso un
servicio cuya raíz contesta 404 mientras su API contesta con normalidad está en línea,
siempre que la ruta del recurso apunte a la API. Sobre HTTPS, el certificado TLS del servicio
se acepta cuando Windows confía en él, o cuando usted aprobó ese mismo certificado en
[Acceso a los equipos](#equipment-access), en la página de este driver. Una credencial en un
dispositivo bajado a HTTP sin cifrar viaja sin cifrar, y la estación lo dice en el diario del
conector cuando el dispositivo se conecta. Cada petición tiene diez segundos: un endpoint que acepta la conexión y después se queda callado cuesta una lectura, no el
dispositivo entero, porque los demás tags del dispositivo se leen en la misma pasada. El
intervalo de sondeo es configurable: el valor predeterminado del dispositivo (1000 ms) vale
para todo tag que no declare el suyo.

## El direccionamiento del tag {#tag-addressing}

El campo **Ruta** del tag es la ruta de la URL relativa a la ruta del recurso del dispositivo:

| Campo | Qué hace | Valores | Valor inicial |
|---|---|---|---|
| Ruta | La ruta que se pide para este tag. La URL completa es `<transport>://<host>:<puerto>/<ruta del recurso>/<ruta>`. | Texto libre (obligatorio) | vacía |

Ejemplo: con el host `192.168.0.40` bajado a HTTP sin cifrar, la ruta del recurso `api` y la
ruta de tag `sensors/temp` se sondea `http://192.168.0.40/api/sensors/temp`.

## Las lecturas {#reads}

Cada sondeo hace GET de la URL del tag e interpreta el **cuerpo entero de la respuesta**
según el tipo de dato declarado del tag:

| Tipo | Cuerpo aceptado |
|---|---|
| Float | Un número, en formato invariante (`21.5`, con punto decimal y sin separadores de miles) |
| Int32 | Un entero (`42`) |
| Boolean | `true` o `false` |
| String | Cualquier cosa; el cuerpo es el valor tal cual (un documento JSON llega como su texto crudo) |

Un cuerpo que el tipo declarado no puede interpretar, o un código de estado que no es de
éxito, se lee como una lectura fallida: el tag pasa a mala calidad y su política de lectura
fallida decide qué se presenta, como se describe en la página del [Connector](connector). Un
estado que no es de éxito es el endpoint rechazando la lectura, y el motivo del tag
nombra el estado y cita lo que el endpoint dijo con él (`HTTP 404 Not Found: …`), con
las mismas palabras que las de una escritura o un comando rechazados. Un cuerpo que el tipo
declarado no puede interpretar le da al tag un motivo que cita lo que no se pudo leer, y el
dispositivo sigue conectado. Un endpoint que no contesta nada es la conexión del
dispositivo fallando: el dispositivo lo reporta y se reconecta, y sus tags apuntan a él. La línea roja del tag dice un estado así en el idioma de la estación, con lo que significa en los códigos 401, 403 y 404, y un cuerpo que no se puede analizar como una respuesta que no se puede leer como un valor del tipo del tag; la página Eventos guarda las palabras del propio endpoint.

## Las escrituras {#writes}

Los tags con un modo de acceso escribible escriben con **PUT** a esa misma URL: el cuerpo es
el valor en JSON, enviado con el tipo de contenido `application/json`. Un número va como un
literal pelón (`42.5`), un booleano como `true` o `false`, y el texto va entre comillas
(`"automatic"`). El endpoint decide qué hacer con él; un estado que no es de éxito es el endpoint rechazando el valor: el rechazo nombra el estado y cita lo que el endpoint dijo con él, con las mismas palabras que el de un comando rechazado, y quien escribió el valor lee el motivo. Como en todos lados, la caja de escritura toma el valor de
ingeniería y las etapas de conversión del tag se deshacen antes de que el valor bruto salga al
bus, como se describe en la página del [Connector](connector).

## Los tipos de dato admitidos {#supported-data-types}

Boolean, Int32, Float y String.

## Comandos {#commands}

Un tag lee un valor; un comando le pide al servicio que haga algo. Declare cada uno en el
dispositivo, en la tarjeta **Comandos** de su página: un nombre, la ruta a la que se le hace
POST (bajo la dirección propia del dispositivo, exactamente igual que la ruta de un tag) y,
opcionalmente, el nombre del único valor que toma. El verbo Ejecutar de la fila lo envía y
reporta qué contestó el servicio, y el comando se convierte además en un método del
dispositivo dentro del espacio de direcciones OPC UA propio de esta estación, así que
cualquier cosa que pueda llamar a un método puede lanzarlo. El valor que usted escriba se
envía como el cuerpo de la petición, tal cual.

Lo que contesta el servicio es el resultado del comando. Un estado que el servicio devuelve
fuera del rango de éxito es el servicio rechazando el comando, no la conexión fallando: el
rechazo nombra el estado y cita lo que el servicio dijo con él ("HTTP 500 Internal Server Error: el quemador está bloqueado"), y nada más del dispositivo se perturba por eso.

## El descubrimiento {#discovery}

El driver no tiene escaneo de descubrimiento. Agregue cada endpoint por su host y
cada valor por su ruta; el flujo para agregar un dispositivo se describe en la página del
[Connector](connector).

## Acceso a los equipos {#equipment-access}

Un endpoint HTTPS con un certificado autofirmado, o emitido por una autoridad propia, presenta un certificado que ninguna raíz instalada en Windows avala. No hace falta instalar esa raíz en este ordenador. La primera conexión se rechaza, el dispositivo dice **Esperando la aprobación del certificado** en el árbol y en su página, cuyo botón **Revisar el certificado** abre esta tarjeta sobre el certificado, y el certificado espera en **Acceso a los equipos**, al final de la página del driver HTTP, la misma tarjeta que lleva la página del driver OPC UA, hasta que usted decida:

| Grupo | Qué muestra | Qué puede hacer |
|---|---|---|
| A la espera de aprobación | Cada certificado rechazado, con el nombre que declara: su huella digital SHA-256, la dirección en la que se encontró, cuándo lo intentó por última vez y cuántas veces, y sus detalles (sujeto, emisor, nombres de dominio, fechas de validez). El que abrió **Revisar el certificado** de un dispositivo aparece marcado como Seleccionado para revisión. | **Aprobar** acepta el certificado desde el siguiente intento de conexión. **Bloquear** lo sigue rechazando sin volver a listarlo aquí. **Descartar todos los certificados pendientes** vacía la lista sin aprobar ni bloquear nada. |
| Equipos aprobados | Los certificados que usted aprobó o importó, con quién decidió y cuándo, y la dirección en la que se encontró cada uno por última vez. | **Retirar la aprobación** cierra la conexión y devuelve el certificado a la lista. **Importar certificado** aprueba un archivo de certificado público que ya tenga (.der, .cer, .crt o .pem) antes de la primera conexión. |
| Equipos bloqueados | Los certificados que usted bloqueó. Un certificado bloqueado se rechaza aunque Windows confíe en él. | **Desbloquear** devuelve el certificado a la lista, sin aprobarlo. |

Verifique la huella digital con quien administra el equipo antes de aprobar el certificado. Una aprobación acepta ese certificado y ningún otro, y solo dentro de sus fechas de validez; sustituye a la raíz que falta en Windows y al nombre que lleva el certificado, así que un endpoint al que se llama por su dirección IP se conecta aunque su certificado lleve otro nombre, y nada más del certificado se relaja. Cuando el equipo responde en una dirección cuyo certificado usted aprobó con otro distinto (un certificado renovado), la lectura se detiene, el nuevo espera aquí y la estación avisa "Certificado cambiado: `<nombre>`" con un botón **Revisar**. Un certificado en el que Windows ya confía se acepta como antes y nunca aparece aquí; nada se aprueba automáticamente.

El propio fallo del driver dice el motivo en lugar de un error de TLS sin nombre: "El certificado de este equipo (los primeros 16 caracteres de la huella digital) espera su aprobación en Acceso a los equipos, en la página del driver HTTP. La lectura empieza en cuanto lo apruebe." Uno bloqueado dice "…está bloqueado en esta estación. Revíselo en Acceso a los equipos, en la página del driver HTTP." Un certificado fuera de sus fechas de validez, revocado o con la firma rota se rechaza con ese motivo y nunca se lista, porque ninguna aprobación lo vuelve válido.

Las decisiones se guardan en la carpeta de datos de la estación, en `ua\pki\http`, y sobreviven a un reinicio. Los verbos solo se dibujan para un rol que puede configurar el Connector, y solo actúan en la ventana de la propia estación: un navegador en otro dispositivo lee la tarjeta sin cambiarla, y ninguna herramienta de agente aprueba un certificado (`connector_browse` indica el dispositivo en espera con `awaitingCertificate`). La lista guarda hasta 100 certificados a la espera de aprobación; cuando está llena, uno nuevo se sigue rechazando pero no se lista, y la tarjeta lo dice.