NGSIToMongo

コンテンツ :

機能性

NGSIToMongo は、MongoDB サーバー内で NGSI ライクのコンテキスト・データの イベントを永続化するように設計されたプロセッサです。 通常、このようなコンテキスト・データは Orion Context Broker インスタンスによって通知されますが、NGSI 言語を話す他のシステム でもかまいません。

データ・ジェネレータとは無関係に、NGSI コンテキスト・データは常に Draco のソースで内部オブジェクト NGSIEvent に変換されます。 最後に、これらのイベント内の情報は Draco シンクで特定の HDFS データ構造にマッピングされなければなりません。

次のセクションではこれについて詳しく説明します。

トップ

NGSI イベントを NGSIEvent オブジェクトにマッピング

コンテキスト・データを含む、通知された NGSI イベントは、NGSI データ・ジェネレータやそれが永続化される最後のバックエンドとは無関係に、NGSIEvent (各コンテキスト要素に対して、NGSIEvent が作成されます。そのような イベントは特定のヘッダと ContextElement オブジェクトの組み合わせです) オブジェクトに変換されます。

これは NGSIRestHandler により、Draco-ngsi Http リスナー (Flume の専門用語集のソース) で行われています。変換されると、 データは (NGSIEvent オブジェクトとして) 将来の使用のために 内部チャネルに入れられます (次のセクションを参照してください。

トップ

NGSIEvent を MongoDB データ構造へのマッピング

MongoDB は、Json ドキュメントのコレクションを含むデータベースにデータを 整理します。このような組織 (organization) は、NGSIEvent が持続化されるたびに NGSIToMongo によって活用されます。

トップ

MongoDB データベースの命名規則

イベント内のヘッダ値 fiware-service の名前でデータベースが作成されます (まだ存在していない場合)。設定されたプレフィックスが追加されます (デフォルトsth_)。

MongoDB はデータベース名に /, \, ., ", $ を使用することができません。 これは enable_encoding 設定パラメータによっては特定の エンコーディング が適用されることを意味します。

MongoDB の名前空間 (データベース+コレクション) の名前の長さ は113バイトに制限されています。

トップ

MongoDB コレクションの命名規則

これらのコレクションの名前は、構成されているデータ・モデルと分析モードに よって異なります (詳細については、設定 のセクションを参照してください) :

  • サービス・パスによるデータ・モデル (data_model=dm-by-service-path)。 データ・モデル名が示すように、通知された FIWARE サービス・パス、 またはNGSIRestHandler にデフォルトとして 設定されているものがコレクションの名前として使用されます。これにより、 同じサービス・パスに属するすべての NGSI エンティティに関するデータを この一意のテーブルに格納できます。設定されたプレフィックスは、 コレクション名の先頭に追加されます。
  • エンティティ (data_model=dm-by-entity) によるデータ・モデル。 各エンティティについて、通知された/デフォルトのFIWARE サービス・パスは、 コレクション名を作成するために通知されたエンティティの ID とタイプに 連結されます。FIWARE サービス・パスがルート・パス (/) の場合、 エンティティ ID とタイプのみが連結されます。設定されたプレフィックスは、 コレクション名の先頭に追加されます。
  • 属性 (data_model=dm-by-attribute) によるデータ・モデル。 各エンティティの 属性について、通知された/デフォルトの FIWARE　サービス・パスは、 コレクション名を構成するために、通知されたエンティティの ID とタイプ、 および通知された属性名に連結されます。FIWARE サービス・パスがルート・パス (/) の場合は、エンティティ ID とタイプ、および属性名とタイプのみが 連結されます。設定されたプレフィックスは、コレクション名の先頭に追加されます。

MongoDB は コレクション名 に $ を設定できなので、アンダースコア _ に置き換えられます。これにより、設定パラメータ enable_encoding に応じて 特定のエンコード が適用されます。

MongoDB の名前空間 (データベース+コレクション) の名前の長さ は113バイトに制限されています。

次の表は、テーブル名の構成をまとめたものです (デフォルトの sth_ プレフィックス、古いエンコーディングを想定) :

FIWARE service path dm-by-service-path dm-by-entity dm-by-attribute
/ sth_/ sth_/<entityId>_<entityType> sth_/<entityId>_<entityType>_<attrName>
/<svcPath> sth_/<svcPath> sth_/<svcPath>_<entityId>_<entityType> sth_/<svcPath>_<entityId>_<entityType>_<attrName>

新しいエンコーディングを使用 :

FIWARE service path dm-by-service-path dm-by-entity dm-by-attribute
/ sth_x002f sth_x002fxffff<entityId>xffff<entityType> sth_x002fxffff<entityId>xffff<entityType>xffff<attrName>
/<svcPath> sth_x002f<svcPath> sth_x002f<svcPath>xffff<entityId>xffff<entityType> sth_x002f<svcPath>xffff<entityId>xffff<entityType>xffff<attrName>

エンティティ ID とタイプの連結が既に ヘッダ値 notified_entities/grouped_entities に指定されていることを確認してください (グループ化ルールの使用の有無に応じて、詳細については、NGSIEvent の 設定のセクションを参照してくだい)。

トップ

Row-like の格納

上記のコレクション内に格納されている特定のデータに関して、attr_persistence パラメータが row (デフォルトの格納モード) に 設定されている場合、通知されたデータは属性ごとに格納され、 それぞれに対して Json ドキュメントを構成します。各ドキュメントには、 設定された data_model に応じて可変数のフィールドを含みます。

  • サービス・パス別データモデル
    • recvTimeTs: UTC タイムスタンプ (ミリ秒)
    • recvTime: 人が読める形式の UTC タイムスタンプ (ISO 8601)
    • entityId: 通知されたエンティティ識別子
    • entityType: 通知されたエンティティ・タイプ
    • attrName: 通知された属性名
    • attrType: 通知された属性タイプ
    • attrValue: 最も単純な形式では、この値は単なる文字列ですが、 Orion 0.11.0 以降では Json　オブジェクトまたは Json 配列になります
    • attrMetadata: 設定されている場合にのみ保存されます (設定ファイル ngsi_agent.conf で attr_metadata_store が true に設定されている場合)。 Json オブジェクトです。
  • エンティティ別データモデル :
    • recvTimeTs: UTC タイムスタンプ (ミリ秒)
    • recvTime: 人が読める形式の UTC タイムスタンプ (ISO 8601)
    • attrName: 通知された属性名
    • attrType: 通知された属性タイプ
    • attrValue: 最も単純な形式では、この値は単なる文字列ですが、 Orion 0.11.0 以降では Json オブジェクトまたは Json 配列になります
    • attrMetadata: 設定されている場合のみ保存されます (設定ファイル ngsi_agent.conf で attr_metadata_store が true に設定されている場合)。 Json オブジェクトです。
  • 属性別データモデル :
    • recvTimeTs: UTC タイムスタンプ (ミリ秒)
    • recvTime: 人が読める形式の UTC タイムスタンプ (ISO 8601)
    • attrType: 通知された属性タイプ
    • attrValue: 最も単純な形式では、この値は単なる文字列ですが、 Orion 0.11.0 以降では Json オブジェクトまたは Json 配列になります
    • attrMetadata: 設定されている場合のみ保存されます (設定ファイル ngsi_agent.conf で attr_metadata_store が true に設定されている場合)。 Json オブジェクトです。

トップ

Column-like の格納

上記のコレクション内に格納されている特定のデータに関して、attr_persistence パラメータが column に設定されていると、通知されたエンティティ全体に対して 単一の Json ドキュメントが作成されます。各ドキュメントには、data_model の設定に応じて可変数のフィールドが含まれます。

  • サービス・パス別データモデル :
    • recvTime: 人が読める形式のタイムスタンプ (ISO 8601 に似ていますが、 すべての MySQL タイムスタンプは UTC 形式であると想定されているため、 UTCを表す文字 Z は使用しません)
    • fiwareServicePath: 通知されたものまたはデフォルトのもの
    • entityId: 通知されたエンティティ識別子
    • entityType: 通知されたエンティティ・タイプ
    • 通知された属性ごとに、属性として指定されたフィールドが考慮されます。 このフィールドは時間とともに属性値を格納します
    • 通知された属性ごとに、属性名と _md　の連結として名付けられた フィールドが考慮されます。このフィールドは時間とともに属性の メタデータ値を格納します
  • エンティティ別データモデル :
    • recvTime: 人が読める形式のタイムスタンプ (ISO 8601 に似ていますが、 すべての MySQL タイムスタンプは UTC 形式であると想定されているため、 UTCを表す文字 Z は使用しません)
    • fiwareServicePath: 通知されたものまたはデフォルトのもの
    • 通知された属性ごとに、属性として指定されたフィールドが考慮されます。 このフィールドは時間とともに属性値を格納します
    • 通知された属性ごとに、属性名と _md　の連結として名付けられた フィールドが考慮されます。このフィールドは時間とともに属性の メタデータ値を格納します
  • 属性別データモデル。この組み合わせは意味がありませんので、避けてください

トップ

例

NGSIEvent

以下の NGSIEvent が通知された NGSI コンテキスト・データから作成されると 仮定します。以下のコードはオブジェクト表現であり、 実際のデータ・フォーマットではありません。

    ngsi-event={
        headers={
             content-type=application/json,
             timestamp=1429535775,
             transactionId=1429535775-308-0000000000,
             correlationId=1429535775-308-0000000000,
             fiware-service=vehicles,
             fiware-servicepath=/4wheels,
             <grouping_rules_interceptor_headers>,
             <name_mappings_interceptor_headers>
        },
        body={
            entityId=car1,
            entityType=car,
            attributes=[
                {
                    attrName=speed,
                    attrType=float,
                    attrValue=112.9
                },
                {
                    attrName=oil_level,
                    attrType=float,
                    attrValue=74.6
                }
            ]
        }
    }

トップ

データベース名とテーブル名

プレフィックスと通知された FIWARE サービス・パスを連結した名前の MongoDB データベース。つまり、sth_vehicles が作成されます。

コレクション名に関しては、MongoDB コレクション名は、設定されている データ・モデルに応じて、以下のものになります (古いエンコーディング) :

FIWARE service path dm-by-service-path dm-by-entity dm-by-attribute
/ sth_/ sth_/car1_car sth_/car1_car_speed
sth_/car1_car_oil_level
/4wheels sth_/4wheels sth_/4wheels_car1_car sth_/4wheels_car1_car_speed
`sth_/4wheels_car1_car_oil

新しいエンコーディングを使用 :

FIWARE service path dm-by-service-path dm-by-entity dm-by-attribute
/ sth_x002f sth_x002fxffffcar1xffffcar sth_x002fxffffcar1xffffcarxffffspeed
sth_x002fxffffcar1xffffcarxffffoil_level
/4wheels sth_x002f4wheels sth_x002f4wheelsxffffcar1xffffcar sth_x002f4wheelsxffffcar1xfffcarxffffspeed
sth_x002f4wheelsxffffcar1xffffcarxffffoil_level

トップ

Row-like の格納の例

data_model=dm-by-service-path と attr_persistence=row を設定パラメータとすると、NGSIToMongo は本体内のデータを以下のように保持します。

    $ mongo -u myuser -p
    MongoDB shell version: 2.6.9
    connecting to: test
    > show databases
    admin              (empty)
    local              0.031GB
    sth_vehicles       0.031GB
    test               0.031GB
    > use vehicles
    switched to db vehicles
    > show collections
    sth_/4wheels
    system.indexes
    > db['sth_/4wheels'].find()
    { "_id" : ObjectId("5534d143fa701f0be751db82"), "recvTimeTs": "1402409899391", "recvTime" : "2015-04-20T12:13:22.41.412Z", "entityId" : "car1", "entityType" : "car", "attrName" : "speed", "attrType" : "float", "attrValue" : "112.9" }
    { "_id" : ObjectId("5534d143fa701f0be751db83"), "recvTimeTs": "1402409899391", "recvTime" : "2015-04-20T12:13:22.41.412Z", "entityId" : "car1", "entityType" : "car", "attrName" : "oil_level", "attrType" : "float", "attrValue" : "74.6" }

If `data_model=dm-by-entity` and `attr_persistence=row` then `NGSIToMongo` will persist the data within the body as:

    $ mongo -u myuser -p
    MongoDB shell version: 2.6.9
    connecting to: test
    > show databases
    admin              (empty)
    local              0.031GB
    sth_vehicles       0.031GB
    test               0.031GB
    > use vehicles
    switched to db vehicles
    > show collections
    sth_/4wheels_car1_car
    system.indexes
    > db['sth_/4wheels_car1_car'].find()
    { "_id" : ObjectId("5534d143fa701f0be751db82"), "recvTimeTs": "1402409899391", "recvTime" : "2015-04-20T12:13:22.41.412Z", "attrName" : "speed", "attrType" : "float", "attrValue" : "112.9" }
    { "_id" : ObjectId("5534d143fa701f0be751db83"), "recvTimeTs": "1402409899391", "recvTime" : "2015-04-20T12:13:22.41.412Z", "attrName" : "oil_level", "attrType" : "float", "attrValue" : "74.6" }

data_model=dm-by-attribute と attr_persistence=row の場合、 NGSIToMongo はデータを次のように保持します :

    $ mongo -u myuser -p
    MongoDB shell version: 2.6.9
    connecting to: test
    > show databases
    admin              (empty)
    local              0.031GB
    sth_vehicles       0.031GB
    test               0.031GB
    > use vehicles
    switched to db vehicles
    > show collections
    sth_/4wheels_car1_car_speed
    sth_/4wheels_car1_car_oil_level
    system.indexes
    > db['sth_/4wheels_car1_car_speed'].find()
     { "_id" : ObjectId("5534d143fa701f0be751db87"), "recvTimeTs": "1402409899391", "recvTime" : "2015-04-20T12:13:22.41.412Z", "attrType" : "float", "attrValue" : "112.9" }
    > db['sth_/4wheels_car1_oil_level'].find()
     { "_id" : ObjectId("5534d143fa701f0be751db87"), "recvTimeTs": "1402409899391", "recvTime" : "2015-04-20T12:13:22.41.412Z", "attrType" : "float", "attrValue" : "74.6" }

トップ

Column-like の格納の例

If data_model=dm-by-service-path and attr_persistence=column then NGSIToMongo will persist the data within the body as:

data_model=dm-by-service-path と attr_persistence=column の場合、NGSIToMongo は本体内のデータを次のように保持します :

    $ mongo -u myuser -p
    MongoDB shell version: 2.6.9
    connecting to: test
    > show databases
    admin              (empty)
    local              0.031GB
    sth_vehicles       0.031GB
    test               0.031GB
    > use vehicles
    switched to db vehicles
    > show collections
    sth_/4wheels
    system.indexes
    > db['sth_/4wheels'].find()
    { "_id" : ObjectId("5534d143fa701f0be751db86"), "recvTimeTs": "1402409899391", "recvTime" : "2015-04-20T12:13:22.41.412Z", "entityId" : "car1", "entityType" : "car", "speed" : "112.9", "oil_level" : "74.6" }

data_model=dm-by-entity と attr_persistence=column の場合、 NGSIToMongo はボディ内のデータを以下のように保持します :

    $ mongo -u myuser -p
    MongoDB shell version: 2.6.9
    connecting to: test
    > show databases
    admin              (empty)
    local              0.031GB
    sth_vehicles       0.031GB
    test               0.031GB
    > use vehicles
    switched to db vehicles
    > show collections
    sth_/4wheels_car1_car
    system.indexes
    > db['sth_/4wheels_car1_car'].find()
    {"_id" : ObjectId("56337ea4c9e77c1614bfdbb7"), "recvTimeTs": "1402409899391", "recvTime" : "2015-04-20T12:13:22.41.412Z", "speed" : "112.9", "oil_level" : "74.6"}
トップ

管理ガイド

設定

NGSIToMongo は以下のパラメータで設定されます :

名前 デフォルト値 許容値 説明
Mongo URI no "MongoURI、典型的には : mongodb://host1[:port1][,host2[:port2],...]". また、ユーザーを追加して渡すこともできます。例 : mongodb://user:password@host1:port
NGSI version v2 サポートされている NGSI のバージョン(v2 と ld) のリスト、現在は v2 のみをサポート
Data Model db-by-entity イベントを受け取ったときにテーブルを作成するためのデータモデル : db-by-service-path または db-by-entity、デフォルト値は db-by-service-path
Attribute persistence row row, column テーブルの許容値内にデータを格納するモードは row と column です
Default Service test Context Broker に Fiware-Service ヘッダを設定しない場合、この値は Fiware-Service として使用されます
Default Service path /path Context Broker に Fiware-Service Path ヘッダを設定しない場合、この値は Fiware-ServicePath として使用されます
Enable encoding true true, false true は新しいエンコーディングを適用し、false は古いエンコーディングを適用します
Enable lowercase true スキーマ名とテーブル名を小文字で作成する場合は true です
Database prefix sth_
Collection prefix sth_ system. は受け入れられません
Data Expiration 0 秒単位で指定された値より古い場合、コレクションは削除されます。時間の参照は recvTime プロパティに保存されているものです。 このポリシーが不要な場合は0に設定してください
Collections Size 0 データ・コレクションのサイズがバイトで指定された値より大きくなると、挿入時間に従って、最も古いデータが削除されます。 サイズ・ベースの切捨てポリシーが時間ベースの切捨てポリシーよりも優先されることに注意してください。 このポリシーが不要な場合は0に設定してください。最小値 (0以外) は4096バイトです
Max Documents 0 データ・コレクション内のドキュメント数が指定された値を超えると、挿入時間に従って、最も古いデータが削除されます。 このポリシーが不要な場合は0に設定してください

設定例は次のようになります :

![mongo-processor](../images/processor-mongo.png

トップ

ユース・ケース

中長期的にはそれほど成長しない Json ベースのドキュメント・ストレージを探しているのなら、NGSIToMongo を使ってください。

トップ

注意事項

バッチ処理について

プログラマーズ・ガイドで説明しているように、NGSIToMongo は、 NGSISinkを拡張します。これは内部の Flume チャンネルからイベントを 収集するための組み込みメカニズムを提供します。このメカニズムにより、 拡張クラスは最終バックエンドで、そのようなイベントのバッチの永続性の詳細を 処理するだけで済みます。

バッチ・メカニズムに関して重要なことは、書き込み回数が劇的に減少するため、 シンクのパフォーマンスが大幅に向上することです。例を見てみましょう、 100の NGSIEvent のバッチを仮定しましょう。最良の場合、これらのイベントは すべて同じエンティティに関するものです。つまり、イベント内のすべてのデータは 同じ MongoDB コレクションに保持されます。イベントを1つずつ処理する場合、 MongoDB に100回挿入する必要があります。それにもかかわらず、この例では １つのインサートのみが必要とされる。明らかに、すべてのイベントが常に 同じ一意のエンティティを対象とするわけではなく、多くのエンティティが 1つのバッチに含まれる可能性があります。しかし、それは問題ではありません。 1つのバッチ内に複数のイベントのサブバッチが作成されるため、最終的な宛先 の MongoDB コレクションごとに1つのサブバッチがあります。最悪の場合、 100個のエンティティ全体が約100個の異なるエンティティ (100個の異なる MongoDB コレクション) になりますが、これは通常の シナリオではありません。したがって、現実的な数のバッチあたり10〜15個の サブバッチを想定して、イベント・アプローチによる100個のイベントのインサートを、 わずか10〜15個のインサートで置き換えます。

バッチメカニズムは、新しいデータが到着しないときにシンクがバッチ構築の 永遠の状態に留まるのを防ぐために累積タイムアウトを追加します。 このようなタイムアウトに達すると、バッチはそのまま維持されます。

非永続バッチのリトライに関しては、いくつかのパラメーターが使用されます。 一方では、Time-to-Live (TTL) を使用して、Draco が確実にイベントを ドロップするまでに何回リトライするかを指定します。一方、リトライ間隔の リストを設定できます。そのようなリストは、最初のリトライ間隔を定義し、 次に2番目のリトライ間隔を定義します。TTL がリストの長さより大きい場合は、 最後のリトライ間隔が必要な回数だけ繰り返されます。

デフォルトで NGSIToMongo は、設定されたバッチ・サイズとバッチ累積 タイムアウトはそれぞれ1秒と30秒です。それにもかかわらず、上記で 説明したように、パフォーマンス上の理由から、少なくともバッチ・サイズを 増やすことを強くお勧めします。最適値は何ですか。バッチのサイズは、 イベントが取得されるチャネルのトランザクションサイズと密接に関係しています (最初のものが2番目のものよりも大きいことは意味がありません)。 また、推定サブバッチの数によっても異なります。累積タイムアウトは、 最終的なストレージで新しいデータを確認したい頻度によって異なります。 イベントのバッチとそれらの適切なサイズ設定に関するより深い議論は、 パフォーマンスのドキュメント にあります。

トップ

recvTime と TimeInstantメタデータについて

デフォルトで NGSIToMongo は、通知受信のタイムスタンプを格納します。 それにもかかわらず、row モードで作業していて TimeInstant という名前の メタデータが通知された場合、そしてその場合のみ、受信タイムスタンプの代わりに そのようなメタデータ値が使用されます。 これは、受信時刻ではなく 測定値の生成時刻 (したがって、TimeInstant メタデータとして通知される) を保持したい場合に便利です。

トップ

エンコードについて

NGSIToMongo は、 MongoDB の命名制限に従います。つまり :

バージョン 1.2.0 (含む) まで、Draco は非常に単純なエンコーディングを 適用しました :

  • データベース名は\, /, ., $, " と、_ としてエンコードされた のキャラクタを持っています
  • コレクション名は、_ としてエンコードされた $ のキャラクタを持っています

バージョン1.3.0 (含む) から、Draco は MongoDB データ構造に合わせて 調整されたこの特定のエンコーディングを適用します。

  • 等号 = は、xffff としてエンコードされます
  • すべての禁止文字は、x キャラクタとそれに続くキャラクタの Unicode としてエンコードされます
  • x 文字と Unicode からなるユーザ定義文字列は、xx の後に Unicode が続いたものとしてエンコードされます
  • xffff は、連結キャラクタとして使用されます

古いエンコーディングは将来、非推奨になりますが、 configuration セクションで説明されているように enable_encoding パラメータを通してエンコーディング・タイプを 切り替えることが可能です。

トップ

MongoDB のサポート・バージョンについて

このシンクは以下のバージョンの Mongo でテストされています :

  • 3.2.6
  • 3.4

トップ

認証と認可

NGSIToMongo の現在の実装は、MongoDB エンドポイントで作成されたユーザ名と パスワードの資格情報に依存しています。

トップ