AVEVA PI

AVEVA PI 驱动参考：走 HTTPS 的 PI Web API、承载令牌或 Basic 认证、AF 与 PI point 寻址、读取和写入。

AVEVA PI 驱动通过 PI Web API 读写一套 AVEVA PI System，也就是这个系统的 REST 接口（HTTP 上的 JSON）。它是一个客户端模式的驱动，由 Ganter Lab 连到 PI Web API 服务上，而传输默认是 HTTPS：驱动会把设备的凭据放在它发出的每一个请求上，所以不加密的连接等于把它们公之于众。普通 HTTP 只作为一个按设备明确做出的选择存在。

一个点位寻址的是一个 AF 属性、一个 PI point，或者一条原始的 PI Web API stream，读的是它的快照（当前）值。

连接字段

连上时，驱动核实服务根（先 HEAD，退回 GET）。走 HTTPS 时，服务的 TLS 证书在 Windows 信任它，或你在本驱动页面的现场设备访问里批准了这份证书本身时被接受。轮询间隔可以配置：设备的默认值（1000 毫秒）适用于每一个没有自己另作规定的点位。

准备 PI Web API

驱动通过 HTTP Basic 用用户名和密码登录，或者用承载令牌登录。PI Web API 出厂时只启用 Kerberos 这一种身份验证方法，而驱动不使用 Kerberos，所以刚安装好的服务通常会拒绝工作站，直到在 PI Web API 服务器上完成下面其中一项：

服务返回 401 且不提供 Basic 时，设备页面会用这些步骤说明这一点，代替驱动的英文错误；服务提供 Basic 却拒绝设备发送的账户时，页面会说明用户名或密码被拒绝，并指向“连接”卡片。服务一旦应答，这两种提示都会自行消失。日志和代理读到的是同样的步骤。服务拒绝承载令牌时，用驱动自己的话说明。

点位寻址

点位的 PI 路径字段接受四种形式：

路径查询会缓存 12 小时，所以稳定运行时的轮询不会一遍遍重查。对前三种形式，读取 GET 的是这条 stream 的快照值（streams/{webId}/value），并取出 JSON 里的 Value 字段；相对 URL 则按字面读，所以请把它指向一个用一份值文档来应答的 endpoint。结果会被转换成点位声明的数据类型。

归档自己对这次采样的判断会随它一起读回来。归档标为不良、标为可疑、或者标为被替换过（一个手工输入而不是测出来的数）的值，都不是对仪器的一次读数，所以也不会被当作读数发布出去：点位转为质量不可用，原因会说是三者中的哪一种。响应里没有值，或者答的是一个数字状态而不是一个单一值时，也是同样处理，这时那个状态的名字会成为原因的一部分。它们的位置上不会被编出什么东西来，也不会有哪份文档冒充成那次测量。

PI Web API 拒绝的读取（一个在成功范围之外的状态，比如账户对这个 point 没有读权限）同样转为质量不可用，原因会点名那个状态，以及服务随它说的话（HTTP 403 Forbidden: …）。服务不认识的路径会这样说出来，并点名那条路径。空地址、不属于四种形式中任何一种的地址，以及读不成声明类型的响应，同样会给出原因。一个完全不答的服务是设备的连接失败：设备会报告它并重新连接，它的点位会指向这台设备。

例子：

• \\PI-SRV01\FURNACE.TEMP：一个经典的 PI point。
• \\AF-SRV\Plant\Line 3\Furnace|Temperature：一个 AF 属性。
• streams/F1DPmNQx2kqBk0qbIVMoxAVBJw/value：一条原始的 stream URL，在你已经从别的工具那里拿到 WebId 时很好用。

写入

读写方式可写的点位通过 PI Web API 的 stream endpoint 来写：向 streams/{webId}/value POST 一个 {"Timestamp":"*","Value":…}（时间戳 * 表示现在）。写入需要一个解析得出来的 WebId，所以它对按 AF 路径、按 PI point 路径、按 WebId 寻址的点位都行得通，对按相对 streams/… URL 寻址的也行：WebId 会从那条 URL 里读出来，写入落在那条 stream 的 value endpoint 上，不管地址后面还带着哪个读取侧的子资源（比如 recorded）。有三种相对形式被拒绝，因为它们各自答的是一份文档而不是某一条 stream 的值，写入会寻错资源：streamsets/…、attributes?… 和 points?…。这次拒绝会点名可接受的那几种形式。写入能不能落地，还取决于 PI Web API 有没有配置成允许写入，以及那个账户对这个 point 有没有写权限。PI Web API 拒绝的写入会得到一个答复，里面有状态，以及服务随它说的话（例如 HTTP 403 Forbidden: …），写入这个值的一方读得到原因。

你在点位写入框里打的是工程值；原始值上总线之前会先把这个点位的转换环节反过来走一遍，见 Connector 页面。

支持的数据类型

Boolean、Int32、Int64、Float、Double 和 String。数值型的 PI point 通常是 Float 或 Double。数字状态不是一个单一值，所以一个用它来应答的 point，不管点位声明的是什么类型，都读作质量不可用并点名那个状态。

命令

除了读写点之外，一个 PI Web API endpoint 还可以被要求去做一件事，而它接受哪些请求是这个服务自己的事。每一条命令都在设备上声明，位置是它页面上的命令卡片：一个名称、POST 到服务根下面的那条相对 URL，以及可选的、它所接收的那一个值的名字，那个值作为请求体发出去。行上的“运行”把它发出去并报告服务答了什么；这条命令同时也成为这台设备在本工作站自己的 OPC UA 地址空间里的一个方法。服务拒绝的请求会得到一个答复，里面有状态，以及服务随它说的话，用的是和被拒绝的写入一样的说法。

设备发现

发现设备按钮读的是一个服务。把它的地址和这次遍历的起点 AF 元素填进驱动页面的“扫描范围”卡片，中间用一个 # 隔开：https://pi-host/piwebapi#\\AF-SRV\Plant\Line 3。扫描会解析那个元素，走一遍它下面每一个元素，并把设备提供出来，每个属性给一个点，各自按自己的 stream 寻址。扫描是不带凭据去读服务的，因为它跑的时候那台该拿着凭据的设备还不存在，所以一个对每次请求都要求认证的 PI Web API 什么都不会回答，那就改为手工添加设备：按主机添加这个服务，再按 AF 或 PI 路径添加点位，具体流程见 Connector 页面上添加设备的那一节。

PI 设备的页面上没有发现点位：遍历从一个 AF 元素开始，而设备并不保存这个元素，所以设备的点来自这次扫描，或者手工添加（见发现一台设备的点位）。

现场设备访问

端口上没有分配证书的 PI Web API 会自己生成并使用一份自签名证书，Windows 中已安装的任何根证书都不为它担保。无需在这台计算机上安装那个根证书。第一次连接会被拒绝，设备在树里和它的页面上显示正在等待证书批准，页面上的查看证书按钮会在那份证书上打开这张卡片；证书则在 AVEVA PI 驱动页面末尾的现场设备访问里等你决定。这张卡片和 OPC UA 驱动页面上的是同一张。

批准之前，请与管理该 PI 服务器的人核对指纹。批准只接受这一份证书，而且只在它的有效期内；它代替 Windows 缺少的根证书和证书上写的名字，所以按 IP 地址连接的 PI Web API，即使证书上写的是别的名字也能连上，而证书的其他方面一概不放宽。如果现场设备在你批准过证书的地址上换出另一份证书（证书续期、给端口绑定另一份证书等），读取就会停止，新证书在这里等待，工作站会带着审核按钮提示“证书已更换：<名称>”。Windows 已经信任的证书照旧被接受，永远不会出现在这里；没有任何东西会被自动批准。

驱动自己的失败会说明原因，而不是一个没有名字的 TLS 错误：“这台现场设备的证书（指纹的前 16 个字符）正在 AVEVA PI 驱动页面的‘现场设备访问’里等待你的批准。批准之后就开始读取。”被阻止的则显示“……在本工作站已被阻止。请在 AVEVA PI 驱动页面的‘现场设备访问’里审核它。”超出有效期、已吊销或签名损坏的证书会以这个原因被拒绝，且永远不会被列出，因为批准也不能让它变得可靠。从“扫描范围”卡片扫描这个服务时也遵循同样的决定：陌生的证书会以这句话结束扫描，并在这里等待。

这些决定保存在工作站数据文件夹的 ua\pki\aveva-pi 下，重启后依然有效。操作按钮只对能配置 Connector 的角色显示，而且只在工作站自己的窗口里生效：其他设备上的浏览器只能查看卡片、不能修改，也没有任何代理工具能批准证书（connector_browse 用 awaitingCertificate 标出正在等待的设备）。列表最多保留 100 份等待批准的证书；列表满了以后，新的证书仍会被拒绝但不会列出，卡片会说明这一点。