このチュートリアルでは、MongoDB データベースから傾向データを取得するために使用される Generic Enabler である FIWARE STH-Comet について紹介します。チュートリアルでは、前のチュートリアルで接続した IoT センサをアクティブにし、それらのセンサからの測定値をデータベースに保存し、そのデータの時間ベースの集計を取得します。

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

時系列データのクエリ (MongoDB)¶

"The "moment" has no yesterday or tomorrow. It is not the result of thought and therefore has no time."

— Bruce Lee

FIWARE プラットフォーム内では、Orion Context Broker と Cygnus Generic Enabler の組み合わせを使用して、履歴コンテキスト・データを MongoDB のようなデータベースに保存できます。これにより、選択したデータベースに一連のデータ・ポイントが書き込まれます。各タイムスタンプ付きデータ・ポイントは、所与の瞬間におけるコンテキスト・エンティティの状態を表します。個々のデータ点はそれ自体では無意味であり、最大値、最小値および傾向などの意味のある統計値が観測されることができるのは、一連のデータ点を組み合わせたときだけです。

傾向データの作成と分析は、コンテキスト駆動型システムの一般的な要件です。したがって、FIWARE プラットフォームは、Mong-DB に永続化された時系列データの永続化と解釈の問題に特化した Generic Enabler (STH-Comet) を提供します。STH-Comet 自体は 2 つのモードで使用できます :

最小モードでは、STH-Cometは、リクエストされたときに、データの収集とデータの解釈の両方に責任があります
正規モードでは、データの収集が Cygnus に委任され、STH-Comet は、単に既存のデータベースから読み込みます

2 つの動作モードのうち、正規モードはより柔軟ですが、最小モードは設定が簡単です。両者の主な違いを以下の表に要約します。

	最小モード	正規モード
システムは適切にセットアップしやすいですか？	1 つの構成だけがサポートされています	高度な設定が可能です - 複雑な設定
どのコンポーネントがデータの永続性を担っていますか？	STH-Comet	Cygnus
STH-Comet の役割は何ですか？	データの読み書き	データ読み取り専用
Cygnus の役割は何ですか？	使用しません	データ書き込み専用
データはどこに集約されていますか？	STH-Comet にのみ接続された MongoDB データベース	Cygnus と STH-Comet の両方に接続された MongoDB データベース
他のデータベースを使用するようにシステムを構成できますか？	いいえ	はい
ソリューションは簡単に拡張できますか？	簡単に拡張できません - 単純なシステムで使用します	スケールアップが容易です - 複雑なシステムに使用できます
システムは高いスループットに対処できますか？	いいえ - スループットが低い場所で使用します	はい - スループットが高い場所で使用します

時系列データの解析¶

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

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

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

デバイス・モニタ¶

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

FIWARE Monitor

デバイス履歴¶

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

アーキテクチャ¶

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

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

4 つの 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 STH-Comet は以下を行います :
  - 時間ベースのデータ・クエリを解釈します
  - コンテキストの変更をサブスクライブして、MongoDB データベースに保存します (最小モードのみ)
- FIWARE Cygnus は、コンテキストの変更をサブスクライブして、MongoDB データベースに保存します (正規モードのみ)

注: : Cygnus は、STH-Comet が正規モードで設定されている場合にのみ使用されます。

MongoDB データベース :
- Orion Context Brokerが、データ・エンティティ、サブスクリプション、レジストレーションなどのコンテキスト・データ情報を保持するために使用します
- デバイスの URLs や Keys などのデバイス情報を保持するために IoT Agent によって使用されます
- 時間ベースの履歴コンテキスト・データを保持するデータ・シンクとして使用されます
  - 最小モード - これは STH-Comet によって読み取られ、追加されます
  - 正規モード - これは Cygnus によって追加され、STH-Comet によって読み取られます
3 つのコンテキストプロバイダ :
- 在庫管理フロントエンドは、このチュートリアルで使用していません。これは以下を行います :
  - 店舗情報を表示し、ユーザーがダミー IoT デバイスと対話できるようにします
  - 各店舗で購入できる商品を表示します
  - ユーザが製品を購入して在庫数を減らすことを許可します
- HTTP 上で動作する Ultralight 2.0 プロトコルを使用して、ダミー IoT デバイスのセットとして機能する Web サーバ
- このチュートリアルでは、コンテキスト・プロバイダの NGSI proxy は使用しません。これは以下を行います :
  - NGSI-v2 を使用してリクエストを受信します
  - 独自の API を独自のフォーマットで使用して、公開されているデータ・ソースへのリクエストを行います
  - NGSI-v2 形式でコンテキスト・データを Orion Context Broker に返します

要素間のすべての対話は 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.Short-Term-History.git
cd tutorials.Short-Term-History
git checkout NGSI-v2

./services create

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

./services <command>

ここで、<command> は、起動するモードによって異なります。このコマンドは、前のチュートリアルのシード・データをインポートし、起動時にダミー IoT センサをプロビジョニングします。

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

最小モード (STH-Comet のみ)¶

最小構成で、STH-Comet は、履歴コンテキスト・データを永続化するために使用され、また、時間ベースのクエリを作成するために使用されます。すべての操作は同じポート 8666 で行われます。標準 27017 ポートをリッスンする MongoDB インスタンスは、Orion Context Broker および IoT Agent に関連するデータを保持するだけでなく、履歴データを保持するためにも使用されます。全体的なアーキテクチャを以下に示します :

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

mongo-db:
    image: mongo:4.2
    hostname: mongo-db
    container_name: db-mongo
    ports:
        - "27017:27017"
    networks:
        - default

STH-Comet の設定¶

sth-comet:
    image: fiware/sth-comet
    hostname: sth-comet
    container_name: fiware-sth-comet
    depends_on:
        - mongo-db
    networks:
        - default
    ports:
        - "8666:8666"
    environment:
        - STH_HOST=0.0.0.0
        - STH_PORT=8666
        - DB_PREFIX=sth_
        - DB_URI=mongo-db:27017
        - LOGOPS_LEVEL=DEBUG

sth-comet コンテナは、1 つのポートで待機しています :

STH-Comet のポートの操作 - 8666 は、サービスが Orion Context Broker からの通知と、cUrl または Postman からの時間ベースのクエリのリクエストをリッスンするポートです

sth-comet コンテナは、次に示すように環境変数によって制御されます :

キー	値	説明
STH_HOST	`0.0.0.0`	STH-Comet がホストされているアドレス - このコンテナ内では、ローカルマシン上のすべての IPv4 アドレスを意味します
STH_PORT	`8666`	STH-Comet がリッスンするオペレーション・ポート。コンテキスト・データの変更をサブスクライブするときにも使用されます
DB_PREFIX	`sth_`	指定されていない場合は、各データベースのエンティティに追加されたプレフィックス
DB_URI	`mongo-db:27017`	STH-Comet が履歴コンテキスト・データを永続化するために接続する MongoDB サーバ
LOGOPS_LEVEL	`DEBUG`	STH-Comet のログレベル

最小モード - 起動¶

STH-Comet のみを使用して、最小構成でシステムを起動するには、次のコマンドを実行します :

./services sth-comet

STH-Comet - サービスの健全性のチェック¶

STH-Comet が実行されると、公開されている STH_PORT ポートへの HTTP リクエストを行うことで状態を確認できます。レスポンスがブランクの場合は、通常、STH-Comet が実行されていないか、別のポートでリッスンしているためです。

1 リクエスト :¶

curl -X GET \
  'http://localhost:8666/version'

レスポンス :¶

レスポンスは次のようになります :

{
    "version": "2.3.0-next"
}

トラブルシューティング : レスポンスがブランクの場合はどうなりますか？

Docker コンテナが動作していることを確認するには :
docker ps
いくつかのコンテナが走っているのを確認してください。sth-comet または cygnus が実行されていない場合は、必要に応じてコンテナを再起動できます。

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

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

最小モード - コンテキスト変更に対する STH-Comet のサブスクリプション¶

最小モードで動的コンテキスト・システムが起動して実行されると、STH-Comet はコンテキストの変更を通知する必要があります。したがって、これらの変更を STH-Comet に通知するために Orion Context Broker にサブスクリプションを設定する必要があります。サブスクリプションの詳細は、監視対象のデバイスとサンプリング・レートによって異なります。

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

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

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

fiware-service と fiware-servicepath ヘッダは、サブスクリプションをフィルタリングして、接続された IoT センサからの測定値のみをリッスンためにするために使用されます
リクエストのボディの idPattern は、STH-Comet にすべてのモーション・センサのデータの変更が通知されるようにします
通知 url は設定された STH_PORT と一致する必要があります
STH-Comet は、現在、古い NGSI v1 形式の通知のみを受け付けるため、attrsFormat=legacy が必要です

2 リクエスト :¶

curl -iX POST \
  'http://localhost:1026/v2/subscriptions/' \
  -H 'Content-Type: application/json' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /' \
  -d '{
  "description": "Notify STH-Comet of all Motion Sensor count changes",
  "subject": {
    "entities": [
      {
        "idPattern": "Motion.*"
      }
    ],
    "condition": {"attrs": ["count"] }
  },
  "notification": {
    "http": {
      "url": "http://sth-comet:8666/notify"
    },
    "attrs": [
      "count"
    ],
    "attrsFormat": "legacy"
  }
}'

STH-Comet - ランプの明度のサンプリング¶

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

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

fiware-service と fiware-servicepath ヘッダは、サブスクリプションをフィルタリングして、接続された IoT センサからの測定値のみをリッスンためにするために使用されます
リクエストのボディの idPattern は、STH-Comet にすべてのスマート・ランプのデータの変更が通知されるようにします
通知 url は設定された STH_PORT と一致する必要があります
STH-Comet は、現在、古い NGSI v1 形式の通知のみを受け付けるため、attrsFormat=legacy が必要です
throttling 値は、変更がサンプリングされる割合を定義します

注 : サブスクリプションの throttling が順次更新として期待どおりに行われないため、注意が必要です。たとえば、Ultra Light デバイスが測定値 t|20|l|1200 を送信すると、それは単一アトミックのコミットになり、両方の属性は STH-Comet への通知に含まれます。しかしながら、デバイスが t|20#l|1200 を送信している場合、これは 2 つのアトミック・コミットとして扱われます。t の最初の変更に対して通知が送られますが、エンティティがサンプリング期間内に最近更新されたので、lの第 2 の変更は無視されます。

3 リクエスト :¶

curl -iX POST \
  'http://localhost:1026/v2/subscriptions/' \
  -H 'Content-Type: application/json' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /' \
  -d '{
  "description": "Notify Cygnus to sample Lamp luminosity every five seconds",
  "subject": {
    "entities": [
      {
        "idPattern": "Lamp.*"
      }
    ],
    "condition": {
      "attrs": [
        "luminosity"
      ]
    }
  },
  "notification": {
    "http": {
      "url": "http://sth-comet:8666/notify"
    },
    "attrs": [
      "luminosity"
    ]
  },
  "throttling": 5
}'

時系列データのクエリ¶

このセクションのクエリは、最小モードまたは正規モードのいずれかを使用して、STH-Comet をすでに接続しており、いくつかのデータを収集していることを前提としています。

前提条件¶

STH-Comet は、十分なデータ・ポイントが既にシステム内に集約されている場合にのみ、時系列データを取り出すことができます。スマート・ドアがロック解除されていて、スマート・ランプがオンになっており、サブスクリプションが登録されていることを確認してください。データは、チュートリアルの前に少なくとも 1 分間は収集する必要があります。

サブスクリプションが存在することを確認¶

fiware-service および fiware-servicepath ヘッダはクエリに設定し、サブスクリプションを設定するときに使用する値と一致する必要があることに注意してください。

4 リクエスト :¶

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

レスポンス :¶

[
    {
        "id": "5b39e3c11615e2e55a8df103",
        "description": "Notify STH-Comet of all Motion Sensor count changes",
        "status": "active",
        "subject": { ...ETC },
        "notification": {
            "timesSent": 6,
            "lastNotification": "2018-07-02T08:36:04.00Z",
            "attrs": ["count"],
            "attrsFormat": "legacy",
            "http": { "url": "http://sth-comet:8666/notify" },
            "lastSuccess": "2018-07-02T08:36:04.00Z"
        }
    },
    {
        "id": "5b39e3c31615e2e55a8df104",
        "description": "Notify STH-Comet to sample Lamp changes every five seconds",
        "status": "active",
        "subject": { ...ETC },
        "notification": {
            "timesSent": 4,
            "lastNotification": "2018-07-02T08:36:00.00Z",
            "attrs": ["luminosity"],
            "attrsFormat": "legacy",
            "http": { "url": "http://sth-comet:8666/notify" },
            "lastSuccess": "2018-07-02T08:36:01.00Z"
        },
        "throttling": 5
    }
]

結果は空であってはいけません。レスポンスの notification セクション内には、各サブスクリプションの健全性を表すいくつかの追加の attributes があります。

サブスクリプションの基準が満たされている場合、timesSent は 0 より大きくなければなりません。ゼロの値は、サブスクリプションの サブジェクトが間違っているか、サブスクリプションが間違った fiware-service-path または fiware-service ヘッダで作成されたことを示します。

lastNotification は最近のタイム・スタンプでなければなりません。そうでなければ、デバイスは定期的にデータを送信していません。 スマート・ドアのロックを解除し、スマート・ランプをオンにすることを忘れないでください

lastSuccess は lastNotification の日付と一致する必要があります。そうでない場合は、Cygnus または STH Comet はサブスクリプションを正しく受信していません。ホスト名とポートが正しいことを確認してください。

最後に、サブスクリプションの status が active であることを確認します。期限切れのサブスクリプションは起動しません。

オフセット，制限，ページネーション¶

最初の N 個のサンプリング値をリスト¶

この例は、Lamp:001 から最初に 3 つのサンプリングされた luminosity 値を示しています。

コンテキスト・エンティティ属性の短期履歴を取得するには、GET リクエストを送信します : ../STH/v1/contextEntities/type/<Entity>/id/<entity-id>/attributes/<attribute>

hLimit パラメータは、N 値に結果を制限します。hOffset=0 は、最初の値から開始します。

5 リクエスト :¶

curl -X GET \
  'http://localhost:8666/STH/v1/contextEntities/type/Lamp/id/Lamp:001/attributes/luminosity?hLimit=3&hOffset=0' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /'

レスポンス :¶

{
    "contextResponses": [
        {
            "contextElement": {
                "attributes": [
                    {
                        "name": "luminosity",
                        "values": [
                            {
                                "recvTime": "2018-06-21T12:20:19.841Z",
                                "attrType": "Integer",
                                "attrValue": "1972"
                            },
                            {
                                "recvTime": "2018-06-21T12:20:20.819Z",
                                "attrType": "Integer",
                                "attrValue": "1982"
                            },
                            {
                                "recvTime": "2018-06-21T12:20:29.923Z",
                                "attrType": "Integer",
                                "attrValue": "1937"
                            }
                        ]
                    }
                ],
                "id": "Lamp:001",
                "isPattern": false,
                "type": "Lamp"
            },
            "statusCode": {
                "code": "200",
                "reasonPhrase": "OK"
            }
        }
    ]
}

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

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

コンテキスト・エンティティ属性の短期履歴を取得するには、GET リクエストを送信します : ../STH/v1/contextEntities/type/<Entity>/id/<entity-id>/attributes/<attribute>

hLimit パラメータは、N 値に結果を制限します。hOffset は、ゼロ以外の値に設定すると N 番目の測定から開始します。

6 リクエスト :¶

curl -X GET \
  'http://localhost:8666/STH/v1/contextEntities/type/Motion/id/Motion:001/attributes/count?hLimit=3&hOffset=3' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /'

レスポンス :¶

{
    "contextResponses": [
        {
            "contextElement": {
                "attributes": [
                    {
                        "name": "count",
                        "values": [
                            {
                                "recvTime": "2018-06-21T12:37:00.358Z",
                                "attrType": "Integer",
                                "attrValue": "1"
                            },
                            {
                                "recvTime": "2018-06-21T12:37:01.368Z",
                                "attrType": "Integer",
                                "attrValue": "0"
                            },
                            {
                                "recvTime": "2018-06-21T12:37:07.461Z",
                                "attrType": "Integer",
                                "attrValue": "1"
                            }
                        ]
                    }
                ],
                "id": "Motion:001",
                "isPattern": false,
                "type": "Motion"
            },
            "statusCode": {
                "code": "200",
                "reasonPhrase": "OK"
            }
        }
    ]
}

期間クエリ¶

一定期間にわたる値の合計をリスト¶

この例では、1 分ごとにMotion:001から合計 count 値を示しています。

コンテキスト・エンティティ属性の短期履歴を取得するに、GET リクエストを送信します : ../STH/v1/contextEntities/type/<Entity>/id/<entity-id>/attributes/<attribute>

aggrMethod パラメータは、時系列上に実行する集計のタイプを決定します。aggrPeriod は、second, minute, hour または day のいずれかです。

常にデータ収集の頻度に基づいて最も適切な期間を選択してください。 Motion:001 は、1 分ごとに数回変化しているので、minute が選択されます。

8 リクエスト :¶

curl -X GET \
  'http://localhost:8666/STH/v1/contextEntities/type/Motion/id/Motion:001/attributes/count?aggrMethod=sum&aggrPeriod=minute' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /'

レスポンス :¶

{
    "contextResponses": [
        {
            "contextElement": {
                "attributes": [
                    {
                        "name": "count",
                        "values": [
                            {
                                "_id": {
                                    "attrName": "count",
                                    "origin": "2018-06-21T12:00:00.000Z",
                                    "resolution": "minute"
                                },
                                "points": [
                                    {
                                        "offset": 37,
                                        "samples": 3,
                                        "sum": 1
                                    },
                                    {
                                        "offset": 38,
                                        "samples": 12,
                                        "sum": 6
                                    },
                                    {
                                        "offset": 39,
                                        "samples": 7,
                                        "sum": 4
                                    },
                                    ...etc
                                ]
                            }
                        ]
                    }
                ],
                "id": "Motion:001",
                "isPattern": false,
                "type": "Motion"
            },
            "statusCode": {
                "code": "200",
                "reasonPhrase": "OK"
            }
        }
    ]
}

期間内の平均値のクエリは直接サポートされていません。

この例では、1 分ごとの Lamp:001 からの luminosity 値の合計を示します。期間内のサンプル数と組み合わせると、データから平均を計算することができます。

コンテキスト・エンティティ属性の短期履歴を取得するには、GET リクエストを送信します : ../STH/v1/contextEntities/type/<Entity>/id/<entity-id>/attributes/<attribute>

aggrMethod パラメータは、時系列上に実行する集計のタイプを決定します。aggrPeriod は、second, minute, hour または day のいずれかです。

9 リクエスト :¶

curl -X GET \
  'http://localhost:8666/STH/v1/contextEntities/type/Lamp/id/Lamp:001/attributes/luminosity?aggrMethod=sum&aggrPeriod=minute' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /'

レスポンス :¶

{
    "contextResponses": [
        {
            "contextElement": {
                "attributes": [
                    {
                        "name": "luminosity",
                        "values": [
                            {
                                "_id": {
                                    "attrName": "luminosity",
                                    "origin": "2018-06-21T12:00:00.000Z",
                                    "resolution": "minute"
                                },
                                "points": [
                                    {
                                        "offset": 20,
                                        "samples": 9,
                                        "sum": 17382
                                    },
                                    {
                                        "offset": 21,
                                        "samples": 8,
                                        "sum": 15655
                                    },
                                    {
                                        "offset": 22,
                                        "samples": 5,
                                        "sum": 9630
                                    },
                                    ...etc
                                ]
                            }
                        ]
                    }
                ],
                "id": "Lamp:001",
                "isPattern": false,
                "type": "Lamp"
            },
            "statusCode": {
                "code": "200",
                "reasonPhrase": "OK"
            }
        }
    ]
}

一定期間にわたる値の最小値をリスト¶

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

コンテキスト・エンティティ属性の短期履歴を取得するには、GET リクエストを送信します : ../STH/v1/contextEntities/type/<Entity>/id/<entity-id>/attributes/<attribute>

aggrMethod パラメータは、時系列上に実行する集計のタイプを決定します。aggrPeriod は、second, minute, hour または day のいずれかです。

スマート・ランプの光度は絶えず変化しているため、最小値を追跡することは理にかなっています。モーション・センサは、バイナリ値のみを提供するため、これには適していません。

10 リクエスト :¶

curl -X GET \
  'http://localhost:8666/STH/v1/contextEntities/type/Lamp/id/Lamp:001/attributes/luminosity?aggrMethod=min&aggrPeriod=minute' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /'

レスポンス :¶

{
    "contextResponses": [
        {
            "contextElement": {
                "attributes": [
                    {
                        "name": "luminosity",
                        "values": [
                            {
                                "_id": {
                                    "attrName": "luminosity",
                                    "origin": "2018-06-21T12:00:00.000Z",
                                    "resolution": "minute"
                                },
                                "points": [
                                    {
                                        "offset": 20,
                                        "samples": 9,
                                        "min": 1793
                                    },
                                    {
                                        "offset": 21,
                                        "samples": 8,
                                        "min": 1819
                                    },
                                    {
                                        "offset": 22,
                                        "samples": 5,
                                        "min": 1855
                                    },
                                    ...etc
                                ]
                            }
                        ]
                    }
                ],
                "id": "Lamp:001",
                "isPattern": false,
                "type": "Lamp"
            },
            "statusCode": {
                "code": "200",
                "reasonPhrase": "OK"
            }
        }
    ]
}

一定期間にわたる値の最大値をリスト¶

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

コンテキスト・エンティティ属性の短期履歴を取得するには、GET リクエストを送信します : ../STH/v1/contextEntities/type/<Entity>/id/<entity-id>/attributes/<attribute>

aggrMethod パラメータは、時系列上に実行する集計のタイプを決定します。aggrPeriod は、second, minute, hour または day のいずれかです。

11 リクエスト :¶

curl -X GET \
  'http://localhost:8666/STH/v1/contextEntities/type/Lamp/id/Lamp:001/attributes/luminosity?aggrMethod=max&aggrPeriod=minute' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /'

レスポンス :¶

{
    "contextResponses": [
        {
            "contextElement": {
                "attributes": [
                    {
                        "name": "luminosity",
                        "values": [
                            {
                                "_id": {
                                    "attrName": "luminosity",
                                    "origin": "2018-06-21T12:00:00.000Z",
                                    "resolution": "minute"
                                },
                                "points": [
                                    {
                                        "offset": 20,
                                        "samples": 9,
                                        "max": 2005
                                    },
                                    {
                                        "offset": 21,
                                        "samples": 8,
                                        "max": 2006
                                    },
                                    {
                                        "offset": 22,
                                        "samples": 5,
                                        "max": 1988
                                    },
                                    ...etc
                                ]
                            }
                        ]
                    }
                ],
                "id": "Lamp:001",
                "isPattern": false,
                "type": "Lamp"
            },
            "statusCode": {
                "code": "200",
                "reasonPhrase": "OK"
            }
        }
    ]
}

正規モード (Cygnus + STH-Comet)¶

正規構成は Cygnus を使用して、前のチュートリアルで示したのと同じ方法で、履歴コンテキスト・データを MongoDB データベースに保存します。既存の MongoDB インスタンス(標準 27017 ポートでリスニング) は、Orion Context Broker，IoT Agent、および Cygnus によって永続化された履歴コンテキスト・データに関連するデータを保持するために使用されます。STH-Comet も同じデータベースに接続されており、そこからデータを読み込みます。全体的なアーキテクチャを以下に示します :

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

mongo-db:
    image: mongo:4.2
    hostname: mongo-db
    container_name: db-mongo
    ports:
        - "27017:27017"
    networks:
        - default

STH-Comet の設定¶

sth-comet:
    image: fiware/sth-comet
    hostname: sth-comet
    container_name: fiware-sth-comet
    depends_on:
        - mongo-db
    networks:
        - default
    ports:
        - "8666:8666"
    environment:
        - STH_HOST=0.0.0.0
        - STH_PORT=8666
        - DB_PREFIX=sth_
        - DB_URI=mongo-db:27017
        - LOGOPS_LEVEL=DEBUG

Cygnus の設定¶

cygnus:
    image: fiware/cygnus-ngsi:latest
    hostname: cygnus
    container_name: fiware-cygnus
    depends_on:
        - mongo-db
    networks:
        - default
    expose:
        - "5080"
    ports:
        - "5050:5050"
        - "5080:5080"
    environment:
        - "CYGNUS_MONGO_HOSTS=mongo-db:27017"
        - "CYGNUS_LOG_LEVEL=DEBUG"
        - "CYGNUS_SERVICE_PORT=5050"
        - "CYGNUS_API_PORT=5080"

sth-comet コンテナは、1 つのポートで待機しています :

STH-Comet のポートの操作 - 8666 は、サービスが cUrl または Postman からの時間ベースのクエリ・リクエストをリッスンするポートです

sth-comet コンテナは、次に示すように、環境変数によって制御されます :

キー	値	説明
STH_HOST	`0.0.0.0`	STH-Comet がホストされているアドレス - このコンテナ内では、ローカルマシン上のすべての IPv4 アドレスを意味します
STH_PORT	`8666`	STH-Comet がリッスンするオペレーション・ポート
DB_PREFIX	`sth_`	指定されていない場合は、各データベースのエンティティに追加されたプレフィックス
DB_URI	`mongo-db:27017`	STH-Comet が履歴コンテキスト・データを永続化するために接続する MongoDB サーバ
LOGOPS_LEVEL	`DEBUG`	STH-Comet のログレベル

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

Cygnus のサブスクリプション・ポート - 5050 は、サービスが Orion Context Broker からの通知をリッスンするポートです
Cygnus の管理ポート - 5080 はチュートリアルのアクセスのためだけに公開されているため、cUrl または Postman は同じネットワークの一部ではなくプロビジョニング・コマンドを実行できます

cygnus コンテナは、次に示すように、環境変数によって制御されます :

キー	値	説明
CYGNUS_MONGO_HOSTS	`mongo-db:27017`	Cygnus が履歴コンテキスト・データを永続化するために接続する MongoDB サーバのカンマ区切りリスト
CYGNUS_LOG_LEVEL	`DEBUG`	Cygnus のログレベル
CYGNUS_SERVICE_PORT	`5050`	コンテキスト・データが変更されたときに Cygnus がリッスンする通知ポート
CYGNUS_API_PORT	`5080`	Cygnus が操作上の理由でリッスンするポート

正規モード - 起動¶

Cygnus と STH-Comet を使用して正規構成を使用してシステムを起動するには、次のコマンドを実行します :

./services cygnus

STH-Comet - サービスの健全性のチェック¶

STH-Comet が実行されると、公開された STH_PORT ポートへの HTTP リクエストを行うことで、状態を確認できます。レスポンスがブランクの場合は、通常、STH-Comet が実行されていないか、別のポートでリッスンしているためです。

12 リクエスト :¶

curl -X GET \
  'http://localhost:8666/version'

レスポンス :¶

レスポンスは次のようになります :

{
    "version": "2.3.0-next"
}

Cygnus - サービスの健全性のチェック¶

Cygnus が実行されると、公開された CYGNUS_API_PORT ポートへの HTTP リクエストを行うことで、状況を確認できます。レスポンスがブランクの場合、これは通常、Cygnus が実行されていないか、別のポートでリッスンしているためです。

13 リクエスト :¶

curl -X GET \
  'http://localhost:5080/v1/version'

レスポンス :¶

The response will look similar to the following:

{
    "success": "true",
    "version": "1.8.0_SNAPSHOT.ed50706880829e97fd4cf926df434f1ef4fac147"
}

トラブルシューティング : いずれかのレスポンスがブランクの場合はどうなりますか？

Docker コンテナが動作していることを確認するには :
docker ps
いくつかのコンテナが走っているのを確認してください。sth-comet または cygnus が実行されていない場合は、必要に応じてコンテナを再起動できます。

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

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

正規モード - コンテキスト変更に対する Cygnus のサブスクリプション¶

正規モードでは、Cygnus は、履歴コンテキスト・データの永続性のために責任があります。動的コンテキスト・システムが起動したら、Orion Context Broker にサブスクリプションを設定して、Cygnus にコンテキストの変更を通知する必要があります。STH-Comet は永続データの読み取りにのみ使用されます。

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

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

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

fiware-service および fiware-servicepath ヘッダは、サブスクリプションをフィルタリングして、接続されている IoT センサからの測定値だけをリッスンするために使用されます
リクエストのボディの idPattern は、すべてのモーション・センサのデータ変更を Cygnus に通知します
通知 url は設定された CYGNUS_API_PORT と一致する必要があります
Cygnus は、現在、古い NGSI v1 形式の通知のみを受け付けるため、attrsFormat=legacy が必要です

14 リクエスト :¶

curl -iX POST \
  'http://localhost:1026/v2/subscriptions/' \
  -H 'Content-Type: application/json' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /' \
  -d '{
  "description": "Notify Cygnus of all Motion Sensor count changes",
  "subject": {
    "entities": [
      {
        "idPattern": "Motion.*"
      }
    ],
    "condition": {
      "attrs": [
        "count"
      ]
    }
  },
  "notification": {
    "http": {
      "url": "http://cygnus:5051/notify"
    },
    "attrs": [
      "count"
    ]
  }
}'

Cygnus - ランプの明度のサンプリング¶

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

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

fiware-service および fiware-servicepath ヘッダは、サブスクリプションをフィルタリングして、接続された IoT センサからの測定値のみをリッスンするために使用されます
リクエストのボディの idPattern は、すべてのスマート・ランプのデータ変更のみを Cygnus に通知します
通知 url は設定された CYGNUS_API_PORT と一致する必要があります
Cygnus は、現在、古い NGSI v1 形式の通知のみを受け付けるため、attrsFormat=legacy が必要です
throttling 値は、変更がサンプリングされる割合を定義します

15 リクエスト :¶

curl -iX POST \
  'http://localhost:1026/v2/subscriptions/' \
  -H 'Content-Type: application/json' \
  -H 'fiware-service: openiot' \
  -H 'fiware-servicepath: /' \
  -d '{
  "description": "Notify Cygnus to sample Lamp luminosity every five seconds",
  "subject": {
    "entities": [
      {
        "idPattern": "Lamp.*"
      }
    ],
    "condition": {
      "attrs": [
        "luminosity"
      ]
    }
  },
  "notification": {
    "http": {
      "url": "http://cygnus:5051/notify"
    },
    "attrs": [
      "luminosity"
    ]
  },
  "throttling": 5
}'

正規モード - 時系列データのクエリ¶

データベースからデータを読み込む場合、最小と正規のモードに違いはありません。このチュートリアルの前のセクションを参照して、STH-Comet から時系列データをリクエストしてください

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

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

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

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

function readCometLampLuminosity(id, aggMethod) {
    return new Promise(function (resolve, reject) {
        const url = "http://sth-comet:8666/STH/v1/contextEntities/type/Lamp/id/Lamp:001/attributes/luminosity";
        const options = {
            method: "GET",
            url: url,
            qs: { aggrMethod: aggMethod, aggrPeriod: "minute" },
            headers: {
                "fiware-servicepath": "/",
                "fiware-service": "openiot"
            }
        };

        request(options, (error, response, body) => {
            return error ? reject(error) : resolve(JSON.parse(body));
        });
    });
}

function cometToTimeSeries(cometResponse, aggMethod) {
    const data = [];
    const labels = [];

    const values = cometResponse.contextResponses[0].contextElement.attributes[0].values[0];
    let date = moment(values._id.origin);

    _.forEach(values.points, (element) => {
        data.push({ t: date.valueOf(), y: element[aggMethod] });
        labels.push(date.format("HH:mm"));
        date = date.clone().add(1, "m");
    });

    return {
        labels,
        data
    };
}

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

時系列データのクエリ (MongoDB)¶

時系列データの解析¶

デバイス・モニタ¶

デバイス履歴¶

アーキテクチャ¶

前提条件¶

Docker と Docker Compose¶

Cygwin for Windows¶

起動¶

最小モード (STH-Comet のみ)¶

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

STH-Comet の設定¶

最小モード - 起動¶

STH-Comet - サービスの健全性のチェック¶

1 リクエスト :¶

レスポンス :¶

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

最小モード - コンテキスト変更に対する STH-Comet のサブスクリプション¶

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

2 リクエスト :¶

STH-Comet - ランプの明度のサンプリング¶

3 リクエスト :¶

時系列データのクエリ¶

前提条件¶

サブスクリプションが存在することを確認¶

4 リクエスト :¶

レスポンス :¶

オフセット，制限，ページネーション¶

最初の N 個のサンプリング値をリスト¶

5 リクエスト :¶

レスポンス :¶

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

6 リクエスト :¶

レスポンス :¶

最新の N 個のサンプリング値をリスト¶

7 リクエスト :¶

レスポンス :¶

期間クエリ¶

一定期間にわたる値の合計をリスト¶

8 リクエスト :¶

レスポンス :¶

9 リクエスト :¶

レスポンス :¶

一定期間にわたる値の最小値をリスト¶

10 リクエスト :¶

レスポンス :¶

一定期間にわたる値の最大値をリスト¶

11 リクエスト :¶

レスポンス :¶

正規モード (Cygnus + STH-Comet)¶

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

STH-Comet の設定¶

Cygnus の設定¶

正規モード - 起動¶

STH-Comet - サービスの健全性のチェック¶

12 リクエスト :¶

レスポンス :¶

Cygnus - サービスの健全性のチェック¶

13 リクエスト :¶

レスポンス :¶

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

正規モード - コンテキスト変更に対する Cygnus のサブスクリプション¶

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

14 リクエスト :¶

Cygnus - ランプの明度のサンプリング¶

15 リクエスト :¶

正規モード - 時系列データのクエリ¶

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

License¶