MODE JAPAN Blog

IoTを活用したデジタルトランスフォーメーションのための情報、開発の現場から技術的な情報や取り組みについてお届けします。

MODE 時系列データベースの使い方 (基本編)

From Developer （開発者より）

こんにちは、エンジニアの野本です。今までの記事でも度々紹介してきましたが、MODE ではセンサーデータを MODE 内部で実装した時系列データベース (Time Series Database 以下 TSDB) に格納しています。Sensor Cloud で提供される Web UI にセンサーデータのグラフ表示がありますがこれらのデータは TSDB に格納されています。TSDB は HTTP REST API によりデータの格納/取得などが可能です。Sensor Cloud もこの REST API を利用して TSDB に格納されているデータを表示しています。

f:id:reprimande:20200630180317p:plain

今回はこれら格納されているデータをどのように取得出来るかを紹介してみます。これを利用することによりユーザは TSDB のデータを利用した独自のアプリケーションを開発することも出来ます。

データ取得の基本

Series ID

各センサーデータの値は Series ID と呼ばれるユニークな ID をキーとして登録されています。Series ID は基本的には Sensor Cloud であれば Sensor Gateway によりセンサーの種類などに基づいて自動的に採番されます。TSDB に格納されている Series ID 一覧は以下のクエリにより確認出来ます。この Series ID ごとに TSDB に格納されているデータを取得することになります。

$ curl -X GET -H 'Authorization: ModeCloud [PROJECT_API_KEY]' https://api.tinkermode.com/homes/123/smartModules/tsdb/timeSeries

[
  {
    "homeId": 123,
    "id": "0001:01234567-value:0",
    "moduleId": "tsdb",
    "timeZone": "UTC"
  },
  {
    "homeId": 123,
    "id": "0001:01234567-temperature:0",
    "moduleId": "tsdb",
    "timeZone": "UTC"
  },
  {
    "homeId": 123,
    "id": "0001:01234567-co2:0",
    "moduleId": "tsdb",
    "timeZone": "UTC"
  }
]

期間内データの取得

TSDB からのデータ取得は対象の Series ID に対し期間指定をしての取得が基本になります。クエリパラメータの begin と end により期間指定を行います。

curl -X GET -H 'Authorization: ModeCloud [PROJECT_API_KEY]'  https://api.tinkermode.com/homes/123/smartModules/tsdb/timeSeries/0001:01234567-temperature:0/data\?begin\=2020-04-01T00:00:00.000Z\&end\=2020-04-30T23:59:59.999Z\&aggregation\=avg

{
  "aggregation": "avg",
  "begin": "2020-04-01T00:00:00Z",
  "data": [
    [
      "2020-04-01T00:00:00Z",
      5.150430555555556
    ],
    [
      "2020-04-02T00:00:00Z",
      5.131888888888889
    ],
    [
      "2020-04-03T00:00:00Z",
      5.163805555555555
    ],
...
    [
      "2020-04-28T00:00:00Z",
      5.746069444444443
    ],
    [
      "2020-04-29T00:00:00Z",
      5.507174825174825
    ],
    [
      "2020-04-30T00:00:00Z",
      5.217708333333333
    ]
  ],
  "end": "2020-04-30T23:59:59.999Z",
  "resolution": "1day",
  "seriesId": "0001:01234567-temperature:0"
}

ここで resolution が 1day となっていますが、先の begin と end で指定した期間の範囲によって取得する際のデータの解像度が自動的に決まります。データを取得するごとに期間内のデータを全て集め集計していると期間によっては膨大な時間がかかってしまうこともあります。MODE の TSDB では期間に対し適切な解像度にデータを集約し保存しており、広い期間であっても高速に集約データを取り出すことが出来ます。 期間と解像度の対応は以下のようになっています。

期間 解像度
5分以下 集約なし
5分 - 15分 5秒
15分 - 1時間 15秒
1時間 - 12時間 1分
12時間 - 5日 10分
5日 - 28日 1時間
28日 - 1年 1日
1年 - 5年 1週間
5年以上 1ヶ月

また、集約の種類は aggregation クエリパラメータにより指定出来ます。先の例では平均値 (avg) を指定しています。集約の種類は以下になります。

aggregation パラメータの値 集約の種類
avg 平均
max 最大値
min 最小値
sum 合計値
count データ数

生のデータポイントの取得

集約値ではなく生のデータポイントを参照したい場合は ts パラメータと limit パラメータを利用して取得することが出来ます。

$ curl -X GET -H 'Authorization: ModeCloud [PROJECT_API_KEY]' https://api.tinkermode.com/homes/123/smartModules/tsdb/timeSeries/0001:01234567-temperature:0/data\?ts\=2020-04-01T00:00:00.000Z\&limit\=100

{
  "data": [
    [
      "2020-04-01T00:00:42.733Z",
      5.42
    ],
    [
      "2020-04-01T00:01:42.792Z",
      5.38
    ],
    [
      "2020-04-01T00:02:42.659Z",
      5.36
    ],
…
   [
      "2020-04-01T08:17:40.001Z",
      4.96
    ],
    [
      "2020-04-01T08:18:39.866Z",
      4.94
    ],
    [
      "2020-04-01T08:19:40.12Z",
      4.96
    ]
  ],
  "limit": 100,
  "seriesId": "0001:01234567-temperature:0",
  "ts": "2020-04-01T00:00:00Z"
}

ts にセットされた日時を基準に limit に指定された値を最大数としてデータを取得します。limit は -500 から 500 の範囲で指定可能です。(なので取得出来るデータの最大数は 500 件です。)

格納データ期間

対象の Series ID に格納されているデータの期間を知りたい場合は以下のクエリで確認出来ます。

$ curl -X GET -H  'Authorization: ModeCloud [PROJECT_API_KEY]' https://api.tinkermode.com/homes/123/smartModules/tsdb/timeSeries/0001:01234567-temperature:0/timeRange

{
  "begin": "2017-07-27T02:38:20Z",
  "end": "2020-06-30T05:41:05.152Z",
  "seriesId": "0001:01234567-temperature:0"
}

データのエクスポート

任意の期間内のデータを一括で取得したい場合はファイルによるエクスポート機能を使います。 エクスポートを行いたい場合、まずエクスポートしたい期間と対象の Series ID を指定してエクスポートのリクエストを POST で発行します。

$ payload=$(cat <<EOF
{
    "begin": "2020-04-01T00:00:00Z",
    "end": "2020-04-01T23:59:59Z",
    "seriesIds": ["0001:01234567-temperature:0"]
}
EOF)

$ curl -X POST -H 'Authorization: ModeCloud [PROJECT_API_KEY]' -d '${payload}' https://api.tinkermode.com/homes/123/smartModules/tsdb/export

レスポンスとして以下情報が返却されます。

{
"dataUrl": "https://s3-us-west-2.amazonaws.com/scdata.tinkermode.com/export/123/XXXX.zip…",
"statusUrl": "https://s3-us-west-2.amazonaws.com/scdata.tinkermode.com/export/123/XXXX.json…"
}

dataUrl は最終的に生成されるエクスポートデータの URL です。ファイルは zip 形式になっています。statusUrl はエクスポート可能かどうかの状態が記述されている JSON ファイルの URL です。エクスポート処理はデータを収集しファイルを生成するのに時間がかかるので、この URL により完了したかどうかを確認出来ます。 ダウンロード出来る状態になると

{ "status": "SUCCESS" }

という内容になり、dataUrl からファイルをダウンロードすることが出来るようになります。 エクスポートしたファイルは以下のように日時と値が対となった csv 形式になっていています。

2020/06/01 00:00:42,4.88
2020/06/01 00:01:42,4.94
2020/06/01 00:02:42,4.94
2020/06/01 00:03:43,4.96
2020/06/01 00:04:42,4.98
2020/06/01 00:05:42,5
2020/06/01 00:06:42,5
2020/06/01 00:07:42,5.04
2020/06/01 00:08:42,5.06
2020/06/01 00:09:42,5.08
2020/06/01 00:10:42,5.12
2020/06/01 00:11:42,5.14
2020/06/01 00:12:42,5.14
...

まとめ

MODE の時系列データベースからデータを取り出す基本的な方法を紹介しました。必要に応じた形でデータを取り出すことが出来、また大量データでも扱いやすい解像度で高速にデータを取り出すことが出来ます。 以下ドキュメントで API の一覧を公開しています。データの格納や削除も API を利用して行えます。実際の利用時はこちらのドキュメントを参考に活用してみて下さい。

https://dev.tinkermode.com/platform/api/time-series-database

また、今回紹介した機能以外にも新たに追加されている便利な機能もあります。それらも今後紹介していきたいと思います。

また、MODE Labs ではこれらを利用した開発を弊社エンジニアのサポートとともに行えます。お気軽にご相談下さい!

www.tinkermode.jp