FIWARE Banner NGSI v2

FIWARE Core Context Management License: MIT Support badge
Documentation

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

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

Run in Postman


時系列データの永続化とクエリ (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 BrokerIoT 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 バージョン 18.03 以降と Docker Compose 1.21 以上を使用していることを確認 し、必要に応じてアップグレードしてください。

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 は、ポート 8868 上の 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:
      - cratedb
    environment:
      - CRATE_HOST=cratedb

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-servicefiware-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-servicefiware-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-ServiceFiware-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/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以内にある最新の4つのサンプリングされたランプの luminosity 値を示しています。デバイス・モニタのページで利用可能なすべてのランプをつけると、 Lamp:001Lamp:004 のデータを見ることができるはずです。

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

19 リクエスト :

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 BYLIMIT を使用してデータをソートします。 詳細は、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 のドメイン内にはありませんが 、WirecloudKnowage などのマッシュアップやダッシュボード・コンポーネントに任せることができます。

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

基本的な処理は、検索と属性マッピングの 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

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


License

MIT © 2018-2020 FIWARE Foundation e.V.