NGSIToPostgreSQL¶
コンテンツ :
機能性¶
NGSIToPostgreSQL は、PostgreSQL server 内で
NGSI ライクのコンテキスト・データのイベントを永続化するように設計された
プロセッサです。 通常、このようなコンテキスト・データは
Orion Context Broker
インスタンスによって通知されますが、
NGSI 言語を話す他のシステムでもかまいません。
データ・ジェネレータとは無関係に、NGSI コンテキスト・データは常に
Draco のソースで内部の NGSIEvent オブジェクトに変換されます。
結局、これらのイベント内の情報は特定の PostgreSQL データ構造に
マッピングされなければなりません。
次のセクションではこれについて詳しく説明します。
NGSI イベントを NGSIEvent オブジェクトにマッピング¶
コンテキスト・データを含む通知された NGSI イベントは、NGSI データ・ジェネレータ
やそれが永続化されている最後のバックエンドとは無関係に、NGSIEvent
オブジェクトに変換されます。(各コンテキスト要素に対して NGSIEvent
が作成されます。そのようなイベントは特定のヘッダと ContextElement
オブジェクトの組み合わせです)
これは NGSIRestHandler のおかげで Draco-ngsi HTTP
リスナー (Flumeの専門用語集にある）で行われています。 変換されると、
データは、NGSIEventオブジェクトとして、将来の利用のために
内部チャンネルに入れられます。次のセクションを参照ください。
NGSIEvent を PostgreSQL のデータ構造にマッピング¶
PostgreSQL は、データ行のテーブルを含むデータベース内のスキーマにデータを
整理します。このような組織は、 NGSIEvent が永続化するたびに
NGSIToPostgreSQL によって利用されます。
PostgreSQL データベースの命名規則¶
PostgreSQL を使用した操作の前に、使用するデータベースを作成する必要があります。
PostgreSQL
は、英数字とアンダースコア (_) のみを受け付けます。これにより、
enable_encoding 設定パラメータに応じて特定のエンコードが適用されます。
PostgreSQL データベースの名前の長さ は63文字に制限されています。
PostgreSQL スキーマの命名規則¶
通知された fiware-service ヘッダ値、または、そのようなヘッダがない場合は、
FIWARE service のデフォルト値を使った名前のスキーマが作成されます
(スキーマがまだ存在していない場合)。
PostgreSQL
は、英数字とアンダースコア (_) のみを受け付けます。これにより、
enable_encoding 設定パラメータに応じて特定のエンコードが適用されます。
PostgreSQL スキーマの名前の長さ は63文字に制限されています。
PostgreSQL のテーブル命名規則¶
これらのテーブルの名前は、設定されているデータモデルによって異なります。 詳細については、設定 セクションを参照してください :
- サービス・パス (
data_model=dm-by-service-path) によるデータ・モデル。 データ・モデル名が示すように、通知された FIWARE service path またはNGSIRestHandlerにデフォルトとして設定された ものがテーブルの名前として使用されます。これにより、同じサービス・パスに 属するすべての NGSI エンティティに関するデータをこの一意のテーブルに 格納できます。このデータモデルに関する唯一の制約は、FIWARE service path をルートパス (/) にすることはできないということです - エンティティによるデータモデル (
data_model=dm-by-entity)。 各エンティティについて、通知された/デフォルトの FIWARE service path は、テーブル名を構成するために通知されたエンティティの ID と型に連結されます。FIWARE service path がルートパス (/) の場合、エンティティ ID と型のみが連結されます。
PostgreSQL は英数字とアンダースコア (_)
のみを受け付けます
。これは特定の エンコーディング が enable_encoding
設定パラメータに応じて適用されることになります。
PostgreSQL テーブルの名前の長さ は63文字に制限されています。
次の表は、テーブル名の構成 (古いエンコーディング) をまとめたものです :
| 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 と型の連結が既に
notified_entities/grouped_entities ヘッダ値に指定されていることを
確認してください。NGSIEvent 内での詳細については 設定
セクションを参照してください。
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_persistenceparameter が column に設定されている場合、
通知されたエンティティ全体に対して1行が構成され、次のフィールドが含まれます :
recvTime: 人が読み取れる形式の UTC タイムスタンプ (ISO 8601)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
}
]
}
}データベース, スキーマ, テーブル名¶
PostgreSQL データベース名は、ユーザが選択します。
PostgreSQL スキーマは常に vehicles になります。
PostgreSQL のテーブル名は、設定されているデータモデルに応じて、 次のようになります (古いエンコーディング) :
| 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 | x002fxffffcar1xffffcar |
/4wheels |
x002f4wheels |
x002f4wheelsxffffcar1xffffcar |
Row-like の格納の例¶
attr_persistence=row を設定パラメータとして仮定すると、
NGSIToPostgreSQL は、次のようにボディ内のデータを永続化します。
$ psql -U myuser
psql (9.5.0)
Type "help" for help.
postgres-# \c my-database
my-database# \dn
List of schemas
Name | Owner
----------+----------
vehicles | postgres
public | postgres
(2 rows)
my-database=# \dt vehicles.*
List of relations
Schema | Name | Type | Owner
----------+-------------------+-------+----------
vehicles | 4wheels_car1_car | table | postgres
(1 row)
postgresql> select * from vehicles.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 の格納の例¶
近日公開。
管理ガイド¶
設定¶
NGSIToPostgreSQL は、次のパラメータで設定されます :
| 名前 | デフォルト値 | 許容値 | 説明 |
|---|---|---|---|
| JDBC Connection Pool | no | 特定のデータベース・エンジンに接続するためのコントローラ・サービス | |
| NGSI version | v2 | サポートされている NGSI (v 2と 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-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' を設定することが重要です |
設定例は次のようになります :
ユース・ケース¶
いくつかのテナントを持つ大きなデータベースを探しているのケースでは、
NGSIToPostgreSQL を使ってください。PostgreSQL
は複数のデータベースを持つことは得意ではありませんが、
異なるスキーマを持つことは非常に得意です。
重要なメモ¶
テーブル・タイプについて¶
テーブル型の設定パラメータは、見てのとおり、デフォルトの宛先 による ダイレクトな データの収集方法です。 (つまり同じエンティティに関するすべての通知は同じ PostgreSQL のテーブルに格納されます) または デフォルト の service-path (つまり、同じ service-path に関するすべての通知は同じ PostgreSQL のテーブルに格納されます)
永続化モードについて¶
常に同じ数の属性が通知されるとは限らないことに注意してください。
これは NGSI ライクの送信者に対して行われたサブスクリプションに依存します。
通知された属性ごとに固定の8フィールドのデータ行が挿入されるため、これは
row 永続性モードでは問題になりません。それにもかかわらず、column
モードは (フィールドに関して) 異なる長さのいくつかのデータ行によって
影響されるかもしれません。したがって、columnモードは、最後の通知以降に
更新されていなくても、サブスクリプションが常に同じ属性を送信するように
設計されている場合にのみ推奨されます。
さらに、columnモードで実行しているとき、通知された属性の数
(したがってDatastore内に書き込まれるフィールドの数) が不明なため、
テーブルを自動的に作成することはできず、
Draco の実行の前にプロビジョニングする必要があります。
書き込まれるフィールドの数は通知された属性の数とは無関係に常に
一定であるため、これは row モードの場合はありません。
バッチ処理について¶
プログラマーズ・ガイドで説明しているように、
NGSIToPostgreSQL は、NGSISink を拡張します。これは内部の Flume
チャンネルからイベントを収集するための組み込みメカニズムを提供します。
このメカニズムにより、拡張クラスは最終バックエンドでそのようなイベントの
バッチの永続性の詳細を処理するだけで済みます。
バッチ・メカニズムに関して重要なことは、書き込み回数が劇的に減少するため、
シンクのパフォーマンスが大幅に向上することです。例を見てみましょう、
100 NGSIEvent のバッチを仮定します。最良の場合、これらのイベントは
すべて同じエンティティに関するものです。つまり、イベント内のすべての
データは同じ PostgreSQL テーブルに保持されます。イベントを一つずつ処理する場合、
PostgreSQL への100回の挿入が必要になります。それにもかかわらず、
この例では１つのインサートのみが必要とされます。明らかに、すべてのイベントが
常に同じ一意のエンティティを対象とするわけではなく、多くのエンティティが
1つのバッチに含まれる可能性があります。しかし、イベントのいくつかの
サブ・バッチが1つのバッチ内に作成されるため、これは問題になりません。
最終的な宛先の PostgreSQL テーブルごとに1つのサブ・バッチがあります。
最悪の場合、100個のエンティティ全体が約100個の異なるエンティティ
(100個の異なる PostgreSQL テーブル) になりますが、これは通常のシナリオでは
ありません。したがって、1バッチあたり10〜15個のサブバッチの現実的な数を
想定して、イベント・アプローチによるイベントの100個の挿入を、
わずか10〜15個の挿入で置き換えます。
バッチ・メカニズムは、新しいデータが到着しないときにシンクがバッチ構築の 永遠の状態に留まるのを防ぐために累積タイムアウトを追加します。 このようなタイムアウトに達すると、バッチはそのまま維持されます。
非永続バッチのリトライに関しては、いくつかのパラメータが使用されます。 一方では、Time-to-Live (TTL) を使用して、Draco が確実にイベントを ドロップするまでに何回リトライするかを指定します。一方、リトライ間隔の リストを設定できます。そのようなリストは、最初のリトライ間隔を定義し、 次に2番目のリトライ間隔を定義します。TTL がリストの長さより大きい場合は、 最後のリトライ間隔が必要な回数だけ繰り返されます。
デフォルトで、NGSIToPostgreSQL は、設定されたバッチサイズと
バッチ累積タイムアウトは、それぞれ1秒と30秒に設定します。それにもかかわらず、
上記で説明したように、パフォーマンス上の理由から、少なくともバッチのサイズを
増やすことを強くお勧めします。最適値はどれですか。バッチのサイズは、
イベントが取得されるチャネルのトランザクションのサイズと密接に関係しています
(最初のものが2番目のものよりも大きいことは意味がありません)。
また、推定サブ・バッチの数によっても異なります。累積タイムアウトは、
最終的なストレージで新しいデータを確認したい頻度によって異なります。
タイムゾーン情報¶
PostgreSQL はタイムゾーン情報の情報を環境変数として格納するため、 その情報は PostgreSQL タイムスタンプには追加されません。 PostgreSQL タイムスタンプは UTC 時間で保存されます。
エンコードについて¶
バージョン1.2.0 (含む) まで、Draco は非常に単純なエンコーディングを適用しました :
- 英数字以外の文字はすべてアンダースコア
_に置き換えられました - 下線は、連結文字としても使用されました
- FIWARE service path 内のスラッシュ
/は無視されます
バージョン1.3.0 (含む) から、Draco は PostgreSQL データ構造に合わせた 特定のエンコーディングを適用します。
- 小文字の英数字はエンコードされません
- 大文字の英数字はエンコードされます
- 数字はエンコードされません
- アンダースコア文字
_はエンコードされません - 等号
=は、xffffとしてエンコードされます - FIWARE service paths のスラッシュを含む他のすべてのキャラクタは、
xキャラクタと、それに続く Unicode キャラクタとしてエンコードされます xキャラクタと Unicode で構成されるユーザ定義文字列は、xxの後に Unicode が続いたものとしてエンコードされますxffffは連結文字として使用されます
古いエンコーディングは将来非推奨になりますが、configuration
セクションで説明しているように enable_encoding パラメータを通して
エンコーディングのタイプを切り替えることは可能です。
認証と認可¶
NGSIToPostgreSQL の現在の実装は、PostgreSQL エンドポイントで作成された
データベース、ユーザ名、パスワードの認証情報に依存しています。