PI Web API

Integración con el AVEVA PI System (antes OSIsoft) mediante la PI Web API. Corre en proceso dentro de cms-api sobre HTTPS — sin SDK nativo, sin microservicio separado y sin dependencia binaria.

Aunque habla HTTP, no es una integración HTTP genérica: el CMS conoce el vocabulario del PI (tags, ventanas de tiempo, calidad de muestra) y resuelve por su cuenta la parte más tediosa del producto, que es el WebId.

Por qué importa el WebId

Toda lectura y escritura en la PI Web API direcciona la tag por un WebId — un identificador opaco generado por el servidor que cambia si la tag se borra y se recrea, o si el PI se migra.

Una integración HTTP cruda guardaría ese WebId en la URL de la recolección. El día en que la tag se recreara, toda la configuración pasaría a devolver 404 sin ninguna pista del motivo, y alguien tendría que reescribir URL por URL.

En el CMS lo que se configura es la ruta de la tag (\\PISRV01\FIC101.PV) — legible, estable y exportable. El WebId vive solo en una caché interna; cuando el PI responde que ya no existe, el CMS vuelve a resolver la ruta por su cuenta y repite la llamada. La configuración no se rompe.

Conexión

Registre el servidor en Conexiones Externas, en la categoría Protocolos Industriales:

• URL Base — puede pegar la raíz del sitio (https://pi.empresa.com); el sufijo /piwebapi se agrega cuando falta.
• Autenticación — Basic (usuario y contraseña), Bearer (token) o Anónimo.
• Data Server predeterminado — el botón Buscar servidores lista los PI Data Archives visibles para la credencial; al hacer clic en el nombre se completa el campo. Con él configurado, las tags pueden informarse solo por el nombre (FIC101.PV) en vez de la ruta completa.
• Validar certificado TLS — déjelo activado. Si el PI usa un certificado autofirmado o de CA interna, prefiera pegar la CA en Certificado de la CA a desactivar la validación.

El botón Probar Conexión valida en dos etapas — dirección/credencial y luego el Data Server — y rechaza en el acto un nombre de servidor inexistente, en vez de dejar que el error aparezca recién en la primera recolección.

Una Aplicación con Keep Alive PI_WEB_API monitorea el servidor en el cockpit. La prueba también avisa cuando la PI Web API responde pero el Data Archive detrás está desconectado — una situación en la que ninguna tag puede leerse aunque el HTTP siga devolviendo 200.

Catálogo de tags

El ícono de catálogo en la fila de la conexión abre el navegador de tags: filtra por nombre con el comodín * del propio PI y muestra descripción, unidad de ingeniería y tipo del punto.

Es cache-first — abre al instante y funciona con el PI fuera de servicio, sirviendo el catálogo ya conocido. El botón Actualizar del PI fuerza la ida al servidor.

El mismo navegador reaparece como selector de tag en las pantallas de Recolección y Entrega: hacer clic en una tag ya la agrega con un alias sugerido.

Recolección — PI_WEB_API

Recolección programada (pull), en el mismo programador de HTTP_GET/SQL_SERVER — sin conexión persistente —, o bajo demanda, cuando tiene Parámetros de Entrada. Son cuatro modos de lectura:

El payload generado es {alias: valor} para cada tag configurada. Con Incluir metadatos, gana un bloque _meta con timestamp, calidad y unidad por tag.

{
  "vazao": 128.4,
  "temperatura": 87.2,
  "_meta": {
    "vazao": { "timestamp": "2026-08-21T14:03:00Z", "boa": true, "unidade": "m3/h" }
  }
}

En el modo Valor Actual todas las tags se leen en una única llamada (/streamsets/value) — veinte tags cuestan una petición, no veinte.

Barrido incremental de histórico

Inicio y Fin aceptan la sintaxis de tiempo del PI (* = ahora, *-1h = hace una hora) o una fecha ISO. También aceptan {{ultimaExecucao}}, el placeholder del CMS:

Inicio: {{ultimaExecucao}}     Fin: *

Con eso, cada ejecución lee exactamente el histórico todavía no leído — sin repetir ni saltar muestras entre ciclos. Es la forma recomendada de traer histórico continuo del PI a una cola.

Ventana que viene de afuera

Inicio, Fin e Intervalo también pueden venir de quien dispara la recolección. El bloque Parámetros de Entrada (API) queda justo debajo del modo de lectura, antes de los campos de la ventana: declare allí los nombres — por ejemplo data_inicio y data_final — y úselos en los campos como {{data_inicio}} y {{data_final}}.

Inicio: {{data_inicio}}     Fin: {{data_final}}     Intervalo: {{passo}}

Con al menos un parámetro, la recolección sale del programador y pasa a ejecutarse bajo demanda: por la API dinámica de Recolección, por un Disparador o por un agente de IA.

POST /api/collect/PI_DEMO_HIST/PI_DEMO_HIST_LEITURA
{ "data_inicio": "*-8h", "data_final": "*" }

Un parámetro que no llegue en la llamada usa su valor por defecto; sin valor por defecto, el campo cae en el valor del PI — *-1h en Inicio, * en Fin y 1h en Intervalo. Los campos también aceptan Variables ({{NOMBRE}}), como el resto del CMS.

Asistente de tiempo

Nadie necesita memorizar la sintaxis del PI. El ícono de calendario junto a Inicio, Fin e Intervalo abre un asistente que arma la expresión a partir de elecciones en lenguaje común:

Arriba quedan los atajos más usados y, cuando la recolección tiene Parámetros de Entrada, un botón para cada uno. Una vista previa muestra la expresión, lo que significa y en qué fecha y hora caería si la recolección se ejecutara ahora. El asistente abre ya posicionado en el valor actual del campo — y sigue siendo posible escribir directamente en el campo cualquier expresión que el PI acepte.

Emisión

En los modos con ventana de tiempo, la recolección puede generar un mensaje con la serie entera o un mensaje por muestra. La segunda fue pensada para el modo Interpolado, donde todas las tags comparten los mismos instantes; en Recorded, cada tag tiene sus propios instantes de grabación y la agrupación rara vez junta más de una tag por mensaje.

Calidad y tags obligatorias

Con Solo calidad buena activado (el valor por defecto), las muestras que el propio PI marcó como malas o cuestionables se descartan. Una tag marcada obligatoria cuya única muestra vino mala cuenta como “sin valor” y la recolección falla — en vez de propagar un número en el que el PI no confía.

Probar Lectura

El botón Probar Lectura ejecuta la configuración del formulario, incluso sin guardar. Mientras el PI responde, el botón muestra los segundos que pasan; el resultado abre en una ventana cuando la lectura termina:

• Resumen de la consulta — las tags, el modo de lectura, el período ya resuelto (la expresión que de hecho fue al PI), el intervalo, el tipo de resumen o el techo de muestras, los parámetros usados, cuántos registros llegaron (y cuántos se descartaron por calidad), cuántos mensajes generaría la recolección y cuánto tardó. Una tabla muestra, por tag, la ruta y cuántos valores llegaron.
• Registros — cada valor leído: tag, fecha y hora, valor, unidad y calidad, con el total de filas. La tabla muestra los primeros 500.
• Payload — el JSON exacto que la recolección pondría en la cola (los cinco primeros mensajes).

Si la lectura funcionó pero la recolección rechazaría el resultado — una tag obligatoria sin valor, por ejemplo —, la ventana muestra el error y los registros que devolvió el PI, que es justamente lo que ayuda a entender el porqué.

En la prueba no hay llamada de afuera: cada Parámetro de Entrada usa su valor por defecto, y {{ultimaExecucao}} vale una hora atrás.

Entrega — PI_WEB_API_WRITE

Escribe valores en tags del PI a partir del payload del mensaje — el camino de vuelta, del ERP/MES al historiador.

El productor del mensaje no conoce ninguna ruta de tag: envía un objeto plano con los alias configurados, y la pantalla muestra el payload modelo listo para copiar.

{ "setpoint": "*" }

• Timestamp — Ahora sella el momento del envío; Campo del payload usa un campo del propio mensaje, para cuando el dato fue producido antes de llegar al CMS.
• Modo de escritura — Replace sobrescribe un valor ya grabado en el mismo instante, Insert escribe aunque exista otro, No Replace solo escribe cuando no hay nada en ese instante.

Como en la recolección, la escritura va en una sola llamada por lote, y solo se escriben las tags presentes en el payload — una tag ausente no se sobrescribe con nulo. Las tags con un valor predeterminado configurado caen en él cuando el mensaje no las trae.

Probar sin un PI real

La pantalla Simuladores trae una pestaña PI Web API que imita el contrato REST del producto dentro del propio CMS — sin puerto nuevo y sin instalar nada.

• Tags con comportamiento propio (senoide, rampa, onda cuadrada, ruido, fijo) que varían solas en el tiempo y sirven histórico de cualquier ventana.
• La Conexión Externa “PI Simulator (interno)” se crea y se mantiene automáticamente: habilitar el simulador basta para usarlo en una recolección.
• El botón Regenerar WebIds simula tags recreadas en el PI, invalidando de una vez todos los WebId entregados — sirve para comprobar que el CMS vuelve a resolver las rutas por su cuenta, sin editar ninguna recolección.
• El simulador también rechaza peticiones sin el header X-Requested-With, igual que el PI real.
• Entiende las mismas expresiones de tiempo que arma el asistente: *, t, y, días de la semana, desplazamientos en secuencia (t+6h+30m) y fechas ISO.

Alcance de esta versión

Esta versión direcciona el PI Data Archive (PI Points). El Asset Framework (navegación por Elemento/Atributo) no entró — el campo de dirección ya se llama “ruta” y la caché se indexa por ella, así que el AF cabe después sin migración de datos.

La autenticación integrada de Windows (NTLM/Kerberos) también queda fuera de esta versión; use Basic o Bearer.