HTTP

HTTP のドライバーの手引き。HTTP と HTTPS の endpoint をタグとして読むこと、資格情報、パスの対応、本文の解釈、PUT の書き込み、そして型。

HTTP のドライバーは、ふつうの HTTP の endpointをタグとして読みます。小さな Web サーバーを持つ LAN のセンサー、決まった URL に測定値を出すゲートウェイ、自分で用意したサービスなどです。製品の中でいちばん単純な、こちらから接続する方式のドライバーです。Ganter Lab のほうから現場設備につなぎ、飾りのない GET の要求を出して、応答の本文をそのまま 1 つの値として読みます。

このドライバーが何のためのものかは、2 つの性質が線を引きます。

通信は機器自身の選択です。機器は、平文の HTTP で送るのチェックがそう言わないかぎり、サービスに TLS で届きます。ホストの前に http:// や https:// を書くと、そのチェックがそちらへ動き、ホストはホスト名だけの形で保存されるので、二つが食い違うことはありません。どちらの場合も、ドライバーは機器の資格情報を要求のたびに送ります。HTTP Basic としてのユーザー名とパスワード、またはベアラーのトークンです。AVEVA PI と Redfish のドライバーがその 2 つのサービスのためにさらに持っているのは、それぞれの語彙です。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 で送る	この 1 台の機器だけを HTTPS から平文の HTTP に落とします。オフなら HTTPS で、それが資格情報を通信路にさらさない方法です。パネルはその結果を述べます。平文の HTTP では、要求も、その機器が持つ資格情報も、暗号化されずに流れます。ほかの通信では答えない endpoint に使ってください。	オン／オフ	オフ
ユーザー名	HTTP Basic の認証のためのアカウントで、ベアラーのトークンを設定していないときにだけ使われます。空のまま（トークンもなし）なら、要求は匿名になります。	自由記述	空
パスワード	ユーザー名と組になるパスワード。Windows のユーザーごとに保存時に保護されます。別の Windows アカウントで入力した秘密は読めないものとして表示されるので、入力し直してください。	自由記述	空
ベアラーのトークン	要求のたびに `Authorization: Bearer …` として送るトークン。設定されているときは、ユーザー名とパスワードの組より優先されます。同じやり方で保存時に保護されます。	トークンの文字列	空

接続のとき、ドライバーは設定したアドレス、つまりホストとリソースのパスに HEAD の要求を出して確かめます。HEAD が実装されていなければ GET に切り替え、どちらかがうまく答えた相手は到達できたと数えます。ですから、ルートが 404 を返し、API のほうはふつうに答えるサービスも、リソースのパスが API を指しているかぎりオンラインです。HTTPS では、サービスの TLS の証明書は、Windows が信頼しているとき、またはこのドライバーのページの現場設備へのアクセスでその証明書そのものを承認したときに受け入れられます。平文の HTTP に落とした機器では資格情報が暗号化されずに流れるので、機器がつながるときにステーションがコネクターの日誌にそう書きます。要求ごとに 10 秒を与えます。接続は受け付けるのに何も言わない endpoint は、1 回の読み取りを損なうだけで、機器の全体は損ないません。同じ 1 巡でその機器のほかのタグも読むからです。読み出し周期は設定できます。機器の既定（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 です。

コマンド

タグは値を読みます。コマンドは、サービスに何かをするよう頼みます。1 つずつ機器のページのコマンドのカードで宣言してください。名前、POST する先のパス（機器自身のアドレスの下で、タグのパスとまったく同じ書き方です）、そして受け取る 1 つの値の名前（任意）です。行の実行の操作がそれを送り、サービスが何と答えたかを伝えます。コマンドは、このステーション自身の OPC UA のアドレス空間で機器のメソッドにもなるので、メソッドを呼べるものなら何からでも出せます。入力した値は、書いたそのままで要求の本文として送られます。

サービスが答えたものが、コマンドの結果です。サービスが成功の範囲の外の状態を返したのは、接続が失敗したのではなく、サービスがそのコマンドを拒否したということです。その拒否は状態を名指しし、サービスが一緒に言ったことを引用します（「HTTP 500 Internal Server Error：バーナーがロックアウトしています」）。それによって機器のほかのものが乱されることはありません。

機器検出

このドライバーに機器検出のスキャンはありません。endpoint はホストで、値はパスで、1 つずつ追加してください。機器を追加する流れは Connector のページにあります。

現場設備へのアクセス

自己署名の証明書や自前の認証局が発行した証明書を持つ HTTPS の endpoint は、Windows にインストールされたどのルートも保証しない証明書を出します。そのルートをこのコンピューターにインストールする必要はありません。最初の接続は拒否され、機器はツリーとそのページで証明書の承認を待っていますと表示し、そのページの証明書を確認するのボタンがこのカードをその証明書の位置で開きます。証明書は、HTTP のドライバーのページの最後にある現場設備へのアクセスで、判断を待ちます。OPC UA のドライバーのページにあるのと同じカードです。

グループ	並ぶもの	できること
承認待ち	拒否された証明書の 1 つ 1 つが、証明書が名乗る名前の下に並びます。SHA-256 のフィンガープリント、それに出会ったアドレス、最後に試した日時と回数、詳細（主体、発行者、ドメイン名、有効期間）が出ます。機器の証明書を確認するで開いた証明書には「確認のために選択中」の印が付きます。	承認すると、次の接続の試みからその証明書を受け入れます。遮断すると、ここにふたたび並べることなく拒否し続けます。承認待ちの証明書をすべて破棄は、何も承認も遮断もせずに一覧を空にします。
承認した現場設備	承認した証明書と取り込んだ証明書が、誰がいつ判断したかと、それぞれに最後に出会ったアドレスとともに並びます。	承認を取り下げると、接続を閉じ、その証明書を一覧に戻します。証明書を取り込むと、手元にある公開証明書のファイル（.der、.cer、.crt、.pem）を最初の接続より前に承認します。
遮断した現場設備	遮断した証明書が並びます。遮断した証明書は、Windows が信頼していても拒否されます。	遮断を解除すると、承認はせずに、その証明書を一覧に戻します。

承認する前に、現場設備を管理している担当者とフィンガープリントを照合してください。承認で受け入れるのはその証明書だけで、しかも有効期間の内側だけです。承認は、Windows に足りないルートと、証明書に書かれた名前の代わりになります。そのため、IP アドレスで接続する endpoint も、証明書に別の名前が書かれていてもつながります。証明書のそのほかの点は何もゆるめません。承認した証明書のアドレスで現場設備が別の証明書を出すと（証明書の更新など）、読み取りは止まり、新しい証明書がここで待ち、ステーションが確認するのボタン付きで「証明書が変わりました：<名前>」と知らせます。Windows がすでに信頼している証明書はこれまでどおり受け入れられ、ここには出ません。何かが自動で承認されることはありません。

ドライバー自身の失敗は、名前のない TLS のエラーではなく理由を述べます：「この現場設備の証明書（フィンガープリントの先頭 16 文字）は、HTTP ドライバーのページの「現場設備へのアクセス」であなたの承認を待っています。承認すると読み取りが始まります。」遮断した証明書なら「…はこのステーションで遮断されています。HTTP ドライバーのページの「現場設備へのアクセス」で確認してください。」となります。有効期間の外にある証明書、失効した証明書、署名の壊れた証明書は、その理由で拒否され、一覧には並びません。承認しても健全にはならないからです。

判断はステーションのデータフォルダーの ua\pki\http に保存され、再起動しても残ります。操作が描かれるのは Connector を構成できるロールだけで、操作が効くのはステーション自身のウィンドウの中だけです。別の機器のブラウザーはカードを読むだけで変えられず、エージェントのツールが証明書を承認することもありません（connector_browse は待っている機器を awaitingCertificate で示します）。一覧に並ぶ承認待ちの証明書は 100 件までです。いっぱいになると、新しい証明書は引き続き拒否されますが一覧には並ばず、カードがそのことを伝えます。