見出し画像

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

MODE Japan

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

今回はこれら格納されているデータをどのように取得出来るかを紹介してみます。これを利用することによりユーザは 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 では期間に対し適切な解像度にデータを集約し保存しており、広い期間であっても高速に集約データを取り出すことが出来ます。
期間と解像度の対応は以下のようになっています。

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

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

集約値ではなく生のデータポイントを参照したい場合は `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 を利用して行えます。実際の利用時はこちらのドキュメントを参考に活用してみて下さい。

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

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


※ 別媒体からの転載記事です。
※ 掲載内容は2020年6月当時のものです。