AVEVA PI
Referencia del controlador AVEVA PI: PI Web API sobre HTTPS, autenticación por token de portador o Basic, direccionamiento de AF y de puntos PI, lecturas y escrituras.
El controlador AVEVA PI lee y escribe un AVEVA PI System a través de PI Web API, la interfaz REST del sistema (JSON sobre HTTP). Es un controlador en modo cliente (Ganter Lab se conecta al servicio PI Web API) y el transporte es HTTPS de forma predeterminada: el controlador pone las credenciales del dispositivo en cada petición que hace, así que una conexión sin cifrar las publicaría. El HTTP sin cifrar existe solo como una elección explícita por dispositivo.
Un tag direcciona un atributo AF, un punto PI, o un flujo en bruto de PI Web API, y lee su valor instantáneo (el actual).
Campos de conexión
| Campo | Qué es | Formato | Por defecto |
|---|---|---|---|
| Host o IP | El nombre de host o la dirección IP del servidor de PI Web API. | Nombre de host o IP | vacío |
| Puerto | El puerto TCP del servicio. Cero significa el valor por defecto del controlador, el 443. | número de puerto | 0 (= 443) |
| Ruta del recurso | La ruta raíz del servicio que se añade a la autoridad. En blanco, o una / sola, significa la raíz estándar de PI Web API, piwebapi. Cualquier otra ruta es la ruta que abre el controlador, exactamente como se escribió: un servicio publicado detrás de un proxy inverso en /pi se alcanza en /pi, y no se le añade nada. Escriba la ruta completa que necesitaría un navegador, con piwebapi incluido allí donde el servicio siga respondiendo ahí. |
texto de ruta | en blanco (= piwebapi) |
| Enviar por HTTP sin cifrar | Baja este dispositivo, y solo este, de HTTPS a HTTP en claro. Apagado significa HTTPS, el transporte normal de PI Web API. El panel declara la consecuencia: sobre HTTP sin cifrar, el token de portador o la contraseña se envían sin cifrar en cada petición. Úselo solo con un PI Web API 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 la raíz del servicio (con HEAD, y recayendo en GET). Sobre HTTPS, el certificado TLS del servicio tiene que pasar la validación de certificados normal de Windows. 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
El campo ruta PI del tag acepta cuatro formas:
| Forma | Tiene este aspecto | Cómo se resuelve |
|---|---|---|
| Ruta de atributo AF | \\AFServer\Database\Element\SubElement\|Attribute |
Se busca una vez por attributes?path=… para obtener el WebId del atributo |
| Ruta de punto PI | \\PIServer\TagName |
Se busca una vez por points?path=… para obtener el WebId del punto |
| WebId | La propia cadena opaca del WebId | Se usa directamente (se reconoce por ser una ficha larga sin \, \| ni /) |
| URL relativa | streams/{webId}/value, streamsets/…, attributes?…, points?… |
Se envía tal cual bajo la raíz del servicio |
Las búsquedas de ruta se guardan en caché durante 12 horas, así que el sondeo en régimen permanente no las repite. En las tres primeras formas, la lectura hace GET al valor instantáneo del flujo (streams/{webId}/value) y extrae el campo Value del JSON; una URL relativa se lee literalmente, así que apúntela a un punto de conexión que responda con un documento de valor. El resultado se convierte al tipo de dato declarado del tag.
El veredicto del propio archivo histórico sobre la muestra se lee con ella. Un valor que el archivo marca como no bueno, como cuestionable o como sustituido (un número introducido a mano en lugar de medido) no es una lectura del equipo, así que no se publica como tal: el tag pasa a mala calidad y el motivo dice cuál de los tres era. Lo mismo pasa cuando la respuesta no lleva ningún valor, o contesta con un estado digital en vez de con un solo valor, y en ese caso el nombre del estado forma parte del motivo. En su lugar no se inventa nada, y ningún documento llega como si fuera la medida.
Ejemplos:
\\PI-SRV01\FURNACE.TEMP, un punto PI clásico.\\AF-SRV\Plant\Line 3\Furnace|Temperature, un atributo AF.streams/F1DPmNQx2kqBk0qbIVMoxAVBJw/value, una URL de flujo en bruto, útil cuando ya se tiene el WebId de otra herramienta.
Escrituras
Los tags con un modo de acceso que permite escribir escriben por el punto de conexión de flujo de PI Web API: un POST de {"Timestamp":"*","Value":…} (la marca de tiempo * significa ahora) a streams/{webId}/value. La escritura necesita un WebId que se pueda resolver, así que funciona con los tags direccionados por ruta AF, por ruta de punto PI, por WebId, y también por una URL relativa streams/…: el WebId se saca de esa URL y la escritura aterriza en el punto de conexión de valor de ese flujo, sea cual sea el subrecurso de lectura (recorded, por ejemplo) que la dirección llevara más allá. Tres formas relativas se rechazan, porque cada una responde con un documento en lugar de con el valor de un flujo y una escritura direccionaría el recurso equivocado: streamsets/…, attributes?… y points?…. La negativa nombra las formas aceptadas. Que la escritura aterrice depende además de que PI Web API esté configurado para escrituras y de que la cuenta tenga acceso de escritura al punto.
El valor que se escribe en la casilla de escritura del tag es el valor de ingeniería; 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.
Tipos de dato admitidos
Boolean, Int32, Int64, Float, Double y String. Los puntos PI numéricos suelen ser Float o Double. Un estado digital no es un valor único, así que un punto que responde con uno se lee con mala calidad nombrando el estado, sea cual sea el tipo que declare el tag.
Comandos
Más allá de leer y escribir puntos, a un punto de conexión de PI Web API se le puede pedir que haga algo, y qué peticiones acepta es asunto del propio servicio. Cada una se declara en el dispositivo, en la tarjeta Comandos de su página: un nombre, la URL relativa a la que se envía por POST bajo la raíz del servicio y, si procede, el nombre del único valor que toma, que viaja como cuerpo de la petición. El verbo Ejecutar de la fila lo envía e informa de lo que contestó el servicio; 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.
Descubrimiento
El botón Descubrir lee un servicio. Ponga su dirección y el elemento AF donde empieza el recorrido en la tarjeta Alcance de la exploración de la página del controlador, separados por una #: https://pi-host/piwebapi#\\AF-SRV\Plant\Line 3. La exploración resuelve ese elemento, recorre todos los elementos que hay debajo, y ofrece el dispositivo con un punto por atributo, cada uno direccionado por su propio flujo. La exploración lee el servicio sin credenciales, porque corre antes de que exista el dispositivo que las guardaría, así que un PI Web API que autentica cada petición no responde nada y el dispositivo se añade a mano: añada el servicio por su host y añada los tags por sus rutas AF o PI, tal como describe el recorrido para añadir un dispositivo de la página Connector.