NGSIGroupingInterceptor¶
重要な注意 : リリース1.6.0から、この機能は、名前マッピングのために推奨されなくなりました。詳細はこちらをご覧ください。
コンテンツ :
機能性¶
これは、Cygnus 専用に設計されたカスタム・インターセプタです。その目的は、通知されたエンティティに関するデータが保持される宛先エンティティを推測することによって元の NGSIEvent オブジェクト(NGSIRestHandlerによって処理される NGSI 通知からの)を変更することです。この宛先エンティティは、使用されるシンクに応じて、HDFS ファイル名、MySQL テーブル名、または CKAN リソース名です。さらに、宛先エンティティを含む新しい fiware-servicePath を構成することができる。例えば、HDFS の場合、これはフォルダです。CKAN の場合、これはパッケージです。MySQLの場合、これは単にテーブル名のプレフィックスです。
そのような推論は、NGSIEvent の ContextElement オブジェクト内の特定の構成フィールドを検査すること(ただし変更はしない)によって行われます。そのようなフィールドの連結が設定された正規表現と一致する場合 :
- 設定された宛先エンティティが
grouped-entityヘッダ値として追加されます - 設定された宛先 FIWARE service path が
grouped-servicepathヘッダ値として追加されます
さらに、元のエンティティ ID とタイプの連結を含む notified-entity ヘッダが追加されます。
このように、グループ化ルールを有効にしたシンクでは、grouped-entity および grouped-servicepath ヘッダの両方が使用されます。そうでない場合、すなわち元の通知が使用されることを意図している場合、notified-entity および fiware-servicepath ヘッダが使用されます。
グループ化ルールの構文¶
この形式に従った、Json ライクのルール定義を含むファイルがあります :
{
"grouping_rules": [
{
"id": 1,
"fields": [
...
],
"regex": "...",
"destination": "...",
"fiware_service_path": "..."
},
...
]
}であること :
id: ユニークな符号なし整数ベースの識別子fields: 正規表現マッチングのために連結されるフィールド。連結のために利用可能なフィールドの辞書は、entityId,entityTypeおよびservicePathです。これらのフィールドの順序は、連結が左から右に行われるので重要です。regex: 連結されたフィールドに適用される Javaライクの正規表現。\のような特殊文字はエスケープする必要があります。\は\\としてエスケープされますdestination: データが効果的に永続化される HDFS ファイルまたは CKAN リソースの名前。MySQL、Mongo、およびS TH Comet の場合、これはテーブル/コレクション名を補完します。fiware_service_path: 通知されたfiware-servicePathを新しいものに置き換えます。シンクは、これを上記の宛先エンティティが配置される HDFS フォルダまたは CKAN パッケージの名前に変換します。MySQL、Mongo、STH Cometの場合、これはテーブル/コレクション名の前に付けられます
通知ごとに、ルールの1つが一致するまでルールが試行されます。マッチすれば、ルールはその通知のためにもうチェックされません。
ルールの構文に関して、すべてのフィールドは必須であり、有効な値を持たなければなりません。
インターセプト前後のヘッダ¶
インターセプトする前に、これらは NGSIRestHandler によってすべての内部 Flume イベントに追加されたヘッダです :
fiware-service: 通知されたデータに関連するエンティティが属する FIWARE servicefiware-servicepath: 通知されたデータに関連するエンティティが属する FIWARE service path。通知が異なるサービスパスのいくつかのエンティティに関連する場合、これらはカンマで区切られたこのヘッダ内に含まれますfiware-correlator: Cygnus が属する統合全体に e2e フローを識別するために予約された UUIDtransaction-id: Flume ソースから Flume シンクへの内部フローを識別するための UUID
インターセプトの後、NGSIGroupingInterceptor によって追加されたヘッダーは次のとおりです :
notified-entities: カンマで区切られた完全なエンティティ ID/宛先のリストです。これは、通知されたエンティティ ID とそのタイプの連結です。これは内部ヘッダなので、連結文字は等号=です。 パブリックにする時には、この等号は、_(古いエンコーディング) または `xffff (新しいエンコーディング)に変換されます。grouped-entities: グループ化/変更されたエンティティ/宛先のカンマ区切りリストgrouped-servicepaths: グループ化/変更された FIWARE service paths のカンマ区切りリスト
他のインターセプタは、ネイティブのタイムスタンプ・インターセプタによって追加された timestamp ヘッダのような、さらなるヘッダを追加することができます。
例¶
これらのルールを想定しましょう :
{
"grouping_rules": [
{
"id": 1,
"fields": [
"entityId",
"entityType"
],
"regex": "other\\.(\\d*)room",
"destination": "all_other",
"fiware_service_path": "/other"
},
{
"id": 2,
"fields": [
"entityId",
"entityType"
],
"regex": "suite\\.(\\D*)room",
"destination": "all_suites",
"fiware_service_path": "/suites"
}
]
}次に、受け取った通知に関する以下の非インターセプト・イベントを想定しましょう。以下のコードは実際のデータフォーマットではなくオブジェクト表現です。
notification={
headers={
fiware-service=hotel1,
fiware-servicepath=/other,/suites,
correlation-id=1234567890-0000-1234567890
},
body={
{
entityId=suite.12,
entityType=room,
attributes=[
...
]
},
{
entityId=other.9,
entityType=room,
attributes=[
...
]
}
}
}見て分かるように、FIWARE service (hotel) 内の同じタイプ(room)の2つのエンティティ(suite.12 および other.9)が異なるサービスパス(/suites および /other)が通知されます。NGSIRestHandler は2つの NGSIEvents を作成します：
ngsi-event-1={
headers={
fiware-service=hotel,
fiware-servicepath=/suites,
transaction-id=1234567890-0000-1234567890,
correlation-id=1234567890-0000-1234567890,
timestamp=1234567890,
mapped-fiware-service=hotel,
mapped-fiware-service-path=/suites
},
original-context-element={
entityId=suite.12,
entityType=room,
attributes=[
...
]
},
mapped-context-element=null
}
ngsi-event-2={
headers={
fiware-service=hotel,
fiware-servicepath=/other,
transaction-id=1234567890-0000-1234567890,
correlation-id=1234567890-0000-1234567890,
timestamp=1234567890,
mapped-fiware-service=hotel,
mapped-fiware-service-path=/other
},
original-context-element={
entityId=other.9,
entityType=room,
attributes=[
...
]
},
mapped-context-element=null
}いったんインターセプトされると、上記のイベントは次のようになります。以下のコードは実際のデータフォーマットではなくオブジェクト表現です :
intercepted-ngsi-event-1={
headers={
fiware-service=hotel,
fiware-servicepath=/suites,
transaction-id=1234567890-0000-1234567890,
correlation-id=1234567890-0000-1234567890,
timestamp=1234567890,
grouped-entity=all_suites,
grouped-servicepath=/suites,
notified-entity=suite.12_room
},
original-context-element={
entityId=suite.12,
entityType=room,
attributes=[
...
]
},
mapped-context-element=null
}
intercepted-ngsi-event-2={
headers={
fiware-service=hotel,
fiware-servicepath=/other,
transaction-id=1234567890-0000-1234567890,
correlation-id=1234567890-0000-1234567890,
timestamp=1234567890,
grouped-entity=all_other,
grouped-servicepath=/other,
notified-entity=other.9_room
},
original-context-element={
entityId=other.9,
entityType=room,
attributes=[
...
]
},
mapped-context-element=null
}管理ガイド¶
構成¶
NGSIGroupingInterceptor は、次のパラメータによって構成されます :
| パラメータ | 必須 | デフォルト値 | コメント |
|---|---|---|---|
| grouping_rules_conf_file | yes | N/A | グループ化ルールファイルへの絶対パスを設定することは非常に重要です。グループ化ルールファイルは通常 [FLUME_HOME_DIR]/conf/ にあり、Cygnus ディストリビューション内にテンプレートが存在します |
| enable_encoding | no | false | true または false。true は新しいエンコーディングを適用し、false は古いエンコーディングを適用します |
構成例は次のとおりです :
cygnus-ngsi.sources.http-source.interceptors = gi <other-interceptors>
cygnus-ngsi.sources.http-source.interceptors.gi.type = com.telefonica.iot.cygnus.interceptors.NGSIGroupingInterceptor$Builder
cygnus-ngsi.sources.http-source.interceptors.gi.grouping_rules_conf_file = [FLUME_HOME_DIR]/conf/grouping_rules.conf
cygnus-ngsi.sources.http-source.interceptors.gi.enable_encoding = false管理インタフェース関連の操作¶
Cygnus の管理インターフェイスは、グループ化ルール機能に関連する /v1/groupingrules パスの下で一連の操作を公開し、ルールの一覧表示/更新/削除を許可します。例えば :
GET http://<cygnus_host>:<management_port>/v1/groupingrules{
"grouping_rules": [
{
"destination": "allcars",
"fields": [
"entityType"
],
"fiware_service_path": "cars",
"id": 1,
"regex": "Car"
},
{
"destination": "allrooms",
"fields": [
"entityType"
],
"fiware_service_path": "rooms",
"id": 2,
"regex": "Room"
}
]
}詳細を知るためにこのリンクをチェックしてください。