HTTP

HTTP 드라이버 참고 자료입니다. HTTP와 HTTPS endpoint를 태그로 주기적으로 읽기, 자격 증명, 경로 대응, 본문 해석, PUT 쓰기, 그리고 형식.

HTTP 드라이버는 일반 HTTP endpoint를 태그로 주기적으로 읽습니다. 작은 웹 서버를 갖춘 LAN 센서, 정해진 URL에 읽은 값을 공개하는 게이트웨이, 직접 만든 서비스가 상대입니다. 이 제품에서 가장 단순한 클라이언트 모드 드라이버입니다. Ganter Lab이 장비에 접속해서 평범한 GET 요청을 보내고, 응답 본문 하나하나를 값 하나로 읽습니다.

이 드라이버가 무엇을 위한 것인지는 두 성질이 그어 줍니다.

전송은 장치 자신의 선택입니다. 장치는 일반 HTTP로 보내기 표시가 달리 말하기 전까지 TLS로 그 서비스에 닿습니다. 호스트 앞에 http://나 https://를 적으면 그 표시가 거기에 맞춰 움직이고 호스트는 그것을 뗀 채로 저장되므로, 둘이 서로 어긋날 수 없습니다. 어느 쪽이든 드라이버는 요청마다 장치의 자격 증명을 보냅니다. HTTP Basic으로 보내는 사용자 이름과 비밀번호이거나, 베어러 토큰입니다. AVEVA PI와 Redfish 드라이버가 그 두 서비스를 위해 더 얹어 주는 것은 각자의 어휘입니다. PI 경로와 WebId, Redfish의 리소스 나무이며, 이 드라이버는 그것들을 알지 못합니다.
응답 본문 전체가 값입니다. 이 드라이버는 JSON 필드 추출기가 아닙니다. 숫자 태그는 본문이 그 숫자 하나이기를 기대합니다.

연결 칸

칸	무엇인가	형식	기본값
호스트	endpoint의 호스트 이름이나 IP 주소. 호스트 앞에 `http://`나 `https://`를 적으면 아래의 전송 표시가 거기에 맞춰 움직이고, 호스트는 그것을 뗀 채로 저장됩니다. 호스트 뒤에 적은 포트(`:8080`)는 포트 칸으로, 그 뒤의 경로(`/api`)는 리소스 경로로 옮겨지므로 `http://192.168.0.5:8080/api` 같은 주소를 통째로 붙여 넣을 수 있습니다. IPv6 주소는 대괄호를 그대로 유지합니다.	호스트 이름, IP, 또는 그 둘 앞에 `http://`나 `https://`를 붙인 것	비어 있음
포트	TCP 포트입니다. 새 장치에서는 비어 있으며, 빈 칸은 고른 전송이 답하는 포트, 곧 HTTPS면 443, 평문이면 80을 뜻합니다. 칸에는 그 포트가 회색으로 보이고 전송 선택에 맞춰 바뀝니다. 0으로 저장된 장치도 똑같이 보입니다.	1에서 65535까지, 또는 빈 칸	빈 칸
리소스 경로	모든 태그의 경로 앞에 붙이는 선택적인 경로 앞머리이며 예를 들어 `api/v2`입니다. 비우면 아무것도 붙이지 않습니다.	경로 문구	비어 있음
일반 HTTP로 보내기	이 장치 하나만 HTTPS에서 평문 HTTP로 내립니다. 끄면 HTTPS이며, 그것이 자격 증명을 선로에 드러내지 않는 방법입니다. 패널이 그 결과를 말합니다. 평문 HTTP에서는 요청과 그 장치가 지닌 자격 증명이 암호화 없이 나갑니다. 다른 전송으로는 답하지 않는 endpoint에 쓰십시오.	켜짐 / 꺼짐	꺼짐
사용자 이름	HTTP Basic 인증에 쓰는 계정이며, 베어러 토큰이 없을 때에만 씁니다. 토큰도 없이 비어 있으면 요청이 익명이 됩니다.	자유 입력	비어 있음
비밀번호	사용자 이름과 짝이 되는 비밀번호입니다. Windows 사용자별로 보호되어 저장되며, 다른 Windows 계정에서 입력한 비밀 값은 읽을 수 없는 것으로 나오고 다시 입력해야 합니다.	자유 입력	비어 있음
베어러 토큰	요청마다 `Authorization: Bearer …`로 보내는 토큰입니다. 정해져 있으면 사용자 이름과 비밀번호 쌍보다 우선합니다. 저장될 때 같은 방식으로 보호됩니다.	토큰 문구	비어 있음

접속할 때 드라이버는 설정된 주소, 곧 호스트와 리소스 경로에 HEAD 요청을 보내 endpoint를 확인하며, HEAD가 구현되어 있지 않으면 GET으로 물러섭니다. 둘 가운데 하나에 성공으로 답하는 주소는 닿는 것으로 셉니다. 그러므로 뿌리는 404로 답하고 API는 정상으로 답하는 서비스도, 리소스 경로가 그 API를 가리키고 있는 한 온라인입니다. HTTPS에서는 서비스의 TLS 인증서를 Windows가 신뢰하거나, 이 드라이버 페이지의 현장 장비 접근에서 바로 그 인증서를 승인했을 때 받아들입니다. 평문 HTTP로 내린 장치에서는 자격 증명이 암호화 없이 지나가며, 장치가 접속할 때 스테이션이 그 사실을 커넥터 일지에 적습니다. 요청마다 10초가 주어집니다. 연결은 받아들이고 아무 말도 하지 않는 endpoint는 장치 전체가 아니라 읽기 하나만큼의 비용이 듭니다. 그 장치의 다른 태그는 같은 회차에서 읽히기 때문입니다. 읽기 주기는 설정할 수 있습니다. 스스로 값을 정하지 않은 모든 태그에는 장치의 기본값(1000 ms)이 적용됩니다.

태그 주소 지정

태그의 경로 칸은 장치의 리소스 경로에 상대적인 URL 경로입니다.

칸	하는 일	값	기본값
경로	이 태그를 위해 요청하는 경로입니다. 전체 URL은 `<transport>://<host>:<port>/<resource path>/<path>`입니다.	자유 입력(필수)	비어 있음

예를 들어 호스트가 192.168.0.40이고 평문 HTTP로 내려져 있으며, 리소스 경로가 api, 태그 경로가 sensors/temp라면 http://192.168.0.40/api/sensors/temp를 주기적으로 읽습니다.

읽기

읽을 때마다 태그의 URL에 GET을 보내고, 응답 본문 전체를 태그가 선언한 데이터 형식으로 해석합니다.

형식	받아들이는 본문
Float	문화권과 무관한 형식의 숫자(`21.5`, 소수점은 점, 천 단위 구분 기호 없음)
Int32	정수(`42`)
Boolean	`true` 또는 `false`
String	무엇이든 받습니다. 본문이 그대로 값이 됩니다(JSON 문서는 그 원시 텍스트로 들어옵니다)

선언한 형식으로 해석할 수 없는 본문이나 성공이 아닌 상태 코드는 실패한 읽기가 됩니다. 태그는 품질이 나쁜 것이 되고, Connector 페이지에서 설명하듯 그 읽기 실패 정책이 무엇을 보여 줄지 정합니다. 성공이 아닌 상태는 endpoint가 읽기를 거부한 것이며, 태그의 이유는 상태를 밝히고 endpoint가 함께 말한 것을 그대로 옮깁니다(HTTP 404 Not Found: …). 거부된 쓰기나 명령과 같은 말입니다. 선언한 형식으로 해석할 수 없는 본문은 읽지 못한 것을 그대로 옮기는 이유를 태그에 주며, 장치는 연결된 채로 남습니다. 아예 답하지 않는 endpoint는 장치의 연결이 실패한 것입니다. 장치가 그것을 알리고 다시 연결하며, 그 태그들은 장치를 가리킵니다. 태그의 빨간 줄은 이런 상태를 스테이션의 언어로 전하고 401, 403, 404에는 그 뜻이 붙으며, 해석할 수 없는 본문은 태그 형식의 값으로 읽히지 않는 응답으로 전합니다. endpoint 자신의 말은 이벤트 페이지에 남습니다.

쓰기

쓸 수 있는 접근 방식을 가진 태그는 같은 URL에 PUT으로 씁니다. 본문은 값을 JSON으로 적은 것이며 콘텐츠 형식은 application/json입니다. 숫자는 그대로의 리터럴(42.5)로, 부울은 true나 false로, 글자는 따옴표를 붙여("automatic") 갑니다. 그것을 어떻게 다룰지는 endpoint가 정합니다. 성공이 아닌 상태는 endpoint가 값을 거부한 것입니다. 그 거부는 상태를 밝히고 endpoint가 함께 말한 것을, 거부된 명령과 같은 말로 그대로 옮기므로 값을 쓴 쪽이 이유를 읽을 수 있습니다. 다른 곳에서와 마찬가지로 쓰기 상자는 공학값을 받으며, Connector 페이지에서 설명하듯 원시값이 버스로 나가기 전에 태그의 변환 단계가 거꾸로 적용됩니다.

지원하는 데이터 형식

Boolean, Int32, Float, String입니다.

명령

태그는 값을 읽고, 명령은 서비스에 무엇인가를 하라고 시킵니다. 명령은 장치의 페이지에 있는 명령 카드에서 하나씩 선언합니다. 이름, POST를 보낼 경로(태그의 경로와 똑같이 장치 자신의 주소 아래입니다), 그리고 원한다면 명령이 받는 값 하나의 이름입니다. 행의 실행 동사가 명령을 보내고 서비스가 무엇이라고 답했는지 알리며, 그 명령은 이 스테이션 자신의 OPC UA 주소 공간에서 장치의 메서드가 되기도 하므로 메서드를 부를 수 있는 것이라면 무엇이든 그 명령을 낼 수 있습니다. 입력한 값은 적은 그대로 요청 본문으로 나갑니다.

서비스가 답하는 것이 명령의 결과입니다. 서비스가 성공 범위 밖의 상태를 돌려주는 것은 연결이 실패한 것이 아니라 서비스가 명령을 거부한 것입니다. 그 거부는 상태를 밝히고 서비스가 함께 말한 것을 그대로 옮깁니다("HTTP 500 Internal Server Error: the burner is locked out"). 그것 때문에 그 장치의 다른 무엇이 흔들리지는 않습니다.

장치 검색

이 드라이버에는 장치 검색 스캔이 없습니다. endpoint는 호스트로 하나씩, 값은 경로로 하나씩 추가하십시오. 장치를 추가하는 흐름은 Connector 페이지에서 설명합니다.

현장 장비 접근

자체 서명했거나 자체 인증 기관이 발급한 인증서를 쓰는 HTTPS endpoint는 Windows에 설치된 어떤 루트도 보증하지 않는 인증서를 내놓습니다. 그 루트를 이 컴퓨터에 설치할 필요는 없습니다. 첫 연결은 거부되고, 장치는 트리와 그 페이지에서 인증서 승인 대기 중으로 표시되며, 그 페이지의 인증서 검토 단추가 이 카드를 그 인증서 위치에서 엽니다. 인증서는 HTTP 드라이버 페이지 끝의 현장 장비 접근에서 결정을 기다립니다. OPC UA 드라이버 페이지에 있는 것과 같은 카드입니다.

그룹	보여 주는 것	할 수 있는 일
승인 대기 중	거부된 인증서마다 인증서가 내세우는 이름 아래에, SHA-256 지문, 그 인증서를 만난 주소, 마지막 시도 시각과 횟수, 세부 정보(주체, 발급자, 도메인 이름, 유효 기간)가 나옵니다. 장치의 인증서 검토로 연 인증서에는 검토하도록 선택됨 표시가 붙습니다.	승인하면 다음 연결 시도부터 그 인증서를 받아들입니다. 차단하면 여기에 다시 올리지 않고 계속 거부합니다. 대기 중인 인증서 모두 버리기는 아무것도 승인하거나 차단하지 않고 목록을 비웁니다.
승인된 현장 장비	승인했거나 가져온 인증서가 누가 언제 결정했는지, 각 인증서를 마지막으로 만난 주소와 함께 나옵니다.	승인 철회는 연결을 닫고 인증서를 목록으로 되돌립니다. 인증서 가져오기는 이미 가진 공개 인증서 파일(.der, .cer, .crt, .pem)을 첫 연결 전에 승인합니다.
차단된 현장 장비	차단한 인증서가 나옵니다. 차단한 인증서는 Windows가 신뢰하더라도 거부됩니다.	차단 해제는 승인하지 않고 인증서를 목록으로 되돌립니다.

승인하기 전에 장비를 관리하는 담당자와 함께 지문을 확인하십시오. 승인은 그 인증서 하나만, 그것도 유효 기간 안에서만 받아들입니다. 승인은 Windows에 없는 루트와 인증서에 적힌 이름을 대신하므로, IP 주소로 접속하는 endpoint도 인증서에 다른 이름이 적혀 있어도 연결되며, 인증서의 다른 점은 아무것도 느슨해지지 않습니다. 승인한 인증서의 주소에서 장비가 다른 인증서를 내놓으면(인증서 갱신 등) 읽기가 멈추고, 새 인증서가 여기에서 기다리며, 스테이션이 검토 단추와 함께 "인증서가 바뀜: <이름>"을 알립니다. Windows가 이미 신뢰하는 인증서는 예전처럼 받아들여지고 여기에는 나타나지 않습니다. 자동으로 승인되는 것은 없습니다.

드라이버 자체의 실패는 이름 없는 TLS 오류 대신 이유를 말합니다. "이 현장 장비의 인증서(지문의 앞 16자)가 HTTP 드라이버 페이지의 현장 장비 접근에서 승인을 기다립니다. 승인하면 읽기가 시작됩니다." 차단한 인증서라면 "…은 이 스테이션에서 차단되었습니다. HTTP 드라이버 페이지의 현장 장비 접근에서 검토하십시오."라고 읽힙니다. 유효 기간을 벗어났거나, 해지되었거나, 서명이 깨진 인증서는 그 이유로 거부되고 목록에 오르지 않습니다. 승인해도 건전해지지 않기 때문입니다.

결정은 스테이션 데이터 폴더의 ua\pki\http에 저장되며 다시 시작해도 남습니다. 동작 단추는 Connector를 구성할 수 있는 역할에만 그려지고, 스테이션 자신의 창에서만 동작합니다. 다른 기기의 브라우저는 카드를 읽기만 하고 바꾸지 못하며, 에이전트 도구는 인증서를 승인하지 않습니다(connector_browse는 기다리는 장치를 awaitingCertificate로 알립니다). 목록에는 승인 대기 중인 인증서를 100개까지 둡니다. 가득 차면 새 인증서는 계속 거부되지만 목록에 오르지 않으며, 카드가 그렇다고 알립니다.