AVEVA PI
AVEVA PI のドライバーの手引き。HTTPS 越しの PI Web API、ベアラーか Basic の認証、AF と PI ポイントのアドレス指定、読み取りと書き込み。
AVEVA PI のドライバーは、AVEVA PI System をその REST のインターフェース（HTTP 越しの JSON）である PI Web API で読み書きします。こちらから接続する方式のドライバーで、Ganter Lab のほうから PI Web API のサービスにつなぎます。通信は既定で HTTPS です。ドライバーは出すすべての要求に機器の資格情報を載せるので、暗号化のない接続はそれを公開してしまうからです。ふつうの HTTP は、機器ごとにはっきり選んだときにだけ存在します。
1 つのタグは、1 つの AF の属性、1 つの PI ポイント、あるいは PI Web API の生のストリームをアドレスに取り、そのスナップショット（現在）の値を読みます。
接続の項目
| 項目 | 意味 | 形式 | 既定 |
|---|---|---|---|
| ホスト | PI Web API のサーバーのホスト名か IP アドレス。 | ホスト名か IP | 空 |
| ポート | サービスの TCP のポート。0 はドライバーの既定、つまり 443 という意味です。 | ポート番号 | 0（= 443） |
| リソースのパス | 権限の部分の後ろに付ける、サービスのルートのパス。空、または / だけなら、PI Web API の標準のルートである piwebapi という意味です。ほかのパスは、入力したそのままドライバーが開くパスです。リバースプロキシの後ろの /pi で公開しているサービスには /pi で届き、その後ろには何も付けません。ブラウザーが必要とするパスの全体を、サービスがまだそこで答えるなら piwebapi も含めて書いてください。 |
パスの文字列 | 空（= piwebapi） |
| ふつうの HTTP で送る | この 1 台の機器だけを HTTPS から平文の HTTP に落とします。オフなら HTTPS で、PI Web API のふつうの通信です。パネルはその結果を述べます。ふつうの HTTP では、ベアラーのトークンやパスワードが要求のたびに暗号化されずに送られます。ほかの通信では答えない PI Web API のためだけに使ってください。 | オン／オフ | オフ |
| ユーザー名 | HTTP Basic の認証のためのアカウントで、ベアラーのトークンを設定していないときにだけ使われます。空のまま（トークンもなし）なら、要求は匿名になります。 | 自由記述 | 空 |
| パスワード | ユーザー名と組になるパスワード。Windows のユーザーごとに保存時に保護されます。別の Windows アカウントで入力した秘密は読めないものとして表示されるので、入力し直してください。 | 自由記述 | 空 |
| ベアラーのトークン | 要求のたびに Authorization: Bearer … として送るトークン。設定されているときは、ユーザー名とパスワードの組より優先されます。同じやり方で保存時に保護されます。 |
トークンの文字列 | 空 |
接続のとき、ドライバーはサービスのルートを HEAD で確かめ、答えなければ GET に切り替えます。HTTPS では、サービスの TLS の証明書が Windows のふつうの証明書の検証を通らなければなりません。読み出し周期は設定できます。機器の既定（1000 ms）は、自分の周期を書いていないすべてのタグに効きます。
タグのアドレス指定
タグの PI のパスの項目は、4 つの形を受け付けます。
| 形 | 見た目 | 解決のされ方 |
|---|---|---|
| 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 時間キャッシュされるので、落ち着いた定周期読み出しがそれを繰り返すことはありません。最初の 3 つの形では、読み取りはストリームのスナップショットの値（streams/{webId}/value）を GET し、JSON の Value の項目を取り出します。相対 URL はそのまま読まれるので、値の文書で答えるエンドポイントを指してください。結果は、タグに宣言したデータ型に変換されます。
そのサンプルに対するアーカイブ自身の判定も、一緒に読みます。アーカイブが良好でない、疑わしい、あるいは差し替えられた（測定ではなく手で入れた数値）と印を付けた値は、現場設備の読み取りではないので、読み取りとしては公開しません。タグは品質の悪い状態になり、その理由が 3 つのどれだったかを述べます。応答が値を運んでいないときや、1 つの値ではなくデジタルの状態で答えたときも同じで、後者ではその状態の名前が理由の一部になります。その代わりに何かを作ることはありませんし、文書が測定であるかのように届くこともありません。
例です。
\\PI-SRV01\FURNACE.TEMP：昔ながらの PI ポイント。\\AF-SRV\Plant\Line 3\Furnace|Temperature：AF の属性。streams/F1DPmNQx2kqBk0qbIVMoxAVBJw/value：生のストリームの URL で、ほかの道具からすでに WebId を持っているときに便利です。
書き込み
書き込めるアクセスのタグは、PI Web API のストリームのエンドポイントを通じて書きます。streams/{webId}/value へ {"Timestamp":"*","Value":…} を POST します（時刻の * は今という意味です）。書き込みには解決できる WebId が要るので、AF のパス、PI ポイントのパス、WebId、そして相対の streams/… の URL でアドレスを取ったタグで働きます。最後の場合は、その URL から WebId を読み取り、アドレスがその先に何の読み取り側の下位リソース（たとえば recorded）を運んでいても、書き込みはそのストリームの値のエンドポイントに届きます。相対の形のうち 3 つは拒否されます。どれも 1 つのストリームの値ではなく文書で答えるので、書き込みが違うリソースを指してしまうからです。streamsets/…、attributes?…、points?… の 3 つで、拒否は受け付ける形を名指しします。書き込みが届くかどうかは、PI Web API が書き込みを受けるように構成されていることと、そのアカウントがそのポイントへの書き込みの権利を持っていることにもよります。
タグの書き込みの入力欄に入力する値は工業値です。生値がバスに出る前に、そのタグの変換の段階が逆向きに適用されます。Connector のページに書いてあるとおりです。
対応するデータ型
Boolean、Int32、Int64、Float、Double、String です。数値の PI ポイントは、たいてい Float か Double です。デジタルの状態は 1 つの値ではないので、それで答えるポイントは、タグがどの型を宣言していても、その状態を名指しした品質の悪い読み取りになります。
コマンド
ポイントを読み書きするほかに、PI Web API のエンドポイントには何かをするよう頼めます。どの要求を受け付けるかは、そのサービス自身の事情です。1 つずつ機器のページのコマンドのカードで宣言してください。名前、サービスのルートの下で POST する先の相対 URL、そして受け取る 1 つの値の名前（任意）で、その値は要求の本文として運ばれます。行の実行の操作がそれを送り、サービスが何と答えたかを伝えます。コマンドは、このステーション自身の OPC UA のアドレス空間で機器のメソッドにもなります。
機器検出
機器検出のボタンは、1 つのサービスを読みます。ドライバーのページの「スキャンの範囲」のカードに、そのアドレスと、巡回を始める AF の要素を # で区切って入れてください。https://pi-host/piwebapi#\\AF-SRV\Plant\Line 3 のようになります。スキャンはその要素を解決し、その下のすべての要素を巡り、属性 1 つにつきポイント 1 つを、それぞれ自分のストリームでアドレスを取った形で備えた機器を差し出します。スキャンは資格情報なしにサービスを読みます。資格情報を持つはずの機器がまだ存在しないうちに走るからです。ですから、あらゆる要求に認証を求める PI Web API は何も答えないので、その機器は手で追加してください。サービスはホストで追加し、タグは AF か PI のパスで追加します。Connector のページの、機器を追加する流れのとおりです。