STH-Comet を使用してコンテキスト情報の履歴を生成する方法

FIWARE Context Broker によって格納されるコンテキスト情報には、エンティティ属性の最新の値のみが含まれます。属性値の履歴を登録できるようにするには、STH-Comet コンポーネントが必要です。STH-Comet では、MongoDB 上に構築された履歴データベースを使用して、"未加工の履歴および集計された時系列コンテキスト情報" を生成することができます。

したがって、使用される3つの主なコンポーネントは次のとおりです :

下の図では、ユーザが REST HTTP リクエストを発行できることがわかります。すべての操作は Orion Context Broker に送信され、処理されます。STH は Orion Context Broker にサブスクライブしているため、STH は Orion によって格納されたエンティティに加えられた変更を通知されます。その結果、STH は履歴データベースを生成することができます。

Architecture

このチュートリアルを進めるには、マシン上で docker と docker-compose を構成していることを確認する必要があります。あなたのオペレーティング・システムに基づき、docker と docker-compose のインストールのプロセスに従ってください。

あなたのマシン上で、 docker と docker-compose が動作することを確認した後、次の例のように、ディレクトリを作成して docker-compose.yml ファイルを作成する必要があります。

docker-compose.yml

上記の例では、さまざまなコンテナにさまざまなアプリケーションがありますが、それらのコンテナはすべて実際にリンクされています。これらのコンテナを1つずつ実行するのではく、ひとつのコマンドでこれらのコンテナを一度に実行したいため、docker compose を使用します。docker-compose は、ひとつのコマンド "docker-compose up" で、さまざまなコンテナに存在する複数のアプリケーションを実際に実行することができます。上記の例のように、3つのコンテナを定義することができます。* .ymlファイルの中に、Orion Context Broker を実行するコンテナ、MongoDB を実行するコンテナ、そして STH-Comet を実行するコンテナがあります。これは "docker-compose" ファイルと呼ばれます。

前の図では、STH コンポーネントではユーザが .conf ファイルまたは .js を使用してコンポーネントを構成できることに注意する必要がありますが、環境変数を設定すると、ファイルに設定されている他の構成よりも優先されます。ここでは、STH 環境変数の詳細について説明します。

例の実行

実行されるステップは次のとおりです :

  • dokcer-compose (* .yml) ファイルを実行します
  • Orion Context Broker(CB) にコンテキスト情報を公開します
  • STH に通知するサブスクリプションを作成します
  • さまざまな期間に値を更新します
  • 時系列データと集計データの取得します

ステップ・バイ・ステップ

すべての Docker コンテナを削除します (オプション)

docker rm `docker ps -aq`

すべての Docker イメージを削除します (オプション)

docker rmi $(docker images -a -q)

3つのコンポーネント (MongoDB, orion, STH) を一緒に実行するには、docker-compose.yml ファイルがあるフォルダを含むディレクトリに移動し、次の docker-compose コマンドを実行する必要があります :

docker-compose up

ローカルマシン上に構築されたイメージをチェックするには :

docker images

REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
fiware/orion        latest              d6ff87a7b412        6 days ago          266MB
mongo               3.4                 baea457313ee        3 weeks ago         360MB
fiware/sth-comet    latest              6915eeff95d3        4 months ago        294MB

現在実行中のコンテナをチェックするには :

docker ps

CONTAINER ID        IMAGE               COMMAND                  CREATED                  STATUS              PORTS                    NAMES
ccb6441ba878        fiware/orion        "/usr/bin/contextBro…"   Less than a second ago   Up 10 seconds       0.0.0.0:1026->1026/tcp   orion
c832cb36bdfc        fiware/sth-comet    "/bin/sh -c bin/sth"     Less than a second ago   Up 10 seconds       0.0.0.0:8666->8666/tcp   sth
44dea317f258        mongo:3.4           "docker-entrypoint.s…"   Less than a second ago   Up 11 seconds       27017/tcp                mongo

3つのコンテナが稼働していることがわかります。ここでは、 "docker-compose.yml" ファイルで指定されているようにOrion Context Broker コンテナがポート 1026 で、STH コンテナがポート 8666 で、MongoDB がポート 27017 で実 行されています。

REST API コールを実行するには、Web サービスを迅速にテストするのに役立つ多くの HTTP クライアントがあります。

この例では、Postman を使用して、CRUD(Create, Remove, Update, Delete) 操作を実行しています。

Orion Context Broker と STH が本当にうまく動作しているかどうかを確認するために、それぞれのバージョンをクエリし、レスポンスがあるかどうかを確認することでテストできます。

postman を開いたら、GET クエリを実行する必要があることを指定する必要があり、ターゲット (URI : port) を指定する必要があります。この場合、クエリ対象は次のようになります :

$ curl --request GET \ --url http://localhost:1026/version

{
    "orion": {
        "version": "1.12.0-next",
        "uptime": "4 d, 0 h, 3 m, 33 s",
        "git_hash": "61d067e1e82a3b59aa3971b129a97d9814259627",
        "compile_time": "Thu Mar 1 17:52:25 UTC 2018",
        "compiled_by": "root",
        "compiled_in": "0b718d526f33",
        "release_date": "Thu Mar 1 17:52:25 UTC 2018",
        "doc": "https://fiware-orion.readthedocs.org/en/master/"
    }
}
$ curl --request GET \ --url http://localhost:8666/version

{
    "version": "2.3.0-next"
}

次に、DB がアクセス可能かどうかを調べるために、MongoDB コンテナに接続し、mongo コマンドを実行して、mongo シェルにアクセスする必要があります。

$ docker exec -it mongo mongo


MongoDB shell version v3.4.13
connecting to: mongodb://127.0.0.1:27017
MongoDB server version: 3.4.13
Welcome to the MongoDB shell.
For interactive help, type "help".
For more comprehensive documentation, see
    http://docs.mongodb.org/
Questions? Try the support group
    http://groups.google.com/group/mongodb-user
Server has startup warnings: 
2018-03-08T11:50:52.662+0000 I STORAGE  [initandlisten] 
2018-03-08T11:50:52.662+0000 I STORAGE  [initandlisten] ** WARNING: Using the XFS filesystem is strongly recommended with the WiredTiger storage engine
2018-03-08T11:50:52.662+0000 I STORAGE  [initandlisten] **          See http://dochub.mongodb.org/core/prodnotes-filesystem
2018-03-08T11:50:52.764+0000 I CONTROL  [initandlisten]
2018-03-08T11:50:52.765+0000 I CONTROL  [initandlisten] ** WARNING: Access control is not enabled for the database.
2018-03-08T11:50:52.765+0000 I CONTROL  [initandlisten] **          Read and write access to data and configuration is unrestricted.
2018-03-08T11:50:52.765+0000 I CONTROL  [initandlisten]
>
> show dbs
admin  0.000GB
local  0.000GB
orion  0.000GB

エンティティの操作

エンティティは Context Broker によって格納されるオブジェクトです。各エンティティには1つ以上の属性があります。値が変更されたときに通知されるように、これらの属性の1つを読み取り、更新し、サブスクライブすることができます 。エンティティに対して実行できる操作は、Post, Get, Put, Delete です。

エンティティの作成

次のように、次のターゲットに対して POST リクエストを実行する必要があります :

localhost:1026/v2/entities

registered device

リクエストを送信するときに、いくつかのヘッダ値も指定する必要があります :

Headers to pass

Content-type には送信したいデータのタイプを指定します。常に application/json です。

Fiware-Service そして FiwareServicepath は、データを論理的に分離することを意図しています。これはマルチテナント・モデルと呼ばれ、この用語は、ソフトウェアの単一のインスタンスがサーバ上で実行され、複数のテナントを提供していたソフトウェア・アーキテクチャを指します。例えば、 Fiware-Service : Tenat1 です。また、サービスパスは、作成時にエンティティに割り当てられた階層スコープです。例えば、Fiware-ServicePath :

注 : この例で実行するすべての操作に対して、これらのヘッダを設定する必要があります。

複数のエンティティを追加

次のターゲットに対して POST リクエストを行う必要があります :

localhost:1026/v2/op/update

add multiple entities

登録されたすべてのエンティティをクエリ

作成されたすべてのエンティティをクエリするには、次のターゲットに対して GET 操作を実行する必要があります。クエリは以前に追加したすべてのエンティティを取得する必要があります。

localhost:1026/v2/entities

Select All entities

属性の操作

エンティティ属性は個別に扱うことができます。操作には、属性の取得 (get), 属性の変更(put), 属性値の取得(get)、特定の属性値の変更(put)、および属性の削除(delete)が含まれます。

属性の変更

このケースでは、Car1 エンティティの属性値を変更する必要があります。これは、先に渡したのと同じ3つのヘッダパラメータを使用して、次のターゲットに対してPUT リクエストを実行することによって実行できます

localhost:1026/v2/entities/Car1/attrs/speed/value

modify attribute's value

Orion に STH をサブスクライブ

コンテキスト・コンシューマは、サブスクライブ操作を使用して特定の条件を満たすコンテキスト情報を受信するためにサブスクライブすることができます。このようなサブスクリプションには有効期限があります。その代わりに、 Context Broker は、コンテキスト情報の更新を、それらをエクスポートする通知操作を呼び出すことによって、サブスクライブされたコンテキスト・コンシューマに通知します。

entities と notifications サブフィールドは、通知メッセージの内容を定義します。

  • idPattern は、取得したいエンティティをフィルタリングするために使用します。その値は正規表現です。この例では、すべてを取得するように設定しています
  • url は、通知を送信の送信先で、URL のサブフィールドで定義されています。ここでは、STH-Comet の URL を指定します
  • attrsFormat : STH は NGSI v1 の通知ペイロードしか理解しないため、これを レガシー(legacy)に設定します
  • サブスクリプションには、ISO 8601標準フォーマットを使用して指定された有効期限切れフィールドがあります。サブスクリプションがその日を超えれば、サブスクリプションは単に無視されます

localhost:1026/v2/subscriptions

Add Subscription

サブスクリプションを作成した後、STH API を使用していくつかの集約をクエリできるように、前と同じ方法で属性値を更新する必要があります。さまざまな時点で属性値を更新するために必要な変更を確認するには、属性値を何回か変更する方法を次の例に示します

updating multiple values

時系列値のクエリ

ここでは、変更された値の生データをすべて STH を介してクエリします。したがって、次のターゲットに対して GET 操作を実行する必要があります :

localhost:8666/STH/v1/contextEntities/type/Car/id/Car1/attributes/speed?lastN=20

STH Raw Data

レスポンスのペイロードでは、変更された属性の名前が speed であり、その後に異なる期間内に変更された値が続くことがわかります。たとえば、速度値 22 に対応するタイムスタンプは、2018-03-20T10:50:40.089Z であることがわかります。

分解能と集計

aggrMethod: 集約メソッド。STH コンポーネントは、数値属性値に対して、max (最大値), min (最小値), sum (すべてのサンプルの合計), sum2 (すべてのサンプルの2乗の合計) を、文字列型の属性値に対して occur をサポートします。

aggrPeriod: 集約期間または分解能。固定の分解能では、原点時刻形式とオフセットの可能性が決まります。必須パラメータです。分解能または集計期間は、集計された時系列情報がグループ化される期間です。STH でサポートされる有効な有効な分解能の値は、月、日、時、分、秒です。

注 : この例では、手動で属性の値を秒単位で変更しているため、集約時系列コンテキスト情報は分の分解能に設定されています。したがって、値が1時間ごとに変化している場合は、集計された期間パラメータを1日に設定して、基礎となる時間別の変更を確認することができます。

詳細は、STH-Comet のドキュメントを参照してください。

最大値を取得

ここでは、次のターゲットに対して GET 要求を実行します

localhost:8666/STH/v1/contextEntities/type/Car/id/Car1/attributes/speed?aggrMethod=max&aggrPeriod=minute&dateFrom=2018-03-20T00:00:00.000Z&dateTo=2018-03-20T23:59:59.999Z

max of the updated values

この例では、クエリを実行している分解能が_分単位_で表示されていることがわかります。したがって、属性の最大数をクエリするときは、1分ごとに最大値を持ちます。原点時刻は、2018-03-20T10:00:00.000Z であることがわかります。この例は、47分には2つのサンプルがあり、最大数は50です。48分では10サンプルあり、最大値は100です。

オカレンスの検索

ここでは、次のターゲットに対して GET 要求を実行します :

localhost:8666/STH/v1/contextEntities/type/Car/id/Car1/attributes/speed?aggrMethod=occur&aggrPeriod=minute&dateFrom=2018-03-20T00:00:00.000Z&dateTo=2018-03-20T23:59:59.999Z

occur aggregation

上記の図では、10:00 時と50 分の間に6つのサンプルが発生していることがわかります。

合計を取得

ここでは、次のターゲットに対して GET 要求を実行します :

localhost:8666/STH/v1/contextEntities/type/Car/id/Car1/attributes/speed?aggrMethod=sum&aggrPeriod=minute&dateFrom=2018-03-20T00:00:00.000Z&dateTo=2018-03-20T23:59:59.999Z

aggregated data - sum

これらの集計された方法によって提供された情報をサンプル数と組み合わせることによって、平均を計算することができます。平均値、分散、標準偏差などの確率的な値を計算することが可能です。必須パラメータです。たとえば、合計をサンプル数で割って平均を手動で計算できます。

MongoDB の履歴出力

MongoDB コンテナに接続し、Orion Context Broker に登録されているすべてのエンティティにアクセスできます。生成されたすべての履歴データも確認できます :

docker exec -it mongo mongo


> show dbs
admin          0.000GB
local          0.000GB
orion          0.000GB
orion-example  0.000GB
sth_example    0.000GB

> use orion-example
switched to db orion-example

> show collections
csubs
entities

> db.entities.count()
3

> use sth_example
switched to db sth_example

> show collections
sth_x002fxffffCar1xffffCarxffffspeed
sth_x002fxffffCar1xffffCarxffffspeed.aggr
sth_x002fxffffRoom1xffffRoomxffffpressure
sth_x002fxffffRoom1xffffRoomxffffpressure.aggr
sth_x002fxffffRoom1xffffRoomxfffftemperature
sth_x002fxffffRoom1xffffRoomxfffftemperature.aggr
sth_x002fxffffRoom2xffffRoomxffffpressure
sth_x002fxffffRoom2xffffRoomxffffpressure.aggr
sth_x002fxffffRoom2xffffRoomxfffftemperature
sth_x002fxffffRoom2xffffRoomxfffftemperature.aggr

> db.sth_x002fxffffCar1xffffCarxffffspeed.count()
6