このチュートリアルでは、コンテキスト・データを CrateDB データベースに保存するために使用される、Generic Enabler である FIWARE QuantumLeap について紹介します。このチュートリアルでは、以前のチュートリアルで接続した IoT センサを有効にし、それらのセンサからの測定値をデータベースに保存します。このようなデータの時間ベースの集計を取得するには、QuantumLeap クエリAPIを使用するか、CrateDB HTTP エンドポイントに直接接続します。結果は、グラフまたは Grafana 時系列分析ツールを介して視覚化されます。

このチュートリアルでは、全体で cUrl コマンドを使用していますが、 Postman documentation も利用できます。

内容

詳細 (クリックして拡大)

時系列データの永続化とクエリ (CrateDB)
- 時系列データの解析
アーキテクチャ
前提条件
- Docker と Docker Compose
- Cygwin for Windows
起動
QuantumLeap を介して FIWARE を CrateDB データベースに接続
プログラミングによる時系列データへのアクセス
- CrateDB データを Grafana Dashboard として表示
次のステップ

時系列データの永続化とクエリ (CrateDB)

"Forever is composed of nows."

— Emily Dickinson

以前のチュートリアルでは、履歴コンテキスト・データを MySQL や PostgreSQL などのデータベースに永続化する方法を示しました。さらに、Short Term Historic のチュートリアルでは、MongoDB データベースを使用して履歴コンテキスト・データを永続化およびクエリするための STH-Comet Generic Enabler を導入しました。

FIWARE QuantumLeap は、CrateDB 時系列データベースへのデータ永続性のために特別に作成された代替 Generic Enabler であり、STH-Comet に代わるものです。

CrateDB は、Internet of Things で使用するために設計された分散 SQL DBMS です。1 秒間に多数のデータ・ポイントを取り込むことができ、リアルタイムでクエリすることができます。このデータベースは、地理空間データや時系列データなどの複雑なクエリの実行用に設計されています。この履歴データを取得することで、グラフやダッシュボードを作成し、時間の経過とともに傾向を表示することができます。

違いの概要を以下に示します :

QuantumLeap	STH-Comet
通知のための NGSI v2 インタフェースを提供します	通知のための NGSI v1 インタフェースを提供します
データを CrateDB データベースに保存します	データを MongoDB データベースに保存します
クエリ用に独自の HTTP エンドポイントを提供しますが、CrateDB にクエリすることもできます	クエリ用に独自の HTTP エンドポイントを提供します。MongoDB データベースに直接アクセスすることはできません
QuantumLeap は複雑なデータクエリを提供します (CrateDB のおかげで)	STH-Comet は限定された一連のクエリを提供しています
CrateDB は、NoSQL ストレージの上に構築されたスケーラブルな分散 SQL DBMS です	MongoDB は、ドキュメント・ベースの NoSQL データベースです
QuantumLeap の API は、ここにある OpenAPI でドキュメント化されています	STH-Comet は、ここにあるドキュメントで説明されています

基盤となるデータベースエンジンの相違点の詳細は、こちらを参照してください。

時系列データの解析

時系列データ分析を適切に使用するかどうかは、ユースケースと受け取るデータ測定の信頼性によって異なります。時系列データ分析を使用すると、次のような質問に答えることができます。

一定期間内のデバイスの最大測定値はどれくらいでしたか？
一定期間内のデバイスの平均測定値はどれくらいでしたか？
一定期間内にデバイスから送信された測定値の合計はどれくらいですか？

また、個々のデータポイントの重要性を減らして、スムージングによって外れ値を除外するために使用することもできます。

Grafana

Grafana は、このチュートリアルで使用する時系列解析ツール用のオープンソースソフトウェアです。これは、CrateDB を含む様々な時系列データベースと統合されています。Apache License 2.0 のライセンスで利用可能です。詳細は、https://grafana.com/ をご覧ください。

デバイス・モニタ

このチュートリアルの目的のために、一連のダミー IoT デバイスが作成され、Context Broker に接続されます。使用しているアーキテクチャとプロトコルの詳細は、IoT Sensors チュートリアルにあります。各デバイスの状態は、次の UltraLight デバイス・モニタの Web ページで確認できます : http://localhost:3000/device/monitor

デバイス履歴

QuantumLeap がデータの集計を開始すると、各デバイスの履歴の状態は、デバイス履歴の Web ページに表示されます : http://localhost:3000/device/history/urn:ngsi-ld:Store:001

アーキテクチャ

このアプリケーションは、以前のチュートリアルで作成したコンポーネントとダミー IoT デバイスをベースにしています。Orion Context Broker，IoT Agent for Ultralight 2.0 および QuantumLeap の 3 つの FIWARE コンポーネントを使用します。

したがって、全体的なアーキテクチャは次の要素で構成されます :

FIWARE Generic Enablers :
- FIWARE Orion Context Broker は、NGSI を使用してリクエストを受信します
- FIWARE IoT Agent for Ultralight 2.0 は、Ultralight 2.0 形式のダミー IoT デバイスからノース・バウンドの測定値を受信し、Context Broker の NGSI リクエストに変換してコンテキスト・エンティティの状態を変更します
- FIWARE QuantumLeap はコンテキストの変更をサブスクライブし、CrateDB データベースに永続化します
MongoDB データベース :
- Orion Context Broker が、データ・エンティティ、サブスクリプション、レジストレーションなどのコンテキスト・データ情報を保持するために使用します
- デバイスの URLs や Keys などのデバイス情報を保持するために IoT Agent によって使用されます
CrateDB データベース：
- 時間ベースの履歴コンテキスト・データを保持するデータシンクとして使用されます
- 時間ベースのデータクエリを解釈する HTTP エンドポイントを提供します
コンテキストプロバイダ : - HTTP 上で動作する Ultralight 2.0 プロトコルを使用して、ダミー IoT デバイスのセットとして機能する Web サーバです。 - このチュートリアルでは、 コンテキスト・プロバイダの NGSI proxy は使用しません

要素間のすべての対話は HTTP リクエストによって開始されるため、エンティティはコンテナ化され、公開されたポートから実行されます。

全体的なアーキテクチャを以下に示します :

前提条件

Docker と Docker Compose

物事を単純にするために、両方のコンポーネントが Docker を使用して実行されます。Docker は、さまざまコンポーネントをそれぞれの環境に分離することを可能にするコンテナ・テクノロジです。

Docker Windows にインストールするには、こちらの手順に従ってください
Docker Mac にインストールするには、こちらの手順に従ってください
Docker Linux にインストールするには、こちらの手順に従ってください

Docker Compose は、マルチコンテナ Docker アプリケーションを定義して実行するためのツールです。YAML file ファイルは、アプリケーションのために必要なサービスを構成するために使用します。つまり、すべてのコンテナ・サービスは 1 つのコマンドで呼び出すことができます。Docker Compose は、デフォルトで Docker for Windows と Docker for Mac の一部としてインストールされますが、Linux ユーザはここに記載されている手順に従う必要があります。

次のコマンドを使用して、現在の Docker バージョンと Docker Compose バージョンを確認できます :

docker-compose -v
docker version

Docker バージョン 18.03 以降と Docker Compose 1.21 以上を使用していることを確認し、必要に応じてアップグレードしてください。

Cygwin for Windows

シンプルな bash スクリプトを使用してサービスを開始します。Windows ユーザは cygwin をダウンロードして、Windows 上の Linux ディストリビューションと同様のコマンドライン機能を提供する必要があります。

起動

開始する前に、必要な Docker イメージをローカルで取得または構築しておく必要があります。リポジトリを複製し、以下のコマンドを実行して必要なイメージを作成してください :

git clone git@github.com:FIWARE/tutorials.Time-Series-Data.git
cd tutorials.Time-Series-Data

./services create

その後、リポジトリ内で提供される services Bash スクリプトを実行することによって、コマンドラインからすべてのサービスを初期化することができます :

./services start

ℹ️ 注: クリーンアップをやり直したい場合は、次のコマンドを使用して再起動することができます :
./services stop

QuantumLeap を介して FIWARE を CrateDB データベースに接続

この設定では、QuantumLeap は、ポート 8868 上の NGSI v2 通知を待ち受け、履歴データを CrateDB に永続化します。CrateDB は、ポート 4200 を使用してアクセスでき、直接クエリすることも、Grafana 分析ツールに接続することもできます。コンテキスト・データを提供するシステムの残りの部分は、以前のチュートリアルで説明しています。

CrateDB データベース・サーバの設定

  crate-db:
    image: crate:3.1.2
    hostname: crate-db
    ports:
        - "4200:4200"
        - "4300:4300"
    command: crate -Clicense.enterprise=false -Cauth.host_based.enabled=false  -Ccluster.name=democluster -Chttp.cors.enabled=true -Chttp.cors.allow-origin="*"

QuantumLeap の設定

  quantumleap:
    image: smartsdk/quantumleap
    hostname: quantumleap
    ports:
        - "8668:8668"
    depends_on:
      - cratedb
    environment:
      - CRATE_HOST=cratedb

Grafana の設定

grafana:
    image: grafana/grafana
    depends_on:
      - cratedb
    ports:
        - "3003:3000"
    environment:
        - GF_INSTALL_PLUGINS=crate-datasource,grafana-clock-panel,grafana-worldmap-panel

quantumleap コンテナは、1つのポートで待機しています：

QuantumLeap のポートの操作 - ポート 8668 サービスは、Orion Context Broker からの通知をリッスンするポートで、ここからユーザはデータをクエリできます。

CRATE_HOST 環境変数は、データが永続化される場所を定義します。

cratedb コンテナは、2つのポートでリッスンしています：

Admin UI は、ポート 4200 で利用できます
トランスポートプロトコルは、ポート 4300 で利用できます

grafana コンテナは、内部ポート 3000 を外部ポート 3003 に接続しています。これは Grafana UI が通常はポート 3000 で使用できるためですが、このポートはダミー IoT デバイスの UI によって既に取得されているため、別のポートに移動しています。Grafana 環境変数は、Grafana のドキュメントに記述されています。この設定により、チュートリアルの後半で CrateDB データベースに接続できるようになります。

コンテキスト・データの生成

このチュートリアルでは、コンテキストが定期的に更新されるシステムを監視する必要があります。ダミー IoT センサを使用してこれを行うことができます。http://localhost:3000/device/monitor でデバイス・モニタのページを開き、スマート・ドアのロックを解除し、スマート・ランプをオンにします。これは、ドロップ・ダウン・リストから適切なコマンドを選択し、send ボタンを押すことによって行うことができます。デバイスからの測定の流れは、同じページに表示されます :

サブスクリプションのセットアップ

動的コンテキスト・システムが起動したら、コンテキストの変更を直接 QuantumLeap に通知する必要があります。予想通り、これは Orion Context Broker のサブスクリプション・メカニズムを使用して行われます。QuantumLeap は、NGSI v2 通知を直接受け入れるため、attrsFormat=legacy 属性は不要です。

サブスクリプションについては、次のサブセクションで説明します。サブスクリプションの詳細については、以前のチュートリアルや QuantumLeap のドキュメントのサブスクリプション・セクションを参照してください。

モーション・センサのカウント・イベントの集計

モーション・センサの変化率は、現実世界の事象によって引き起こされます。結果を集約するためには、すべてのイベントを受け取る必要があります。

これは、Orion Context Broker の /v2/subscription エンドポイントに POST リクエストをすることで行われます。

fiware-service と fiware-servicepath ヘッダは、サブスクリプションをフィルタリングして、接続された IoT センサからの測定値のみをリッスンためにするために使用されます
リクエストのボディの idPattern は、すべてのモーション・センサのデータ変更を QuantumLeap に通知されるようにします
notification URL は、公開されたポートと一致する必要があります

metadata 属性により、CrateDB データベース内の time_index 列が、CrateDB 自体のレコードの作成時間を使用するのではなく、Orion Context Broker が使用する MongoDB データベース内のデータと一致することが保証されます。

1️⃣ リクエスト :

curl -iX POST \
  'http://localhost:1026/v2/subscriptions/' \
  -H 'Content-Type: application/json' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /' \
  -d '{
  "description": "description": "Notify QuantumLeap of count changes of any Motion Sensor",
  "subject": {
    "entities": [
      {
        "idPattern": "Motion.*"
      }
    ],
    "condition": {
      "attrs": [
        "count"
      ]
    }
  },
  "notification": {
    "http": {
      "url": "http://quantumleap:8668/v2/notify"
    },
    "attrs": [
      "count"
    ],
    "metadata": ["dateCreated", "dateModified"]
  },
  "throttling": 1
}'

ランプの明度のサンプリング

スマート・ランプの明るさは常に変化していますので、最小値や最大値、変化率などの関連する統計値を計算するために値をサンプリングするだけです。

これは、Orion Context Broker の /v2/subscription エンドポイントに POST リクエストを行い、リクエストのボディに throttling 属性を含めることによって行われます。

fiware-service と fiware-servicepath ヘッダは、サブスクリプションをフィルタリングして、接続された IoT センサからの測定値のみをリッスンためにするために使用されます
リクエストのボディの idPattern は、すべてのモーション・センサのデータ変更を QuantumLeap に通知されるようにします
notification URL は、公開されたポートと一致する必要があります
throttling 値は、変更がサンプリングされる割合を定義します

2️⃣ リクエスト :

curl -iX POST \
  'http://localhost:1026/v2/subscriptions/' \
  -H 'Content-Type: application/json' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /' \
  -d '{
  "description": "Notify QuantumLeap on luminosity changes on any Lamp",
  "subject": {
    "entities": [
      {
        "idPattern": "Lamp.*"
      }
    ],
    "condition": {
      "attrs": [
        "luminosity"
      ]
    }
  },
  "notification": {
    "http": {
      "url": "http://quantumleap:8668/v2/notify"
    },
    "attrs": [
      "luminosity", "location"
    ],
    "metadata": ["dateCreated", "dateModified"]
  },
  "throttling": 1
}'

QuantumLeap のサブスクリプションの確認

何かをする前に、:one: と :two: のステップで作成したサブスクリプションをチェックしてください (すなわち、それぞれが少なくとも1つの通知が送信されたか)

3️⃣ リクエスト:

curl -X GET \
  'http://localhost:1026/v2/subscriptions/' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /'

レスポンス:

[
    {
        "id": "5be07427be9a2d09cf677f08",
        "description": "Notify QuantumLeap of count changes of any Motion Sensor",
        "status": "active",
        "subject": { ...ETC },
        "notification": {
            "timesSent": 6,
            "lastNotification": "2018-09-02T08:36:04.00Z",
            "attrs": ["count"],
            "attrsFormat": "normalized",
            "http": { "url": "http://quantumleap:8668/v2/notify" },
            "lastSuccess": "2018-09-02T08:36:04.00Z"
        },
        "throttling": 1
    },
    {
        "id": "5be07427be9a2d09cf677f09",
        "description": "Notify QuantumLeap on luminosity changes on any Lamp",
        "status": "active",
        "subject": { ...ETC },
        "notification": {
            "timesSent": 4,
            "lastNotification": "2018-09-02T08:36:00.00Z",
            "attrs": ["luminosity"],
            "attrsFormat": "normalized",
            "http": { "url": "http://quantumleap:8668/v2/notify" },
            "lastSuccess": "2018-09-02T08:36:01.00Z"
        },
        "throttling": 1
    }
]

時系列データ・クエリ (QuantumLeap API)

QuantumLeapは、CrateDB バックエンドをラッピングする API を提供し、複数のタイプのクエリを実行することもできます。API のドキュメントはこちらです。バージョンに注意してください。quantumleap コンテナへのアクセス権がある場合 (例えば、localhost で実行中、またはポート・フォワーディングしている)、 http://localhost:8668/v2/ui を介して API をナビゲートできます。

QuantumLeap API - 最初の N個のサンプリング値のリスト

さて、QuantumLeap が永続的な値であることを確認するために、最初のクエリを始めましょう。この例は、Lamp:001 から、最初にサンプリングされた 3つの luminosity 値を示しています。

Fiware-Service と Fiware-ServicePath ヘッダの使用に注意してください。これらは、マルチテナント・シナリオでこのようなヘッダを使用してデータを強制的にプッシュする場合にのみ必要です。これらのヘッダを追加しないと、データが返されません。

4️⃣ リクエスト :

curl -X GET \
  'http://localhost:8668/v2/entities/Lamp:001/attrs/luminosity?=3&limit=3' \
  -H 'Accept: application/json' \
  -H 'Fiware-Service: openiot' \
  -H 'Fiware-ServicePath: /'

レスポンス :

{
    "data": {
        "attrName": "luminosity",
        "entityId": "Lamp:001",
        "index": [
            "2018-10-29T14:27:26",
            "2018-10-29T14:27:28",
            "2018-10-29T14:27:29"
        ],
        "index": ["2018-10-29T14:27:26", "2018-10-29T14:27:28", "2018-10-29T14:27:29
        "values": [2000, 1991, 1998]
    }
}

QuantumLeap API - N 個のサンプリング値をオフセットでリスト

この例は、Motion:001 の 4番目、5番目および6番目のサンプリングされた count 値を示しています。

5️⃣ リクエスト :

curl -X GET \
  'http://localhost:8668/v2/entities/Motion:001/attrs/count?offset=3&limit=3' \
  -H 'Accept: application/json' \
  -H 'Fiware-Service: openiot' \
  -H 'Fiware-ServicePath: /'

レスポンス :

{
    "data": {
        "attrName": "count",
        "entityId": "Motion:001",
        "index": [
            "2018-10-29T14:23:53.804000",
            "2018-10-29T14:23:54.812000",
            "2018-10-29T14:24:00.849000"
        ],
        "index": ["2018-10-29T14:23:53.804000", "2018-10-29T14:23:54.812000", "2018-10-29T14:24:00.849000"],
        "values": [0, 1, 0]
    }
}

QuantumLeap API - 最新のN個のサンプリングされた値のリスト

この例は、Motion:001 の最新の3個のサンプリングされた count 値を示しています。

6️⃣ リクエスト :

curl -X GET \
  'http://localhost:8668/v2/entities/Motion:001/attrs/count?lastN=3' \
  -H 'Accept: application/json' \
  -H 'Fiware-Service: openiot' \
  -H 'Fiware-ServicePath: /'

レスポンス :

{
    "data": {
        "attrName": "count",
        "entityId": "Motion:001",
        "index": [
            "2018-10-29T15:03:45.113000",
            "2018-10-29T15:03:46.118000",
            "2018-10-29T15:03:47.111000"
        ],
        "index": ["2018-10-29T15:03:45.113000", "2018-10-29T15:03:46.118000", "2018-10-29T15:03:47.111000"],
        "values": [1, 0, 1]
    }
}

QuantumLeap API - 期間別にグループ化された値の合計をリスト

この例では、Motion:001 の1分ごとの最後の3個の合計 count 値を示しています。

QuantumLeap バージョン >= 0.4.1 以上が必要です。次のような単純な GET でバージョンを確認することができます :

curl -X GET \
  'http://localhost:8668/v2/version' \
  -H 'Accept: application/json'

7️⃣ リクエスト :

curl -X GET \
  'http://localhost:8668/v2/entities/Motion:001/attrs/count?aggrMethod=count&aggrPeriod=minute&lastN=3' \
  -H 'Accept: application/json' \
  -H 'Fiware-Service: openiot' \
  -H 'Fiware-ServicePath: /'

レスポンス :

{
    "data": {
        "attrName": "count",
        "entityId": "Motion:001",
        "index": [
            "2018-10-29T15:03:00.000000",
            "2018-10-29T15:04:00.000000",
            "2018-10-29T15:05:00.000000"
        ],
        "index": ["2018-10-29T15:03:00.000000", "2018-10-29T15:04:00.000000", "2018-10-29T15:05:00.000000"],
        "values": [21, 10, 11]
    }
}

QuantumLeap API - 期間別にグループ化された最小値をリスト

この例では、1分ごとの Lamp:001 からの最小 luminosity 値を示しています。

QuantumLeap バージョン >= 0.4.1 以上が必要です。次のような単純な GET でバージョンを確認することができます :

curl -X GET \
  'http://localhost:8668/v2/version' \
  -H 'Accept: application/json'

8️⃣ リクエスト :

curl -X GET \
  'http://localhost:8668/v2/entities/Lamp:001/attrs/luminosity?aggrMethod=min&aggrPeriod=minute&lastN=3' \
  -H 'Accept: application/json' \
  -H 'Fiware-Service: openiot' \
  -H 'Fiware-ServicePath: /'

レスポンス :

{
    "data": {
        "attrName": "count",
        "entityId": "Motion:001",
        "index": [
            "2018-10-29T15:03:00.000000",
            "2018-10-29T15:04:00.000000",
            "2018-10-29T15:05:00.000000"
        ],
        "index": ["2018-10-29T15:03:00.000000", "2018-10-29T15:04:00.000000", "2018-10-29T15:05:00.000000"],
        "values": [1720, 1878, 1443]
    }
}

QuantumLeap API - ある期間の最大値のリスト

この例では、2018-06-27T09:00:00 から 2018-06-30T23:59:59 までの間に発生した、Lamp:001 の最大の luminosity 値を示しています。

9️⃣ リクエスト :

curl -X GET \
  'http://localhost:8668/v2/entities/Lamp:001/attrs/luminosity?aggrMethod=max&fromDate=2018-06-27T09:00:00&toDate=2018-06-30T23:59:59' \
  -H 'Accept: application/json' \
  -H 'Fiware-Service: openiot' \
  -H 'Fiware-ServicePath: /'

レスポンス :

{
    "data": {
        "attrName": "luminosity",
        "entityId": "Lamp:001",
        "index": [],
        "values": [1753]
    }
}

QuantumLeap API - ポイント付近のデバイスの最新の N 個のサンプル値をリスト

この例は、 52°33'16.9"N 13°23'55.0"E (Bornholmer Straße 65, Berlin, Germany) から半径5km以内にある最新の４つのサンプリングされたランプの luminosity 値を示しています。デバイス・モニタのページで利用可能なすべてのランプをつけると、 Lamp:001 と Lamp:004 のデータを見ることができるはずです。

ℹ️ 注: 地理的クエリは、 NGSI v2 仕様の地理的クエリのセクションに詳述されている完全なクエリのセットを実装する、 QuantumLeap のバージョン 0.5 からのみ利用可能です。

1️⃣0️⃣ リクエスト :

curl -X GET \
  'http://localhost:8668/v2/types/Lamp/attrs/luminosity?lastN=4&georel=near;maxDistance:5000&geometry=point&coords=52.5547,13.3986' \
  -H 'Accept: application/json' \
  -H 'Fiware-Service: openiot' \
  -H 'Fiware-ServicePath: /'

レスポンス :

{
    "data": {
        "attrName": "luminosity",
        "entities": [
            {
                "entityId": "Lamp:001",
                "index": ["2018-12-13T16:35:58.284", "2018-12-13T16:36:58.216"],
                "values": [999, 999]
            },
            {
                "entityId": "Lamp:004",
                "index": ["2018-12-13T16:35:04.351", "2018-12-13T16:36:04.282"],
                "values": [948, 948]
            }
        ],
        "entityType": "Lamp"
    }
}

QuantumLeap API - エリア内のデバイスの最新の N 個のサンプル値をリスト

この例は、 52°33'16.9"N 13°23'55.0"E (Bornholmer Straße 65, Berlin, Germany) を中心とする一辺 200 m の正方形の内側にあるランプの最新の4つのサンプリングされた luminosity 値を示しています。デバイス・モニタのページで利用可能なすべてのランプをつけたとしても、Lamp:001 のデータだけを見るべきです。

ℹ️ 注: 地理的クエリは、 NGSI v2 仕様の地理的クエリのセクションに詳述されている完全なクエリのセットを実装する、 QuantumLeap のバージョン 0.5 からのみ利用可能です。

1️⃣1️⃣ リクエスト :

curl -X GET \
  'http://localhost:8668/v2/types/Lamp/attrs/luminosity?lastN=4&georel=coveredBy&geometry=polygon&coords=52.5537,13.3996;52.5557,13.3996;52.5557,13.3976;52.5537,13.3976;52.5537,13.3996' \
  -H 'Accept: application/json' \
  -H 'Fiware-Service: openiot' \
  -H 'Fiware-ServicePath: /'

レスポンス :

{
    "data": {
        "attrName": "luminosity",
        "entities": [
            {
                "entityId": "Lamp:001",
                "index": [
                    "2018-12-13T17:08:56.041",
                    "2018-12-13T17:09:55.976",
                    "2018-12-13T17:10:55.907",
                    "2018-12-13T17:11:55.833"
                ],
                "values": [999, 999, 999, 999]
            }
        ],
        "entityType": "Lamp"
    }
}

時系列データ・クエリ (CrateDB API)

CrateDB は、SQL クエリを送信するために使用できる HTTP エンドポイントを提供します。エンドポイントは、<servername:port>/_sql 下でアクセス可能です。

SQL ステートメントは POST リクエストの本体として JSON 形式で送信されます。ここで、SQL ステートメントは stmt 属性の値です。

CrateDB にクエリするときと、QuantumLeap にするとき? 経験則として、QuantumLeap で常に作業することを好む理由は次のとおりです。

あなたの経験は Orion のような FIWARE NGSI API に近いでしょう

あなたのアプリケーションは、CrateDB の仕様や QuantumLeap の実装の詳細に結びつくことはありません

QuantumLeap は他のバックエンドにも簡単に拡張でき、あなたのアプリはフリーで互換性を得ることができます

デプロイメントが配布されている場合は、データベースのポートを外部に公開する必要はありません

QuantumLeap で実行したいクエリがサポートされていないことが確かな場合は、 CrateDB でクエリする必要がありますが、開発チームが認識できるように QuantumLeap の GitHub リポジトリで、issue をオープンしてください。

CrateDB API - データの永続性のチェック

データが永続化されているかどうかを確認する別の方法は、table_schema が作成されたことをチェックすることです。次のように、CrateDB HTTP エンドポイントにリクエストすることでこれを行うことができます：

1️⃣2️⃣ リクエスト :

curl -iX POST \
  'http://localhost:4200/_sql' \
  -H 'Content-Type: application/json' \
  -d '{"stmt":"SHOW SCHEMAS"}'

レスポンス :

{
    "cols": ["table_schema"],
    "rows": [["doc"], ["information_schema"], ["sys"], ["mtopeniot"], ["pg_catalog"]],
    "rowcount": 5,
    "duration": 10.5146
}

スキーマ名は、mt プレフィックスとそれに続く、小文字の fiware-service ヘッダで構成されます。IoT Agent は、FIWARE-Service ヘッダ openiot を使用して、ダミー IoT デバイスから測定値を転送します。これらは mtopeniot スキーマの下に保持されています。

mtopeniot が存在しない場合は、QuantumLeap のサブスクリプションが正しく設定されていません。サブスクリプションが存在し、データを正しい場所に送信するように設定されていることを確認します。

QuantumLeap は、エンティティ型に基づいて CrateDB データベース内の別のテーブルにデータを永続化します。テーブル名は、et プレフィックスとエンティティ型の名前を小文字にして形成されます。

1️⃣3️⃣ リクエスト :

curl -X POST \
  'http://localhost:4200/_sql' \
  -H 'Content-Type: application/json' \
  -d '{"stmt":"SHOW TABLES"}'

レスポンス :

{
    "cols": ["table_schema", "table_name"],
    "rows": [["mtopeniot", "etmotion"], ["mtopeniot", "etlamp"]],
    "rowcount": 2,
    "duration": 14.2762
}

レスポンスは、モーション・センサのデータとスマート・ランプのデータの両方がデータベースに保持されていることを示します。

CrateDB API - 最初の N個のサンプリング値のリスト

SQL 文は ORDER BY と LIMIT を使用してデータをソートします。詳細は、CrateDB のドキュメントを参照してください。

1️⃣4️⃣ リクエスト :

curl -iX POST \
  'http://localhost:4200/_sql' \
  -H 'Content-Type: application/json' \
  -d '{"stmt":"SELECT * FROM mtopeniot.etlamp WHERE entity_id = '\''Lamp:001'\'' ORDER BY time_index ASC LIMIT 3"}'

レスポンス :

{
    "cols": ["entity_id", "entity_type", "fiware_servicepath", "luminosity", "time_index"],
    "rows": [
        ["Lamp:001", "Lamp", "/", 1750, 1530262765000],
        ["Lamp:001", "Lamp", "/", 1507, 1530262770000],
        ["Lamp:001", "Lamp", "/", 1390, 1530262775000]
    ],
    "rowcount": 3,
    "duration": 21.8338
}

CrateDB API - N 個のサンプリング値をオフセットでリスト

SQL 文は、OFFSET 句を使用して必要な行を取り出します。詳細は、CrateDB のドキュメントを参照してください。

1️⃣5️⃣ リクエスト :

curl -iX POST \
  'http://localhost:4200/_sql' \
  -H 'Content-Type: application/json' \
  -d '{"stmt":"SELECT * FROM mtopeniot.etmotion WHERE entity_id = '\''Motion:001'\'' order by time_index ASC LIMIT 3 OFFSET 3"}'

レスポンス :

{
    "cols": ["count", "entity_id", "entity_type", "fiware_servicepath", "time_index"],
    "rows": [
        [0, "Motion:001", "Motion", "/", 1530262791452],
        [1, "Motion:001", "Motion", "/", 1530262792469],
        [0, "Motion:001", "Motion", "/", 1530262793472]
    ],
    "rowcount": 3,
    "duration": 54.215
}

CrateDB API - 最新のN個のサンプリングされた値のリスト

SQL 文は、最後の N 行を取り出すために LIMIT 節と結合された、ORDER BY ... DESC 節を使用します。詳細は、CrateDBのドキュメントを参照してください。

1️⃣6️⃣ リクエスト :

curl -iX POST \
  'http://localhost:4200/_sql' \
  -H 'Content-Type: application/json' \
  -d '{"stmt":"SELECT * FROM mtopeniot.etmotion WHERE entity_id = '\''Motion:001'\''  ORDER BY time_index DESC LIMIT 3"}'

レスポンス :

{
    "cols": ["count", "entity_id", "entity_type", "fiware_servicepath", "time_index"],
    "rows": [
        [0, "Motion:001", "Motion", "/", 1530263896550],
        [1, "Motion:001", "Motion", "/", 1530263894491],
        [0, "Motion:001", "Motion", "/", 1530263892483]
    ],
    "rowcount": 3,
    "duration": 18.591
}

CrateDB API - 期間別にグループ化された値の合計をリスト

SQL 文は、SUM 関数と GROUP BY 句を使用して関連するデータを取得します。 CrateDB は、タイムスタンプを切り捨ててグループ化できるデータに変換するための一連の日時関数を提供しています。

1️⃣7️⃣ リクエスト :

curl -iX POST \
  'http://localhost:4200/_sql' \
  -H 'Content-Type: application/json' \
  -d '{"stmt":"SELECT DATE_FORMAT (DATE_TRUNC ('\''minute'\'', time_index)) AS minute, SUM (count) AS sum FROM mtopeniot.etmotion WHERE entity_id = '\''Motion:001'\'' GROUP BY minute LIMIT 3"}'

レスポンス :

{
    "cols": ["minute", "sum"],
    "rows": [
        ["2018-06-29T09:17:00.000000Z", 12],
        ["2018-06-29T09:34:00.000000Z", 10],
        ["2018-06-29T09:08:00.000000Z", 11],
        ["2018-06-29T09:40:00.000000Z", 3],
        ...etc
    ],
    "rowcount": 42,
    "duration": 22.9832
}

CrateDB API - 期間別にグループ化された最小値をリスト

SQL 文は、MIN 関数と GROUP BY 句を使用して関連するデータを取得します。 CrateDB は、タイムスタンプを切り捨ててグループ化できるデータに変換するための一連の日時関数を提供しています。

1️⃣8️⃣ リクエスト :

curl -iX POST \
  'http://localhost:4200/_sql' \
  -H 'Content-Type: application/json' \
  -d '{"stmt":"SELECT DATE_FORMAT (DATE_TRUNC ('\''minute'\'', time_index)) AS minute, MIN (luminosity) AS min FROM mtopeniot.etlamp WHERE entity_id = '\''Lamp:001'\'' GROUP BY minute"}'

レスポンス :

{
    "cols": ["minute", "min"],
    "rows": [
        ["2018-06-29T09:34:00.000000Z", 1516],
        ["2018-06-29T09:17:00.000000Z", 1831],
        ["2018-06-29T09:40:00.000000Z", 1768],
        ["2018-06-29T09:08:00.000000Z", 1868],
        ...etc
    ],
    "rowcount": 40,
    "duration": 13.1854
}

CrateDB API - ある期間の最大値のリスト

SQL 文は、MAX関数と WHERE 句を使用して関連するデータを取得します。CrateDB は、さまざまな方法でデータをアグリゲーションするため、一連のアグリゲーション関数を提供しています。

1️⃣9️⃣ リクエスト :

curl -iX POST \
  'http://localhost:4200/_sql' \
  -H 'Content-Type: application/json' \
  -d '{"stmt":"SELECT MAX(luminosity) AS max FROM mtopeniot.etlamp WHERE entity_id = '\''Lamp:001'\'' and time_index >= '\''2018-06-27T09:00:00'\'' and time_index < '\''2018-06-30T23:59:59'\''"}'

レスポンス :

{
    "cols": ["max"],
    "rows": [[1753]],
    "rowcount": 1,
    "duration": 26.7215
}

プログラミングによる時系列データへのアクセス

指定された時系列の JSON レスポンスが取得されると、生のデータを表示することはエンドユーザにとってほとんど役に立たちません。これは、棒グラフ、折れ線グラフ、またはテーブル・リストに表示するために操作する必要があります。これは、グラフィカルなツールではないため、QuantumLeap のドメイン内にはありませんが、Wirecloud や Knowage などのマッシュアップやダッシュボード・コンポーネントに任せることができます。

また、コーディング環境に適したサード・パーティのグラフ作成ツール (chartjs など) を使用して、検索して表示することもできます。この例は、Git Repository の history コントローラ内にあります。

基本的な処理は、検索と属性マッピングの 2 つのステップで構成されています。サンプルコードは以下のとおりです :

function readCrateLampLuminosity(id, aggMethod) {
    return new Promise(function(resolve, reject) {
        const sqlStatement =
            "SELECT DATE_FORMAT (DATE_TRUNC ('minute', time_index)) AS minute, " +
            aggMethod +
            "(luminosity) AS " +
            aggMethod +
            " FROM mtopeniot.etlamp WHERE entity_id = 'Lamp:" +
            id +
            "' GROUP BY minute ORDER BY minute";
        const options = {
            method: "POST",
            url: crateUrl,
            headers: { "Content-Type": "application/json" },
            body: { stmt: sqlStatement },
            json: true
        };
        request(options, (error, response, body) => {
            return error ? reject(error) : resolve(body);
        });
    });
}

function crateToTimeSeries(crateResponse, aggMethod, hexColor) {
    const data = [];
    const labels = [];
    const color = [];

    if (crateResponse && crateResponse.rows && crateResponse.rows.length > 0) {
        _.forEach(crateResponse.rows, element => {
            const date = moment(element[0]);
            data.push({ t: date, y: element[1] });
            labels.push(date.format("HH:mm"));
            color.push(hexColor);
        });
    }

    return {
        labels,
        data,
        color
    };
}

変更されたデータは、フロント・エンドに渡され、サード・パーティのグラフ作成ツールによって処理されます。結果は次のとおりです : http://localhost:3000/device/history/urn:ngsi-ld:Store:001

CrateDB データを Grafana Dashboard として表示

CrateDB は、QuantumLeap の時系列データ・シンクとして選択されています。他の多くのメリットの中でも、 Grafana 時系列分析ツールとシームレスに統合されています。 Grafana を使用して、アグリゲートされたセンサ・データを表示することができます。ここでダッシュボードを構築するための完全なチュートリアルを見つけることができます。次の簡単な手順では、ランプの luminosity データのグラフを接続して表示する方法をまとめています。

docker-compose ファイルは Grafana UI のインスタンスをポート 3003 でリッスンしているので、ログイン・ページは次の場所にあります: http://localhost:3003/login。デフォルトのユーザー名は admin で、デフォルトのパスワードは admin です。

データソースの設定

ログイン後、データソースは、http://localhost:3003/datasources において、次の値で設定する必要があります：

Name Lamp
Type Crate
URL http://cratedb:4200
Access Server (デフォルト)
Schema mtopeniot
Table etlamp
Time column time_index

Save をクリックすると、Data Source added メッセージが返されます j

ダッシュボードの設定

新しいダッシュボードを表示するには、+ ボタンをクリックして New Dashboard を選択するか、直接 http://localhost:3003/dashboard/new?orgId=1 に移動します。その後、Graph ダッシュボード・タイプを選択します。

ダッシュボードを設定するには、Panel title をクリックし、ドロップ・ダウンリストから edit を選択します。

太字のテキストの次の値は、グラフ作成ウィザードに配置する必要があります :

Data Source Lamp (以前に作成したデータソースから選択)
FROM mtopeniot.etlamp WHERE entity_id = Lamp:001
Select Min luminosity
Group By time Interval Minute Format as Time Series

最終結果は以下の通りです :

次のステップ

高度な機能を追加することで、アプリケーションに複雑さを加える方法を知りたいですか？このシリーズの他のチュートリアルを読むことで見つけることができます

Uh oh!

FilesExpand file tree

README.ja.md

Latest commit

History

README.ja.md

File metadata and controls

内容

時系列データの永続化とクエリ (CrateDB)

時系列データの解析

Grafana

デバイス・モニタ

デバイス履歴

アーキテクチャ

前提条件

Docker と Docker Compose

Cygwin for Windows

起動

QuantumLeap を介して FIWARE を CrateDB データベースに接続

CrateDB データベース・サーバの設定

QuantumLeap の設定

Grafana の設定

コンテキスト・データの生成

サブスクリプションのセットアップ

モーション・センサのカウント・イベントの集計

1️⃣ リクエスト :

ランプの明度のサンプリング

2️⃣ リクエスト :

QuantumLeap のサブスクリプションの確認

3️⃣ リクエスト:

レスポンス:

時系列データ・クエリ (QuantumLeap API)

QuantumLeap API - 最初の N個の サンプリング値のリスト

4️⃣ リクエスト :

レスポンス :

QuantumLeap API - N 個のサンプリング値をオフセットでリスト

5️⃣ リクエスト :

レスポンス :

QuantumLeap API - 最新のN個のサンプリングされた値のリスト

6️⃣ リクエスト :

レスポンス :

QuantumLeap API - 期間別にグループ化された値の合計をリスト

7️⃣ リクエスト :

レスポンス :

QuantumLeap API - 期間別にグループ化された最小値をリスト

8️⃣ リクエスト :

レスポンス :

QuantumLeap API - ある期間の最大値のリスト

9️⃣ リクエスト :

レスポンス :

QuantumLeap API - ポイント付近のデバイスの最新の N 個のサンプル値をリスト

1️⃣0️⃣ リクエスト :

レスポンス :

QuantumLeap API - エリア内のデバイスの最新の N 個のサンプル値をリスト

1️⃣1️⃣ リクエスト :

レスポンス :

時系列データ・クエリ (CrateDB API)

CrateDB API - データの永続性のチェック

1️⃣2️⃣ リクエスト :

レスポンス :

1️⃣3️⃣ リクエスト :

レスポンス :

CrateDB API - 最初の N個の サンプリング値のリスト

1️⃣4️⃣ リクエスト :

レスポンス :

CrateDB API - N 個のサンプリング値をオフセットでリスト

1️⃣5️⃣ リクエスト :

レスポンス :

CrateDB API - 最新のN個のサンプリングされた値のリスト

1️⃣6️⃣ リクエスト :

レスポンス :

CrateDB API - 期間別にグループ化された値の合計をリスト

1️⃣7️⃣ リクエスト :

レスポンス :

CrateDB API - 期間別にグループ化された最小値をリスト

1️⃣8️⃣ リクエスト :

レスポンス :

CrateDB API - ある期間の最大値のリスト

1️⃣9️⃣ リクエスト :

レスポンス :

QuantumLeap API - 最初の N個のサンプリング値のリスト

CrateDB API - 最初の N個のサンプリング値のリスト