時系列データの取得
センサーデータは、Time-series Database(時系列データベース、以降TSDBと略)に保存されます。TSDBが提供するAPIを利用することで、外部のアプリケーションからも取得して利用することができます。
例えばデータを取得する場合、以下のエンドポイントを利用します。
get /homes/{homeId}/smartModules/{moduleId}/timeSeries/{seriesId}/data
|
homeId, moduleId, seriesIdは、以下の通り指定してください。
homeId | そのゲートウェイが所属するHomeId。URLから確認可能。 |
moduleId | TSDBインスタンスのID。センサークラウドの場合、常に”tsdb” |
seriesId | そのセンサーのID。センサーのグラフ画面で確認が可能。 |
具体例)
/homes/2090/smartModules/tsdb/timeSeries/0127:fecd6643d89e-temperature:0
リアルタイムデータの取得
センサーゲートウェイは取得したセンサーデータを”Event”としてクラウドに通知します。このEventはWebsocketを使うことでリアルタイムに受信することができます。詳しくはReceiving Commands via WebSocketを参照してください。また、EventはWebhook Smart Moduleを使うことで外部システムに送信することもできます。How to handle device events and commands詳しくはWebhooksを参照してください。
送信されるイベント
eventType | realtimeData |
eventData | 時系列データ。以下例を参照。 |
例)
{ "eventType": "realtimeData", "eventData": { "timeSeriesData": [ { "timestamp": "2016-01-01T12:00:00.123Z", "seriesId": "0127:fecd6643d89e-temperature:0", "value": 23.456 } ] } }
|
Incident Eventの受信
センサー監視において発生するイベントはWebhook Smart Moduleを介して受信することができます。
Webhookの作成については https://dev.tinkermode.com/platform/console-manual/webhooks をご参照ください。
監視対象の状態に応じて以下の2種類のEvent Typeのイベントが発生します。
Event Type | 説明 |
_mod-tsdb-monitorAlertIncidentInvoked_ | 監視対象に何らかの問題があり、アラート状態になった際に発生するイベント。 |
_mod-tsdb-monitorRecoveryIncidentInvoked_ | 監視対象がアラート状態から復旧した際に発生するイベント。 |
Event Dataは以下の構造のオブジェクトになります。
フィールド名 |
| 型 | 説明 | 例 |
incident |
| object | ルートエレメント(固定) | - |
| incidentType | string | インシデントの種類:
| alert |
| description | string | インシデントの説明。
| Alert: Humidity sensor monitoring |
| projectId | number | インシデントの属するプロジェクトのID | 1000 |
| homeId | number | インシデントの属するHOMEのID | 100 |
| moduleId | string | インシデントの属するSmart Module ID | my-tsdb |
| monitorId | number | 監視のID | 9999 |
| monitorSnapshot | object | イベント発生時点の監視設定のスナップショット(詳細は後述参照) | 監視設定オブジェクト |
| evaluationTimeRange | object | 以下の2フィールドで構成されるobject。どちらのフィールドもRFC3339フォーマットのタイムスタンプ文字列。
| { begin: "2020-01-01T00:00:00.000Z", end: "2020-01-01T00:01:00.000Z" } |
| creationTime | string | イベント発生時のタイムスタンプ文字列(RFC3339フォーマット) | 2020-01-01T00:01:00.000 |
例)
{ "incident": { "incidentType": "alert", "description": "室温センサーの接続が確認できません", "projectId": 1000, "homeId": 2001, "moduleId": "my-tsdb", "monitorId: 912, "monitorSnapshot": { "name": "室温センサーの接続監視", "description": "室温センサーの切断を検知した際にアラートが発生します", "condition": { "conditionType": "timeSeriesHeartbeat", "seriesId": "temperature", "interval": 60, }, "incidentCustomDescriptions": { "alert": "室温センサーの接続が確認できません", "recovery": "室温センサーの接続が復帰しました" } }, "evaluationTimeRange": { begin: "2020-01-01T00:00:00.000Z", end: "2020-01-01T00:01:00.000Z" }, "creationTime": "2020-01-01T00:01:00.000Z" } }
|
監視設定オブジェクト
インシデント発生時点での監視設定のスナップショットです。
フィールド名 | 型 | 説明 | 例 |
name | string | 監視名称 | 室温センサーの接続監視 |
description | string | 監視の説明 | 室温センサーの切断を検知した際にアラートが発生します |
condition | object | 監視条件オブジェクト | 後述 |
incidentCustomDescriptions | object | 以下の2つstring型のフィールドを持つオブジェクト
どちらも、インシデント発生時に、incidentのdescriptionとして利用される。 | { "alert": "室温センサーの接続が確認できません", "recovery": "室温センサーの接続が復帰しました" } |
監視条件は種類に応じてオブジェクトの構造が異なります。
値監視 (Value Monitoring)
フィールド名 | 型 | 説明 | 例 |
conditionType | string | 監視条件の種類によって固定値。接続監視の場合は以下の値に固定:
"timeSeriesThreshold" | timeSeriesThreshold |
seriesId | string | 監視対象のTimeSeriesのID | 0107:ea7801cc5b86-humidity |
interval | number | データの監視間隔。この期間中に条件を満たすデータがどれだけ存在するかをカウントします。 | 60 |
numberOfBreachingDataPointsToAlert | number | この設定値以上に条件を満たすデータがintervalの期間中に存在する場合、アラートが発生します。 | 10 |
dataPointsEvaluationPolicy | string | 条件を満たすデータの数え上げ方に関する方針。以下のいずれか。
consecutive: 連続n回以上 total: 合計n回以上
| consecutive |
threshold | number | しきい値 | 30 |
operator | string | しきい値とデータの比較方法。しきい値とこの比較方法によってあるデータが条件を満たすか否かが判断されます。以下のいずれか。
lessThan: 小さい lessThanOrEqualTo: 以下 equal: 一致 notEqual: 不一致 greaterThanOrEqualTo: 以上 greaterThan: 大きい
| lessThan |
dataPointsDuration | number | 想定されるセンサーデータの発生間隔(秒)。 | 10 |
missingDataPointPolicy | string | dataPointsDurationの間隔に一つもデータが存在しない場合、データが不在としてみなします。データの不在についての扱い方を以下のいずれかの方法で決定します。
| ignore |
接続監視(Heartbeat Monitoring)
フィールド名 | 型 | 説明 | 例 |
conditionType | string | 監視条件の種類によって固定値。接続監視の場合は以下の値に固定:
"timeSeriesHeartbeat" | timeSeriesHeartbeat |
seriesId | string | 監視対象のTimeSeriesのID | 0107:ea7801cc5b86-humidity |
interval | number | 接続の確認間隔(秒)。この間に1度もデータの送信がない場合、センサーが非接続状態にあるとみなしアラートが発生します。 | 60 |