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

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

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

"Forever is composed of nows."

— Emily Dickinson

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

FIWARE QuantumLeap は、永続化および時系列データベース (現在の CrateDB および TimescaleDB) をクエリする API を提供するために特別に作成された代替 Generic Enabler です。したがって、 STH-Comet の代替手段を提供します。

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

TimescaleDB は、時系列データの PostgreSQL を、時空間全体の自動パーティション分割 (パーティション・キー) でスケーリングしますが、標準の PostgreSQL インターフェイスを保持します。つまり、TimescaleDB は通常のテーブルのように見えるものを公開しますが、実際には、実際のデータを構成する多くの個々のテーブルの抽象化または仮想ビューにすぎません。 TimescaleDB 拡張機能と組み合わせて、 geo-timeseries をサポートできます。

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

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

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

時系列データの解析¶

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

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

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

Grafana¶

Grafana は、このチュートリアルで使用する時系列解析ツール用のオープンソースソフトウェアです。これは、CrateDB および TimescaleDB を含むさまざまな時系列データベースと統合します。Apache License 2.0 の下でライセンスされています。詳細については、https://grafana.com/ を参照してください。

デバイス・モニタ¶

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

FIWARE 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-v2 を使用してリクエストを受信します
- FIWARE IoT Agent for Ultralight 2.0 は、Ultralight 2.0 形式のダミー IoT デバイスからノース・バウンドの測定値を受信し、Context Broker の NGSI-v2 リクエストに変換してコンテキスト・エンティティの状態を変更します
- 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 バージョン 20.10 以降と Docker Compose 1.29 以上を使用していることを確認し、必要に応じてアップグレードしてください。

Cygwin for Windows¶

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

起動¶

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

git clone https://github.com/FIWARE/tutorials.Time-Series-Data.git
cd tutorials.Time-Series-Data
git checkout NGSI-v2

./services create

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

./services start

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

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

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

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

  crate-db:
    image: crate:4.1.4
    hostname: crate-db
    ports:
        - "4200:4200"
        - "4300:4300"
    command:
        crate -Cauth.host_based.enabled=false  -Ccluster.name=democluster
        -Chttp.cors.enabled=true -Chttp.cors.allow-origin="*"
    environment:
      - CRATE_HEAP_SIZE=2g

CrateDB が max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144] エラーで直ぐに終了する場合、ホストマシンで sudo sysctl -w vm.max_map_count=262144 コマンドを実行することで修正できます。詳細については、CrateDB のドキュメントと、Docker トラブルシューティング・ガイドを参照してください。

QuantumLeap の設定¶

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

Grafana の設定¶

grafana:
    image: grafana/grafana
    depends_on:
      - cratedb
    ports:
        - "3003:3000"
    environment:
        - GF_INSTALL_PLUGINS=https://github.com/orchestracities/grafana-map-plugin/archive/master.zip;grafana-map-plugin,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 データベースに接続できるようになります。この設定では、NGSI v2 エンティティをマップ上に表示するのに役立つカスタム・マップ・プラグインもインポートします。

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

このチュートリアルでは、コンテキストが定期的に更新されるシステムを監視する必要があります。ダミー 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": "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 値は、変更がサンプリングされる割合を定義します

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

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",
        "location"
      ]
    }
  },
  "notification": {
    "http": {
      "url": "http://quantumleap:8668/v2/notify"
    },
    "attrs": [
      "luminosity", "location"
    ],
    "metadata": ["dateCreated", "dateModified"]
  },
  "throttling": 1
}'

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

何かをする前に、1 と 2 のステップで作成したサブスクリプションをチェックしてください (すなわち、それぞれが少なくとも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?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/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/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 からのみ利用可能です。

10 リクエスト :¶

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 からのみ利用可能です。

11 リクエスト :¶

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 エンドポイントにリクエストすることでこれを行うことができます：

12 リクエスト :¶

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 プレフィックスとエンティティ型の名前を小文字にして形成されます。

13 リクエスト :¶

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 のドキュメントを参照してください。

14 リクエスト :¶

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 のドキュメントを参照してください。

15 リクエスト :¶

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のドキュメントを参照してください。

16 リクエスト :¶

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 は、タイムスタンプを切り捨ててグループ化できるデータに変換するための一連の日時関数を提供しています。

17 リクエスト :¶

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 は、タイムスタンプを切り捨ててグループ化できるデータに変換するための一連の日時関数を提供しています。

18 リクエスト :¶

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 は、さまざまな方法でデータをアグリゲーションするため、一連のアグリゲーション関数を提供しています。

19 リクエスト :¶

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 です。

データソースの設定¶

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

Name CrateDB
Host crate-db:5432
Database mtopeniot
User crate
SSL Mode disable

Save をクリックし、Database Connection OK メッセージがと表示されていることを確認します。

ダッシュボードの設定¶

新しいダッシュボードを表示するには、+ ボタンをクリックして Dashboard を選択するか、直接 http://localhost:3003/dashboard/new?orgId=1 にアクセスします。その後、Add Query をクリックします。

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

Queries to CrateDB (以前に作成したデータソースから選択)
FROM etlamp
Time column time_index
Metric column entity_id
Select value column:luminosity

次に、キーボードの ESC をクリックすると、作成したグラフを含むダッシュボードが表示されます。

Add Panel ボタンをクリックして Choose Visualisation を選択し、Map panel を選択します。

マップ・レイアウト・オプションで、次の値を設定します :

Center: custom
Latitude: 52.5031
Longitude: 13.4447
Initial Zoom: 12

左側の Queries タブをクリックして、次のように設定します :

Format as: Table
FROM etlamp
Time column time_index
Metric column entity_id
Select value
- column:luminosity alias:value
- column:location alias:geojson
- column:entity_type alias:type

左側の Visualisation タブをクリックして、次のように設定します :

Map Layers:
- Lamp:
  - Icon: lightbulb-o
  - ClusterType: average
  - ColorType: fix
  - Column for value: value
  - Maker color: red

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

時系列データの永続化とクエリ (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 個のサンプル値をリスト¶

10 リクエスト :¶

レスポンス :¶

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

11 リクエスト :¶

レスポンス :¶

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

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

12 リクエスト :¶

レスポンス :¶

13 リクエスト :¶

レスポンス :¶

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

14 リクエスト :¶

レスポンス :¶

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

15 リクエスト :¶

レスポンス :¶

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

16 リクエスト :¶

レスポンス :¶

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

17 リクエスト :¶

レスポンス :¶

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

18 リクエスト :¶

レスポンス :¶

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

19 リクエスト :¶

レスポンス :¶

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

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

ログイン¶

データソースの設定¶

ダッシュボードの設定¶

License¶

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

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