3. ダッシュボード向けAPI

本節ではダッシュボード(Node-RED)で使用可能なAPIについて説明します。

3.1. 共通事項

ストリーミング画像表示以外のAPIの共通事項を説明します。

3.1.1. エンドポイント

すべてのAPIはHTTPをベースとしています。APIの発行先のホストは、環境変数APIHOSTに含まれています。API毎のパスと連結してURLを生成します。

環境変数APIHOSTの値の例	10.0.1.1:3001
URLの例	http://10.0.1.1:3001/api/devices

3.1.2. APIキー

APIを発行する際には、認証のためのAPIキーをAuthorizationヘッダーのBearerトークンに設定する必要があります。APIキーは環境変数APIKEYから取得できます。

環境変数APIKEYの値の例	ffc782664c51a0a796fd3af9ac06be2fa3543879
Authorizationヘッダーの例	Authorization: Bearer ffc782664c51a0a796fd3af9ac06be2fa3543879

警告

APIキーは絶対に他の人に知られないようにしてください。

APIキーを知られると、なりすましの被害を受ける可能性があります。

3.2. MSM-PF端末情報取得

所有しているMSM-PF端末のリストを取得します。

パス
- /api/devices
メソッド
- GET
クエリパラメーター
- idOnly
  - 値 false
    - 端末IDだけでなく、詳細情報も受け取る
応答
- content-type
  - application/json
- MSM-PF端末のIDのリスト (idOnly指定なし、またはidOnly=trueの場合)
- MSM-PF端末の詳細情報のリスト (idOnly=falseの場合)

3.3. 直近センサーデータ取得

指定のMSM-PF端末の直近1000サンプル点のセンサーデータを取得します。

応答で得られるセンサーデータはsensordata形式です。MSM-PF端末がsensorjson形式でセンサーデータをアップロードした場合、"sensor values"の値は、sensorjson形式の1サンプル点を表したJSONを構成要素に分解したもののCSVとなります。

パス
- /api/devices/{deviceId}/currentSensorData
メソッド
- GET
パスパラメーター
- deviceId
  - MSM-PF端末のID
応答
- content-type
  - application/json

3.4. センサーデータ受信

SSE(Server Sent Events)により、MSM-PF端末から届いたセンサーデータをすぐに受け取ります。

直近センサデータ取得APIではポーリングでセンサーデータを取得するのに対し、本APIではセンサーデータがプッシュされてきますので、低遅延で可視化等を行うことができます。

パス
- /api/devices/{deviceId}/events
メソッド
- GET
パスパラメーター
- deviceId
  - MSM-PF端末のID
クエリパラメーター
- mode
  - 値 all
    - MSM-PF端末から受信したセンサーデータすべてを受け取る
応答
- content-type
  - text/event-stream
- イベントストリームのdataフィールド (mode=allの場合)
  - キープアライブのため、定期的に空のdataフィールドが届きます
  - 1つのdataフィールドが、MSM-PF端末からのセンサーデータの１サンプル点です
  - MSM-PF端末が送信してくるセンサーデータの形式により、CSVとJSONのどちらかの形式です
  - CSVの場合、最初のカラムはタイムスタンプの秒部分、2番目のカラムはタイムスタンプのマイクロ秒部分で、以降のカラムにセンサ値が並びます
- イベントストリームのdataフィールド (mode指定がない場合)
  - キープアライブのため、定期的に空のdataフィールドが届きます
  - MSM-PF端末からアップロードされるセンサーデータのメッセージ受信毎に、そのメッセージ中の最後(最新)の1点のみが届きます
  - MSM-PF端末が送信してくるセンサーデータの形式により、CSVとJSONのどちらかの形式です
  - CSVの場合、タイムスタンプは含まれず、センサ値のみが並びます

3.5. 上り制御メッセージ受信

SSE(Server Sent Events)により、MSM-PF端末からの上り制御メッセージを受け取ります。

パス
- /api/devices/{deviceId}/ctl-events
メソッド
- GET
パスパラメーター
- deviceId
  - MSM-PF端末のID
応答
- content-type
  - text/event-stream
- イベントストリームのdataフィールド
  - キープアライブのため、定期的に空のdataフィールドが届きます
  - MSM-PF端末が送信した上り制御メッセージ(JSON)

3.6. 下り制御メッセージ送信

MSM-PF端末へ下り制御メッセージを送信します。

パス
- /api/devices/{deviceId}/ctl-events
メソッド
- POST
パスパラメーター
- deviceId
  - MSM-PF端末のID
リクエストボディ
- content-type
  - application/json
- MSM-PF端末へ送信する下り制御メッセージ

3.7. カメラ端末情報取得

所有しているカメラ端末のリストを取得します。

パス
- /api/cameras
メソッド
- GET
応答
- content-type
  - application/json
- カメラ端末のIDのリスト

3.8. ストリーミング画像表示

Node-REDのサーバー側ではなく、ブラウザー側で、Amazon Kinesis Video Streams with WebRTCを使用します。つまり、Node-REDのTemplate UIノードを使用してブラウザー側の処理を記述し、その中でAmazon Kinesis Video Streams with WebRTCを呼び出します。

AWSへのAPI発行のためのアクセスキーID、シークレットアクセスキー、リージョンは、環境変数 _AWS_ACCESS_KEY_ID, _AWS_SECRET_ACCESS_KEY, _AWS_REGION から取得できます。

警告

アクセスキーIDとシークレットアクセスキーは、絶対に他の人に知られないようにしてください。

カメラ端末からのストリーミング画像を盗み見られることがあります。