PI Web APIの使い方(基礎)

バージョン 1

    HTTPSプロトコルでリクエストすれば、PIのデータが取得可能。 (https://servername/piwebapi/XXXXにアクセスすることでPIのデータが取得可能です)

    •PI Web APIが利用できる分野

    –ウェブアプリケーション

    様々なウェブアプリケーションとともにPI Web APIを利用することができます。クライアントマシンに何もインストールせずに動作するところが良いところです。

    –モバイルアプリケーション

    Android, iPhone, Windows Phoneなどで、PIのデータを表示することに利用できます。

    –複数プラットフォームで動作するアプリケーション

    Linux, Windowsなど、プラットフォームを制限せずに動作するアプリケーションも開発できます。

     

    ブラウザからもデータ表示可能

    PI Web API はhttps を受け取れるアプリケーションに対して、プラットフォームをまたぐリッチデータアクセスを提供します。

    構成

    クライアントからPI Web API Serverにリクエストを送ります。

    リクエストの内容は以下です。

     

    PI Web API Serverはレスポンスを返します。(このレスポンスの中にデータやアセット情報が入っています)

    返されるデータはJSON型となります。

    JSONとはJavaScript Object Notationの略で、テキストベースのデータフォーマットです。

    {
        "Timestamp": "2016-01-14T06:01:51Z",
        "Value": 99.99349,
        "UnitsAbbreviation": "",
        "Questionable": false,
        "Substituted": false
    }
    

    TimeStampはUTCで返されるので、ローカル時刻への変換が必要となります。

     

    HTTPSレスポンスコードについて(HTTPSの応答時に返されるコード)

    •201 –Createdエレメントが無事に作成

    •400 –Bad Request定義されていないメソッドを使う

    •403–Forbidden リソースにアクセスすることを拒否された

     

    PI Web API helpページは以下URLです。

    https://PIWebAPIServerName/piwebapi/help

     

    PI Web APIを使用すれば、ブラウザからデータベース内の情報を確認することも可能です。

    Read, Writeを行ってみたいと思います。

    そのためにはHTTPSのGetとPostリクエストを作成する必要があります。

    Postリクエストはブラウザではできないため、Postmanを使います。

    Postmanは以下リンクからダウンロード可能です。

    Postman | Supercharge your API workflow

     

    PI Web APIに慣れるため、以下を実施してみます。

    1. Postmanを開きます。

    2. アドレスフィールドに以下を入力します。GET methodが選択されていることを確認します。

    https://PIWebAPIServerName/piwebapi/

    enterキーを押すか「Send」ボタンをクリックします。PI Web APIのトップレベルプロパティが表示されます。この中にあるのは、他のクエリへのリンクやヘルプなどです。実際のデータなどは返されていません。

    3. 1つ下の階層を見てみましょう。以下のアドレスを入力し、enterキーを押すか「Send」ボタンをクリックします。

    https://PIWebAPIServerName/piwebapi/assetservers/

    names, IDなど 詳細な情報をJSON形式で返してくれます。

    {
        "Links": {},
        "Items": [
            {
                "WebId": "S04gWl9O2GK0uSl8fK3qtqagTUFTVEVSUEk",
                "Id": "f4a505e2-86ed-4b2b-9297-c7cadeab6a6a",
                "Name": "MASTERPI",
                "Description": "",
                "Path": "\\\\ServerName",
                "ServerVersion": "2.6.0.5843",
                "Links": {
                "Self": "https://PIWebAPIServerName/piwebapi/assetservers/S04gWl9O2GK0uSl8fK3qtqagTUFTVEVSUEk",
                "Databases": "https://PIWebAPIServerName/piwebapi/assetservers/S04gWl9O2GK0uSl8fK3qtqagTUFTVEVSUEk/assetdatabases"
                "Databases": "https://PIWebAPIServerName/piwebapi/assetservers/S04gWl9O2GK0uSl8fK3qtqagTUFTVEVSUEk/unitclasses"
                }
            }
        ]
    }
    

    前のページに書かれた情報はクエリの実行結果です。返されたプロパティのほとんどは皆さまに馴染みのあるものだと思います。しかしながらIDが2つ返されており、1つはAF ServerのIDです。

    もう1 つは「WebId」というもので、AF Serverのオブジェクトとは異なるものが返されていることがわかります。

    情報を取得する際、PI Web APIはIDとパスをエンコーディングし、「WebId」とします。この「WebId」をユニークキーとしてクエリで使用します。

    多くのPI Web APIクエリはこの「WebId」を必要とします。

     

    4. 前の演習ではPI Web APIは「Links」を返していました。返されたオブジェクトに対して発行できるクエリを示しています。「Databases」というリンクのURLを確認してください。

    https://PIWebAPIServerName/piwebapi/assetservers/{PI-Asset-Server-WebID}/assetdatabases

    このクエリはPI AF ServerのユニークID(WebId)を使用して、データベースをリクエストしています。Linkを入力して「Send」ボタンを押してください。

     

    5. これでdatabase names, IDと関連する情報が取得できました。「USAWeather」データベースを探し、そのエレメントを表示してみてください。

    「Cities」エレメントが確認できます。さらにそのElementsをドリルダウンすると、都市のリストが確認できます。

    「Chicago」エレメントの属性を取得し、「Wind Speed」のInterpolated dataを取得してみてください。

    Interpolated dataのデフォルトはstartTime=*-1d, endTime=*, interval=1hです。

    *取得した結果のTimeStampはUTCで返されます。LocalTimeにする場合、自分で+9hする必要があります。

     

    6. starTimeを*-1h、intervalを10分として、データを取得してください。

     

    7. PI Web APIはPOSTリクエストを使用してPI Serverに対してデータを書き込んだり、オブジェクトの追加、変更をすることも可能です。

    これからPOSTリクエストを使用し、既存のエレメントに新しい属性を追加してみたいと思います。

    PI Web APIのPOSTリクエストは2つのパートで構成されています。URLとJSON packetです。URLはPOST先のオブジェクトを示します。

    JSON packetは書き込む値が入っています。

    これから新しい属性を追加します。

    そこで特定のエレメントのURLを用意する必要があります。

    属性を追加するため、JSON packetも用意しなければなりません。

    まず、POSTする先のURLを用意します。ヘルプファイルを確認しましょう。

    https://PIWebAPIServerName/piwebapi/help/controllers/element

    POST形式でクエリを書く必要があります。

     

    エレメントのWebIdが必要になります。

    https://PIWebAPIServerName/piwebapi/elements/{element-webId}/attributes

     

    Postmanにおいて、URLの横のプルダウンからPOSTを選んでください。

    URLの下側で「Headers」をクリックします。

    「Body」の部分で「raw」を選択してください。

    「raw」の右側のプルダウンでJSON(application/json)を選択してください。

    テキスト部分に以下を入力してください。

    {
    "Name": "ExampleAttribute",
    "Description": "ExampleString",
    "DataReferencePlugIn": "PI Point",
    "ConfigString": "\\\\localhost\\CDT158;UOM=m;ReadOnly=False",
    "IsConfigurationItem": true,
    }
    

    以下のスクリーンショットのようになっているはずです。

    「Send」ボタンを押してください。「201 Created」のステータスが返されることを確認してください。

     

    8. リクエストを「GET」に変更して再度「Send」ボタンを押してください。作成された属性が確認できるはずです。新しい属性のDataReferencePlugInが「PI Point」で作成されていることを確認します。

     

    PI Web APIは認証さえ通ればどのOSでも動作します。

    まず、Web IDを取得してから実際に必要なリクエストを送ることになるかと思います。

    2つ以上のリクエストを送る場合Batchリクエストが利用できます。パフォーマンスを考慮するとBatchリクエストを使用したほうがよいです。

    PI Web API Batchリクエストの紹介

     

    AF SDK、PI OLEDBの使い方を学習したい方は以下を参考にしてください。

    AF SDKにてPI Data Archiveから値を取得する(基礎)

    PI OLEDB Provider/Enterpriseの使用方法(基礎)