時系列データの取得

センサーデータは、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

  • recovery

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

  • end

{

  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型のフィールドを持つオブジェクト


  • alert

  • recovery


どちらも、インシデント発生時に、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: 無視する

  • breaching: 条件を満たしていると判断

  • notBreaching: 条件を満たしていないと判断

ignore


接続監視(Heartbeat Monitoring)

フィールド名

説明

conditionType

string

監視条件の種類によって固定値。接続監視の場合は以下の値に固定:


"timeSeriesHeartbeat"

timeSeriesHeartbeat

seriesId

string

監視対象のTimeSeriesのID

0107:ea7801cc5b86-humidity

interval

number

接続の確認間隔(秒)。この間に1度もデータの送信がない場合、センサーが非接続状態にあるとみなしアラートが発生します。

60