NGSIToMySQL¶

コンテンツ:

機能性
管理ガイド
- 設定
- ユース・ケース
- 注意事項
  - テーブル・タイプについて
  - 持続モードについて
  - [バッチ処理について(#section2.3.3)
  - タイムゾーン情報
  - エンコードについて
  - リソースの上限設定/期限切れレコードについて
- 認証と認可

機能性¶

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

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

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

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

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

これは、フローファイルとして受信した Draco Listen HTTP Processor (ネイティブの NiFi でも同じ名前) で行われます。このプロセッサは、フローファイルの属性と内容を NGSI イベントにマッピングします。変換されると、データは (現在は NGSIEvent オブジェクトとして) 将来の使用のために内部チャネルに入れられます (次のセクションを参照してください) 。

`NGSIEvent` を MySQL データ構造にマッピング¶

MySQL はデータ行のテーブルを含むデータベースにデータを編成します。このような組織は、NGSIEventが永続化するたびにNGSIToMySQLによって活用されます。

MySQL データベースの命名規則¶

通知された fiware-service ヘッダ値、または、そのようなヘッダがない場合は、 FIWARE Service のデフォルト値の名前のデータベースが作成されます (まだ存在していない場合)。

MySQL は英数字の $ と _ だけを受け付けます。これは特定の encoding が enable_encoding 設定パラメータに応じて適用されます。

MySQL データベースの名前の長さは64文字に制限されています。

MySQL テーブルの命名規則¶

これらのテーブルの名前は、設定されているデータ・モデルによって異なります (詳細については、設定セクションを参照してください)。

サービス・パスによるデータ・モデル (data_model=dm-by-service-path)。データ・モデル名が示すように、通知された FIWARE サービス・パス、または NGSIRestHandler にデフォルトとして設定されたものがテーブルの名前として使用されます。これにより、同じサービス・パスに属するすべての NGSI エンティティに関するデータがこの一意のテーブルに格納されます。このデータモデルに関する唯一の制約は、FIWARE サービス・パスをルートパス (/) にすることはできないということです
エンティティ (data_model=dm-by-entity) によるデータ・モデル。各エンティティについて、通知された/デフォルトの FIWARE サービス・パスは、テーブル名を構成するために通知されたエンティティの ID　とタイプに連結されます。連結文字は _ (アンダースコア) です。FIWARE サービス・パスがルートパス (/) の場合、エンティティ ID とタイプのみが連結されます

MySQL は英数字の $ と _ だけを受け付けます。これは特定の encoding が enable_encoding 設定パラメータに応じて適用されます。

MySQL データベースの名前の長さは64文字に制限されています。

次の表は、テーブル名の構成 (古いエンコーディング) をまとめたものです :

FIWARE service path	`dm-by-service-path`	`dm-by-entity`
`/`	N/A	`<entityId>_<entityType>`
`/<svcPath>`	`<svcPath>`	`<svcPath>_<entityId>_<entityType>`

次の表は、テーブル名の構成 (新しいエンコーディング) をまとめたものです :

FIWARE service path	`dm-by-service-path`	`dm-by-entity`
`/`	`x002f`	`x002fxffff<entityId>xffff<entityType>`
`/<svcPath>`	`x002f<svcPath>`	`x002f<svcPath>xffff<entityId>xffff<entityType>`

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

Row-like の格納¶

上記のテーブルに格納されている特定のデータに関して、attr_persistence パラメータが row (デフォルト格納モード) に設定されている場合、通知されたデータは属性ごとに格納され、それらの各々に対するインサートを構成します。各インサートには、以下のフィールドが含まれています :

recvTimeTs: UTC タイムスタンプ (ミリ秒)
recvTime: 人が読める形式の UTC タイムスタンプ。(ISO 8601)
fiwareServicePath: 通知された fiware-servicePath、または通知されない場合はデフォルト設定。
entityId: 通知されたエンティティ識別子
entityType: 通知されたエンティティ・タイプ
attrName: 通知された属性名
attrType: 通知された属性タイプ
attrValue: 最も単純な形式では、この値は単なる文字列ですが、Orion 0.11.0 以降では Json オブジェクトまたは Json 配列になります
attrMd: Json の属性のメタデータ配列の文字列シリアル化が含まれています (属性にメタデータがない場合は、空の配列 [] が挿入されます)

Column-like の格納¶

上記のテーブルに格納されている特定のデータに関して、attr_persistence パラメータが column に設定されている場合、通知されたエンティティ全体に対して1行が構成され、次のフィールドが含まれます。

recvTime: 人が読める形式のタイムスタンプ (ISO 8601 に似ていますが、すべての MySQL タイムスタンプは UTC 形式であると想定されているため、 UTC を表す文字 Z は使用しません)
fiwareServicePath: 通知された値またはデフォルトの値
entityId: 通知されたエンティティ識別子
entityType: 通知されたエンティティ・タイプ
通知された属性ごとに、属性として指定されたフィールドが考慮されます。このフィールドは時間とともに属性値を格納します。
通知された属性ごとに、属性名と `_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
                }
            ]
        }
    }

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

MySQL データベース名は常に vehicles になります。

MySQL のテーブル名は、設定されているデータモデルに応じて、次のようになります (古いエンコーディング) :

FIWARE service path	`dm-by-service-path`	`dm-by-entity`
`/`	N/A	`car1_car`
`/4wheels`	`4wheels`	`4wheels_car1_car`

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

FIWARE service path	`dm-by-service-path`	`dm-by-entity`
`/`	`x002f`	`car1xffffcar`
`/wheels`	`x002f4wheels`	`x002f4wheelsxffffcar1xffffcar`

Row-like の格納の例¶

構成パラメータとして attr_persistence=row 仮定すると、NGSIToMySQLは、ボディ内のデータを次のように永続化します :

    mysql> select * from 4wheels_car1_car;
    +------------+----------------------------+-------------------+----------+------------+-------------+-----------+-----------+--------+
    | recvTimeTs | recvTime                   | fiwareServicePath | entityId | entityType | attrName    | attrType  | attrValue | attrMd |
    +------------+----------------------------+-------------------+----------+------------+-------------+-----------+-----------+--------+
    | 1429535775 | 2015-04-20T12:13:22.41.124 | 4wheels           | car1     | car        |  speed      | float     | 112.9     | []     |
    | 1429535775 | 2015-04-20T12:13:22.41.124 | 4wheels           | car1     | car        |  oil_level  | float     | 74.6      | []     |
    +------------+----------------------------+-------------------+----------+------------+-------------+-----------+-----------+--------+
    2 row in set (0.00 sec)

Column-like の格納の例¶

attr_persistence=columの場合は、NGSIToMySQL` は、ボディ内のデータを次のように永続化します :

    mysql> select * from 4wheels_car1_car;
    +----------------------------+-------------------+----------+------------+-------+----------+-----------+--------------+
    | recvTime                   | fiwareServicePath | entityId | entityType | speed | speed_md | oil_level | oil_level_md |
    +----------------------------+-------------------+----------+------------+-------+----------+-----------+--------------+
    | 2015-04-20T12:13:22.41.124 | 4wheels           | car1     | car        | 112.9 | []       |  74.6     | []           |
    +----------------------------+-------------------+----------+------------+-------+----------+-----------+--------------+
    1 row in set (0.00 sec)

管理ガイド¶

設定¶

NGSIToMySQL は、次のパラメータで構成されています (必須プロパティの名前は太字で表示されています) :

★★★

名前	デフォルト値	許容値	説明
JDBC Connection Pool	no		特定のデータベース・エンジンに接続するためのコントローラ・サービス
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	表の許容値内にデータを保管するモードは、行と列です
Default Service	test		Context Broker に Fiware-Service ヘッダを設定しない場合、この値が Fiware-Service として使用されます
Default Service path	/path		Context Broker に Fiware-ServicePath ヘッダを設定しない場合、この値が Fiware-ServicePath として使用されます
Enable encoding	true	true, false	true は新しいエンコーディングを適用し、false は古いエンコーディングを適用します
Enable lowercase	true	true, false	スキーマ名とテーブル名を小文字で作成する場合は true　です
Batch size	10		単一のトランザクションでデータベースに書き込むためのフローファイルの推奨数
Rollback on failure	false	true, false	エラー処理方法を指定してください。デフォルト (false) では、フローファイルの処理中にエラーが発生した場合、フローファイルはエラー・タイプに基づいて 'failure' または 'retry' のリレーションシップにルーティングされ、プロセッサは次のフローファイルを続行できます。代わりに、現在処理されているフローファイルをロールバックし、それ以降の処理を直ちに中止することができます。その場合は、この 'Rollback On Failure' プロパティを有効にすることで可能になります。有効にすると、失敗したフローファイルはペナルティを課されることなく入力リレーションシップを維持し、正常に処理されるか他の方法で削除されるまで繰り返し処理されます。頻繁に再試行しないようにするには、適切な 'Yield Duration' を設定することが重要です

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

mysql-processor

ユース・ケース¶

中長期的にそれほど大きくならないデータベース・ストレージを探している場合に NGSIToMySQL を使用します。

注意事項¶

テーブル・タイプについて¶

表のタイプ設定パラメータは、見てのとおり、デフォルトの宛先 (つまり同じエンティティに関するすべての通知が同じ MySQL テーブル内に格納されます) またはデフォルトの service-path (つまりすべての通知) によってデータを直接集約する方法です。ほぼ同じサービスパスが同じMySQLテーブル内に格納されます) 。

表のタイプ設定パラメータは、見てのとおり、デフォルトの宛先 (つまり同じエンティティに関するすべての通知が同じ MySQL テーブル内に格納されます) またはデフォルトの service-path (つまりすべての通知) によってデータを直接集約する方法です。ほぼ同じサービスパスが同じ MySQL テーブル内に格納されます)。

持続モード (persistence mode) について¶

常に同じ数の属性が通知されるとは限らないことに注意してください。これは NGSI ライクの送信者に対して行われたサブスクリプションに依存します。通知された属性ごとに固定の8フィールドのデータ行が挿入されるため、これは row 永続化モードでは問題になりません。それにもかかわらず、 column モードは (フィールドに関して) 異なる長さのいくつかのデータ行によって影響されるかもしれません。したがって、column モードはあなたのサブスクリプションが常に同じ属性を送信するように設計されている場合、最後の通知以降に更新されていない場合にのみ推奨されます。

さらに、column モードで実行しているときは、通知された属性の数 (したがって、データストア内に書き込まれるフィールドの数) が不明なため、テーブルを自動的に作成することはできず、事前に Draco にプロビジョニングする必要があります実行。書き込まれるフィールドの数は通知された属性の数とは無関係に常に一定であるため、これは row モードの場合ではありません。

バッチ処理について¶

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

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

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

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

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

タイムゾーン情報¶

MySQL はその情報を環境変数として格納するため、タイムゾーン情報は MySQL タイムスタンプに追加されません。MySQL のタイムスタンプは UTC 時間で保存されます。

エンコードについて¶

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

英数字以外の文字はすべてアンダースコア _ に置き換えられました
下線は、連結文字としても使用されました
FIWARE サービス・パス内のスラッシュ / は無視されます

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

英数字はエンコードされません
数字はエンコードされません
アンダースコア文字 _ はエンコードされません
等号 = は、xffff としてエンコードされます
FIWARE サービス・パスのスラッシュを含む他のすべての文字は、x 文字の後にその文字の Unicode が続く形でエンコードされます
x 文字と Unicode で構成されるユーザ定義文字列は、xx の後に Unicode が続いたものとしてエンコードされます
他のすべての文字はエンコードされません
xffff は連結文字として使用されます

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

リソースの上限設定/期限切れレコードについて¶

上限と有効期限はデフォルトで無効になっています。それでも、必要に応じてこれを有効にすることができます :

レコード数による上限。これにより、設定された最大レコード数に達するまでリソースを増やすことができ (persistence_policy.max_records)、そのような一定のレコード数を維持します。
レコードの期限切れ。これにより、レコードが古くなるまで、つまり、設定された特定の有効期限を超えるまで、リソースを増やすことができます (persistence_policy.expiration_time)

« Previous Next »