AVEVA PI
AVEVA PI 드라이버 참고 자료입니다. HTTPS 위의 PI Web API, 베어러 인증과 Basic 인증, AF와 PI 포인트 주소 지정, 그리고 읽기와 쓰기.
AVEVA PI 드라이버는 시스템의 REST 인터페이스(HTTP 위의 JSON)인 PI Web API를 거쳐 AVEVA PI System을 읽고 씁니다. 클라이언트 모드 드라이버, 곧 Ganter Lab이 PI Web API 서비스에 접속하는 드라이버이며 전송은 기본이 HTTPS입니다. 드라이버가 보내는 모든 요청에 장치의 자격 증명이 실리므로, 암호화되지 않은 연결은 그것을 그대로 공개하게 됩니다. 평문 HTTP는 장치마다 명시적으로 고르는 선택으로만 있습니다.
태그 하나는 AF 속성 하나, PI 포인트 하나, 또는 PI Web API의 원시 스트림 하나를 가리키고 그 스냅숏(현재) 값을 읽습니다.
연결 칸
| 칸 | 무엇인가 | 형식 | 기본값 |
|---|---|---|---|
| 호스트 | PI Web API 서버의 호스트 이름이나 IP 주소. 주소 전체(https://pi-host/piwebapi)를 붙여 넣을 수 있습니다. 앞에 붙은 https://나 http://는 아래의 전송 방식을 그에 맞춘 뒤 빠지고, 포트는 포트 필드로, 경로는 리소스 경로로 들어갑니다. |
호스트 이름 또는 IP | 비어 있음 |
| 포트 | 서비스의 TCP 포트입니다. 새 장치에서는 비어 있으며, 빈 칸은 고른 전송이 답하는 포트, 곧 HTTPS면 443, 평문이면 80을 뜻합니다. 칸에는 그 포트가 회색으로 보이고 전송 선택에 맞춰 바뀝니다. 0으로 저장된 장치도 똑같이 보입니다. | 1에서 65535까지, 또는 빈 칸 | 빈 칸 |
| 리소스 경로 | 권한부 뒤에 붙는 서비스 뿌리 경로입니다. 비어 있거나 / 하나이면 PI Web API의 표준 뿌리인 piwebapi를 뜻합니다. 그 밖의 경로는 드라이버가 적힌 그대로 여는 경로입니다. 역방향 프록시 뒤 /pi에 공개된 서비스에는 /pi로 닿으며 거기에 아무것도 덧붙이지 않습니다. 브라우저에 필요한 전체 경로를 적으십시오. 서비스가 아직 거기에서 답한다면 piwebapi도 함께 적습니다. |
경로 문구 | 비어 있음 (= piwebapi) |
| 일반 HTTP로 보내기 | 이 장치 하나만 HTTPS에서 평문 HTTP로 내립니다. 끄면 HTTPS이며, 이것이 PI Web API의 보통 전송입니다. 패널이 그 결과를 말합니다. 평문 HTTP에서는 베어러 토큰이나 비밀번호가 요청마다 암호화 없이 나갑니다. 다른 전송으로는 답하지 않는 PI Web API에만 쓰십시오. | 켜짐 / 꺼짐 | 꺼짐 |
| 사용자 이름 | HTTP Basic 인증에 쓰는 계정이며, 베어러 토큰이 없을 때에만 씁니다. 토큰도 없이 비어 있으면 요청이 익명이 됩니다. | 자유 입력 | 비어 있음 |
| 비밀번호 | 사용자 이름과 짝이 되는 비밀번호입니다. Windows 사용자별로 보호되어 저장되며, 다른 Windows 계정에서 입력한 비밀 값은 읽을 수 없는 것으로 나오고 다시 입력해야 합니다. | 자유 입력 | 비어 있음 |
| 베어러 토큰 | 요청마다 Authorization: Bearer …로 보내는 토큰입니다. 정해져 있으면 사용자 이름과 비밀번호 쌍보다 우선합니다. 저장될 때 같은 방식으로 보호됩니다. |
토큰 문구 | 비어 있음 |
접속할 때 드라이버는 서비스 뿌리를 확인합니다(HEAD를 보내고, 안 되면 GET으로 물러섭니다). HTTPS에서는 서비스의 TLS 인증서를 Windows가 신뢰하거나, 이 드라이버 페이지의 현장 장비 접근에서 바로 그 인증서를 승인했을 때 받아들입니다. 읽기 주기는 설정할 수 있습니다. 스스로 값을 정하지 않은 모든 태그에는 장치의 기본값(1000 ms)이 적용됩니다.
PI Web API 준비
드라이버는 HTTP Basic으로 사용자 이름과 비밀번호를 써서, 또는 베어러 토큰으로 로그인합니다. PI Web API는 Kerberos만 인증 방식으로 켜진 채 출하되고 드라이버는 Kerberos를 쓰지 않으므로, 새로 설치한 서비스는 PI Web API 서버에서 다음 중 하나를 마칠 때까지 보통 스테이션을 거부합니다.
| 방법 | 설정하는 곳 | 그다음 |
|---|---|---|
| Basic 인증 | PI Web API Admin Utility의 Authentication Options 페이지에서 Basic을 체크하고 적용합니다. 또는 PI System Explorer의 Configuration 데이터베이스에서 OSIsoft > PI Web API > 인스턴스 이름 아래의 System Configuration 요소를 골라 AuthenticationMethods 특성에 Basic을 추가하고 변경을 체크인합니다. PI Web API 서비스를 다시 시작합니다. | 장치의 연결 카드에 있는 사용자 이름과 비밀번호에 PI System이 받아들이는 Windows 계정을 넣습니다. 도메인 계정은 DOMAIN\user로 씁니다 |
| 베어러 토큰 | AVEVA Identity Manager와 함께 설정한 PI Web API(Bearer 인증) | 토큰은 장치의 베어러 토큰 칸에 넣습니다 |
서비스가 Basic을 제시하지 않고 401로 응답하면, 장치 페이지가 드라이버의 영어 오류 대신 이 절차와 함께 그렇다고 알려 줍니다. Basic을 제시하면서 장치가 보낸 계정을 거부하면, 사용자 이름 또는 비밀번호가 거부되었다고 알리고 연결 카드를 가리킵니다. 어느 알림이든 서비스가 응답하면 저절로 사라집니다. 저널과 에이전트도 같은 절차를 읽습니다. 서비스가 거부한 베어러 토큰은 드라이버 자신의 말로 알려 줍니다.
태그 주소 지정
태그의 PI 경로 칸은 네 가지 형태를 받아들입니다.
| 형태 | 생김새 | 풀어내는 방식 |
|---|---|---|
| AF 속성 경로 | \\AFServer\Database\Element\SubElement\|Attribute |
attributes?path=…으로 한 번 찾아 그 속성의 WebId를 얻습니다 |
| PI 포인트 경로 | \\PIServer\TagName |
points?path=…으로 한 번 찾아 그 포인트의 WebId를 얻습니다 |
| WebId | 불투명한 WebId 문자열 그 자체 | 그대로 씁니다(\도 \|도 /도 없는 긴 토큰으로 알아봅니다) |
| 상대 URL | streams/{webId}/value, streamsets/…, attributes?…, points?… |
서비스 뿌리 아래로 그대로 보냅니다 |
경로 찾기는 12시간 동안 캐시되므로, 자리를 잡은 뒤의 주기적 읽기는 그것을 되풀이하지 않습니다. 앞의 세 형태에서는 읽기가 스트림의 스냅숏 값(streams/{webId}/value)에 GET을 보내고 JSON의 Value 필드를 뽑아냅니다. 상대 URL은 적힌 그대로 읽으므로, 값 문서로 답하는 endpoint를 가리키게 하십시오. 결과는 태그가 선언한 데이터 형식으로 바뀝니다.
샘플에 대한 아카이브 자신의 판정도 함께 읽습니다. 아카이브가 정상 아님으로, 의심스러움으로, 또는 대체됨(측정한 것이 아니라 사람이 손으로 넣은 숫자)으로 표시한 값은 장비의 읽기가 아니므로 읽기로 공개되지 않습니다. 태그는 품질이 나쁜 것이 되고 이유가 셋 가운데 무엇이었는지 말합니다. 응답에 값이 없거나 하나의 값 대신 디지털 상태로 답할 때도 마찬가지이며, 그때는 그 상태의 이름이 이유의 일부가 됩니다. 그 자리에 무엇인가를 지어내지 않으며, 어떤 문서도 측정인 척 도착하지 않습니다.
PI Web API가 거부한 읽기(포인트를 읽을 권한이 없는 계정처럼 성공 범위 밖의 상태)도 품질이 나쁜 것이 되고, 그 이유는 상태와 서비스가 함께 말한 것(HTTP 403 Forbidden: …)을 밝힙니다. 서비스가 모르는 경로는 그 경로를 밝히며 그렇다고 말합니다. 빈 주소, 네 가지 형태 어디에도 맞지 않는 주소, 선언한 형식으로 읽히지 않는 응답도 이유를 말합니다. 아예 답하지 않는 서비스는 장치의 연결이 실패한 것입니다. 장치가 그것을 알리고 다시 연결하며, 그 태그들은 장치를 가리킵니다.
예는 이렇습니다.
\\PI-SRV01\FURNACE.TEMP는 고전적인 PI 포인트입니다.\\AF-SRV\Plant\Line 3\Furnace|Temperature는 AF 속성입니다.streams/F1DPmNQx2kqBk0qbIVMoxAVBJw/value는 원시 스트림 URL이며, 다른 도구에서 WebId를 이미 가지고 있을 때 쓸모가 있습니다.
쓰기
쓸 수 있는 접근 방식을 가진 태그는 PI Web API의 스트림 endpoint로 씁니다. streams/{webId}/value에 {"Timestamp":"*","Value":…}를 POST하는 것이며(시각 *는 지금을 뜻합니다), 쓰기에는 풀어낼 수 있는 WebId가 필요합니다. 그러므로 AF 경로와 PI 포인트 경로와 WebId로 주소를 적은 태그에서 동작하고, 상대 streams/… URL로 적은 태그에서도 동작합니다. 그 URL에서 WebId를 읽어 내어 그 스트림의 값 endpoint에 쓰며, 주소가 그 뒤에 어떤 읽기 쪽 하위 리소스(예를 들어 recorded)를 달고 있었든 마찬가지입니다. 상대 형태 셋은 거부됩니다. 각각 하나의 스트림 값이 아니라 문서로 답하므로 쓰기가 엉뚱한 리소스를 가리키게 되기 때문입니다. streamsets/…, attributes?…, points?…입니다. 거부는 받아들이는 형태를 밝힙니다. 쓰기가 자리를 잡는지는 PI Web API가 쓰기를 받도록 설정되어 있는지와 그 계정이 포인트에 쓸 권한을 가졌는지에도 달려 있습니다. PI Web API가 거부한 쓰기에는 상태와 서비스가 함께 말한 것(예를 들어 HTTP 403 Forbidden: …)이 답으로 돌아가므로 값을 쓴 쪽이 이유를 읽을 수 있습니다.
태그의 쓰기 상자에 입력하는 값은 공학값입니다. Connector 페이지에서 설명하듯 원시값이 버스로 나가기 전에 태그의 변환 단계가 거꾸로 적용됩니다.
지원하는 데이터 형식
Boolean, Int32, Int64, Float, Double, String입니다. 숫자 PI 포인트는 보통 Float이나 Double입니다. 디지털 상태는 하나의 값이 아니므로, 그것으로 답하는 포인트는 태그가 어떤 형식을 선언했든 그 상태의 이름을 밝히며 품질이 나쁜 것으로 읽힙니다.
명령
포인트를 읽고 쓰는 일 말고도, PI Web API endpoint에는 무엇인가를 해 달라고 시킬 수 있으며 어떤 요청을 받아들이는지는 그 서비스가 정할 일입니다. 명령은 장치의 페이지에 있는 명령 카드에서 하나씩 선언합니다. 이름, 서비스 뿌리 아래에서 POST를 보낼 상대 URL, 그리고 원한다면 요청 본문으로 실려 갈 값 하나의 이름입니다. 행의 실행 동사가 명령을 보내고 서비스가 무엇이라고 답했는지 알립니다. 그 명령은 이 스테이션 자신의 OPC UA 주소 공간에서 장치의 메서드가 되기도 합니다. 서비스가 거부한 요청에는 상태와 서비스가 함께 말한 것이 답으로 돌아갑니다. 거부된 쓰기와 같은 말입니다.
장치 검색
장치 검색 단추는 서비스 하나를 읽습니다. 드라이버 페이지의 스캔 범위 카드에 그 주소와 훑기를 시작할 AF 요소를 #로 나누어 적으십시오. https://pi-host/piwebapi#\\AF-SRV\Plant\Line 3입니다. 스캔은 그 요소를 풀어내고 그 아래의 모든 요소를 훑어, 속성마다 지점 하나를 가진 장치를 내놓으며 각 지점은 자기 스트림으로 주소가 매겨집니다. 스캔은 자격 증명 없이 서비스를 읽습니다. 자격 증명을 담고 있을 장치가 생기기 전에 도는 스캔이기 때문입니다. 그러므로 요청마다 인증을 요구하는 PI Web API는 아무것도 답하지 않고, 그런 장치는 손으로 추가합니다. Connector 페이지의 장치 추가 흐름이 설명하듯, 서비스는 호스트로 추가하고 태그는 자기 AF 경로나 PI 경로로 추가하십시오.
PI 장치의 페이지에는 태그 검색이 없습니다. 순회가 AF 요소에서 시작하는데 그 요소를 장치가 갖고 있지 않으므로, 장치의 지점은 이 스캔에서 오거나 직접 추가합니다(장치의 태그 검색 참고).
현장 장비 접근
포트에 인증서가 할당되지 않은 PI Web API는 자체 서명한 자기 인증서를 만들어 쓰며, Windows에 설치된 어떤 루트도 그 인증서를 보증하지 않습니다. 그 루트를 이 컴퓨터에 설치할 필요는 없습니다. 첫 연결은 거부되고, 장치는 트리와 그 페이지에서 인증서 승인 대기 중으로 표시되며, 그 페이지의 인증서 검토 단추가 이 카드를 그 인증서 위치에서 엽니다. 인증서는 AVEVA PI 드라이버 페이지 끝의 현장 장비 접근에서 결정을 기다립니다. OPC UA 드라이버 페이지에 있는 것과 같은 카드입니다.
| 그룹 | 보여 주는 것 | 할 수 있는 일 |
|---|---|---|
| 승인 대기 중 | 거부된 인증서마다 인증서가 내세우는 이름 아래에, SHA-256 지문, 그 인증서를 만난 주소, 마지막 시도 시각과 횟수, 세부 정보(주체, 발급자, 도메인 이름, 유효 기간)가 나옵니다. 장치의 인증서 검토로 연 인증서에는 검토하도록 선택됨 표시가 붙습니다. | 승인하면 다음 연결 시도부터 그 인증서를 받아들입니다. 차단하면 여기에 다시 올리지 않고 계속 거부합니다. 대기 중인 인증서 모두 버리기는 아무것도 승인하거나 차단하지 않고 목록을 비웁니다. |
| 승인된 현장 장비 | 승인했거나 가져온 인증서가 누가 언제 결정했는지, 각 인증서를 마지막으로 만난 주소와 함께 나옵니다. | 승인 철회는 연결을 닫고 인증서를 목록으로 되돌립니다. 인증서 가져오기는 이미 가진 공개 인증서 파일(.der, .cer, .crt, .pem)을 첫 연결 전에 승인합니다. |
| 차단된 현장 장비 | 차단한 인증서가 나옵니다. 차단한 인증서는 Windows가 신뢰하더라도 거부됩니다. | 차단 해제는 승인하지 않고 인증서를 목록으로 되돌립니다. |
승인하기 전에 PI 서버를 관리하는 담당자와 함께 지문을 확인하십시오. 승인은 그 인증서 하나만, 그것도 유효 기간 안에서만 받아들입니다. 승인은 Windows에 없는 루트와 인증서에 적힌 이름을 대신하므로, IP 주소로 접속하는 PI Web API도 인증서에 다른 이름이 적혀 있어도 연결되며, 인증서의 다른 점은 아무것도 느슨해지지 않습니다. 승인한 인증서의 주소에서 장비가 다른 인증서를 내놓으면(인증서 갱신, 포트에 다른 인증서 연결 등) 읽기가 멈추고, 새 인증서가 여기에서 기다리며, 스테이션이 검토 단추와 함께 "인증서가 바뀜: <이름>"을 알립니다. Windows가 이미 신뢰하는 인증서는 예전처럼 받아들여지고 여기에는 나타나지 않습니다. 자동으로 승인되는 것은 없습니다.
드라이버 자체의 실패는 이름 없는 TLS 오류 대신 이유를 말합니다. "이 현장 장비의 인증서(지문의 앞 16자)가 AVEVA PI 드라이버 페이지의 현장 장비 접근에서 승인을 기다립니다. 승인하면 읽기가 시작됩니다." 차단한 인증서라면 "…은 이 스테이션에서 차단되었습니다. AVEVA PI 드라이버 페이지의 현장 장비 접근에서 검토하십시오."라고 읽힙니다. 유효 기간을 벗어났거나, 해지되었거나, 서명이 깨진 인증서는 그 이유로 거부되고 목록에 오르지 않습니다. 승인해도 건전해지지 않기 때문입니다. 스캔 범위 카드에서 하는 서비스 스캔도 같은 결정을 따릅니다. 모르는 인증서는 그 문장으로 스캔을 끝내고 여기에서 기다립니다.
결정은 스테이션 데이터 폴더의 ua\pki\aveva-pi에 저장되며 다시 시작해도 남습니다. 동작 단추는 Connector를 구성할 수 있는 역할에만 그려지고, 스테이션 자신의 창에서만 동작합니다. 다른 기기의 브라우저는 카드를 읽기만 하고 바꾸지 못하며, 에이전트 도구는 인증서를 승인하지 않습니다(connector_browse는 기다리는 장치를 awaitingCertificate로 알립니다). 목록에는 승인 대기 중인 인증서를 100개까지 둡니다. 가득 차면 새 인증서는 계속 거부되지만 목록에 오르지 않으며, 카드가 그렇다고 알립니다.