# HTTP

> Referencia del controlador HTTP: sondear endpoints HTTP y HTTPS como tags, credenciales, correspondencia de rutas, análisis del cuerpo, escrituras PUT y tipos.

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

Dos propiedades trazan la línea de para qué sirve:

- El transporte es **la elección del propio dispositivo**. Un dispositivo alcanza su servicio sobre TLS hasta que su casilla **Enviar por HTTP sin cifrar** diga otra cosa, y un host escrito con `http://` o `https://` delante mueve esa casilla y se guarda como el host a solas, de modo que los dos nunca se contradicen. De una manera u otra, el controlador envía la credencial del dispositivo en cada petición, un nombre de usuario y una contraseña como HTTP Basic o un token de portador. Lo que los controladores [AVEVA PI](driver-aveva-pi) y [Redfish](driver-redfish) siguen aportando para esos dos servicios es su vocabulario: rutas PI y WebId, árboles de recursos de Redfish, de los que este controlador no sabe nada.
- **El cuerpo entero de la respuesta es el valor**. El controlador no es un extractor de campos JSON: un tag numérico espera que el cuerpo sea el número pelado.

## Campos de conexión {#connection-fields}

| Campo | Qué es | Formato | Por defecto |
|---|---|---|---|
| Host o IP | El nombre de host o la dirección IP del endpoint. Un host escrito con `http://` o `https://` delante mueve la casilla del transporte de más abajo para que coincida, y se guarda sin él. Un puerto escrito tras el host (`:8080`) va al campo Puerto y una ruta tras él (`/api`) a la ruta del recurso, así que aquí se puede pegar una dirección entera 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://` delante | vacío |
| Puerto | El puerto TCP. Un dispositivo nuevo lo deja vacío, y un campo vacío significa el puerto en el que responde el transporte elegido, el 443 sobre HTTPS y el 80 sin cifrar: el campo muestra ese puerto en gris y sigue a 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 antepone a la ruta de **todos** los tags, por ejemplo `api/v2`. En blanco no antepone 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 mantiene una credencial fuera del cable. El panel declara la consecuencia: sobre HTTP sin cifrar, las peticiones, 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 acompaña al nombre de usuario. Protegida en reposo por usuario de Windows; un secreto escrito con otra cuenta de Windows aparece como ilegible y hay que volver a escribirlo. | Texto libre | vacío |
| Token de portador | Un token enviado como `Authorization: Bearer …` en cada petición. Cuando está puesto, **gana** sobre la pareja de nombre de usuario y contraseña. Protegido en reposo de la misma manera. | Texto del token | vacío |

Al conectar, el controlador verifica el endpoint con una petición HEAD a la **dirección configurada**, host más ruta del recurso, y recae en GET cuando HEAD no está implementado; una dirección que responde bien a cualquiera de las dos cuenta como alcanzable. Un servicio cuya raíz responde 404 mientras su API responde con normalidad está, por tanto, 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 controlador. 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. A cada petición se le dan diez segundos: un endpoint que acepta la conexión y luego no dice nada 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 por defecto del dispositivo (1000 ms) se aplica a todo tag que no declare el suyo.

## 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 | Por defecto |
|---|---|---|---|
| Ruta | La ruta que se pide para este tag. La URL completa es `<transport>://<host>:<port>/<resource path>/<path>`. | Texto libre (obligatorio) | vacío |

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`.

## Lecturas {#reads}

Cada sondeo hace un GET a la URL del tag y analiza el **cuerpo entero de la respuesta** según el tipo de dato declarado del tag:

| Tipo | Cuerpo aceptado |
|---|---|
| Float | Un número en formato invariable (`21.5`, con punto decimal y sin separadores de millares) |
| 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 en bruto) |

Un cuerpo que el tipo declarado no puede analizar, 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 fallo de lectura decide qué se presenta, tal como se describe en la página [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 dijo el endpoint 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 analizar 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 informa 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.

## Escrituras {#writes}

Los tags con un modo de acceso que permite escribir escriben con **PUT** a la misma URL: el cuerpo es el valor en JSON, enviado con el tipo de contenido `application/json`. Un número va como literal pelado (`42.5`), un booleano como `true` o `false`, y el texto va entrecomillado (`"automatic"`). El endpoint decide qué hacer con él; un estado que no es de éxito es el endpoint rechazando el valor: la negativa nombra el estado y cita lo que dijo el endpoint con él, con las mismas palabras que la de un comando rechazado, y quien escribió el valor lee el motivo. Como en todas partes, la casilla 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, tal como se describe en la página [Connector](connector).

## Tipos de dato admitidos {#supported-data-types}

Boolean, Int32, Float y String.

## Comandos {#commands}

Un tag lee un valor; un comando pide al servicio que haga algo. Cada uno se declara en el dispositivo, en la tarjeta **Comandos** de su página: un nombre, la ruta a la que se envía por POST (bajo la dirección propia del dispositivo, exactamente igual que la ruta de un tag) y, si procede, el nombre del único valor que toma. El verbo Ejecutar de la fila lo envía e informa de lo que contestó el servicio, y el comando pasa a ser además un método sobre el dispositivo en el espacio de direcciones OPC UA propio de esta estación, así que cualquiera que pueda llamar a un método lo puede emitir. El valor que se escribe se envía como cuerpo de la petición, tal como está escrito.

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: la negativa nombra el estado y cita lo que dijo el servicio con él ("HTTP 500 Internal Server Error: el quemador está bloqueado"), y con eso no se perturba nada más del dispositivo.

## Descubrimiento {#discovery}

El controlador no tiene ninguna exploración de descubrimiento. Añada cada endpoint por su host y cada valor por su ruta; el recorrido para añadir un dispositivo se describe en la página [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 controlador HTTP, la misma tarjeta que lleva la página del controlador 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. |

Compruebe 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 controlador 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 controlador 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 controlador 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.