データ・モデル
イントロダクション
通常、Orion Contex Broker が透過的に使用するため、MongoDB に直接アクセスする必要はありません。しかし、いくつかの操作 (例えば、バックアップ、障害回復など) では、データベースの構造を知ることは有益です。このセクションでは、この情報を提供します。
一部のアクションは元に戻すことができなので、データベースに直接アクセスする必要がある場合、操作には注意が必要です。最初は バックアップをとることをお勧めします。
Orion Context Broker は、データベース内で次のサブセクションで説明する4つのコレクションを使用します。
エンティティ・コレクション
エンティティ のコレクションは NGSI エンティティに関する情報を格納します。コレクション内の各ドキュメントはエンティティに対応します。
フィールド :
- _id は ID 自体と型を含む EntityID を格納します。このために _id を使用すると、EntityID が一意であることが保証されます。このフィールドの JSON ドキュメントは次のとおりです :
- id : エンティティの NGSI ID
- type : エンティティの NGSI 型
- servicePath : サービスパス機能に関連します
- attrs は、そのエンティティに対して作成されたさまざまな属性のキーマップです。キーは、属性名で生成されます ("." は MongoDB document keys では有効な文字ではないので、"=" に変更します)。マップの各要素には、次の情報があります :
- type: 属性型
- value : 属性値 (少なくとも1つの更新を受け取った属性の場合) です。バージョン 0.10.1 までは、この値は常に文字列ですが、0.11.0 ではこの値は構造化値を表す JSON オブジェクトまたは JSON ベクトルでもあります (Orion API 仕様の属性表現のセクションを参照ください)
- md (オプション) : カスタム・メタデータです。これはメタデータオブジェクトのキーマップです。キーはメタデータ名で生成されます ("." は MongoDB document keys では有効な文字ではないので、"=" に変更します)。例えば、"m.x" というメタデータは "m = x" キーを使用します。各キーのオブジェクト値には、メタデータの type と value の2つのフィールドがあります
- mdNames : 文字列の配列です。その要素は、属性のメタデータの名前です。ここでは "." から "=" への置換は行われません
- creDate: (追加の結果として) 属性の作成に対応するタイムスタンプ (浮動小数点数、ミリ秒の秒を意味します)
- modDate: 最後の属性の更新に対応するタイムスタンプ (浮動小数点数、ミリ秒の秒を意味します)。 作成後に属性が変更されていない場合は、creDate と一致します
- attrNames : 文字列の配列です。その要素は、エンティティの属性の名前 (IDs なし) です。この場合、 "." から "=" への置換は行われません
- creDate: (追加の結果として) エンティティ作成日に対応するタイムスタンプ (浮動小数点数、ミリ秒の秒を意味します)
- modDate: 最後のエンティティの更新に対応するタイムスタンプ (浮動小数点数、ミリ秒の秒を意味します)。 これは通常、少なくとも1つの属性に対応する modDate と同じであることに注意してください (いつも同じではありません : 最後の更新が DELETE 操作の場合は同じではありません)。 エンティティが作成後に変更されていない場合は、creDate と一致します
- location (オプション) : エンティティの地理的位置です、次のフィールドで構成されます :
- attrName : attrs 配列内の地理的位置を識別する属性名です
- coords : エンティティの位置を表す GeoJSON です。詳細は以下を参照してください
- lastCorrelator : エンティティ上の最後の更新要求における root correlator の値です。自己通知ループ保護ロジックによって使用されます。root correlator とは、サフィックスのない更新要求の
Fiware-Correlatorリクエスト・ヘッダの値を意味します。例えば、Fiware-Correlator: f320136c-0192-11eb-a893-000c29df7908; cbnotif=32の root correlator はf320136c-0192-11eb-a893-000c29df7908です - expDate (オプション): エンティティの有効期限のタイムスタンプ (Date オブジェクトとして)。詳細については、一時的なエンティティの機能を参照してください
location.coordsin については、いくつかの形式を使用することができます :
- ポイントを表します (geo:point で使用されるもの) :
{
"type": "Point",
"coordinates": [ -3.691944, 40.418889 ]
}
- ラインを表します (geo:line で使用されているもの) :
{
"type": "LineString",
"coordinates": [ [ 10, 0], [0, 10] ]
}
- ポリゴンを表します (geo:box と geo:polygon で使用されるもの) :
{
"type": "Polygon",
"coordinates": [ [ [ 10, 0], [0, 10], [0, 0], [10, 0] ] ]
}
- 最後に、
location.coordsは、GeoJSON 形式で場所を表現する任意の JSON オブジェクトを保持できます。任意の GeoJSON は geo:json 属性型で使用でき、有効なオブジェクトを導入するのはユーザの責任です。上記3つのケースは、実際には "fixed" ケースの GeoJSON 表現です。
座標ペアは、geo-location API で使用されている順序とは反対の経度－緯度順 (longitude-latitude order) を使用することに注意してください。これは内部の MongoDB ジオロケーション実装 (GeoJSON に基づいています) が経度－緯度順を使用するためです。しかし、ユーザに近い他のシステム (Google マップなど) では、緯度－経度形式 (latitude-longitude format) を使用しているため、後者を API に使用しています。
サンプルドキュメント :
{
"_id":
"id": "E1",
"type": "T1",
"servicePath": "/"
},
"attrs": {
"A1": {
"type": "TA1",
"value": "282",
"creDate" : 1389376081.8471954,
"modDate" : 1389376120.2154321,
"md" : {
"customMD1": {
"type" : "string",
"value" : "AKAKA"
},
"customMD2": {
"type" : "integer",
"value" : "23232"
}
},
"mdNames": [ "customMD1", "customMD2" ]
},
"A2()ID101": {
"type": "TA2",
"value": "176",
"creDate" : 1389376244.6651231,
"modDate" : 1389376244.6651231
},
"position": {
"type": "location",
"value": "40.418889, -3.691944",
"creDate" : 1389376244.6651231,
"modDate" : 1389376244.6651231
}
},
"attrNames": [ "A1", "A2", "position" ],
"creDate": 1389376081.8471954,
"modDate": 1389376244.6651231,
"location": {
"attrName": "position",
"coords": {
"type": "Point",
"coordinates": [ -3.691944, 40.418889 ]
}
},
"lastCorrelator" : "aa01d6c6-4f7e-11e7-8059-000c29173617"
}
レジストレーション・コレクション
レジストレーション・コレクションは、レジストレーションに関する情報を格納します。コレクション内の各ドキュメントはレジストレーションに対応しています。
フィールド :
- _id : レジストレーション ID (レジストレーションを更新するためにユーザに提供される値) です。このために _id を使用すると、レジストレーション ID は一意であり、レジストレーション ID によるクエリは非常に高速になります (_id に自動のデフォルト・インデックスがあるため)
- format: 転送されたリクエストを送信するために使用するフォーマット
NGSIv1 フォーマットの場合、
formatの値として JSONを使用してください NGSIv2 では、今日現在、normalized フォーマットのみがサポートされています - servicePath : サービスパス機能に関連します
- status (オプション) :
active(アクティブなサブスクリプションの場合) またはinactive(非アクティブなサブスクリプションの場合)。デフォルト・ステータス (すなわち、ドキュメントがこのフィールドを省略した場合) は "active" です - statusLastChange: ステータスが最後に更新された時刻 (10進数、秒と秒の端数を意味します)。 これは主にサブスクリプション・キャッシュ更新ロジックによって使用されます (したがって、DB のステータスは、新しい場合にのみキャッシュから更新されます)
- description (オプションフィールド) : サブスクリプションを説明するフリーテキスト文字列。最大長は1024です
- timeout このフィールドは、サブスクリプションが http 通知のレスポンスを待機する最大時間を設定します。0から1800000までの数値です。0に設定するか省略した場合、デフォルトのタイムアウトが使用されます
- expiration : これはレジストレーションが失効するタイムスタンプです (整数、秒を意味します)
- fwdMode: プロバイダがサポートするフォワーディング・モード :
all,query,updateまたはnone. 省略した場合 (2.6.0 より前の Orion バージョン)、allが想定されます。 - contextRegistration : 要素に以下の情報が含まれる配列です :
- entities : エンティティのリストを含む配列です (必須)。各エンティティの JSON には、id, type および isPattern が含まれています
- attrs : 属性のリストを含む配列です (オプション)。各属性の JSON には、name および type が含まれています
- providingApplication : このレジストレーションのための提供アプリケーションの URL です (必須)
サンプルドキュメント :
{
"_id": ObjectId("5149f60cf0075f2fabca43da"),
"format": "JSON",
"fwdMode": "all",
"expiration": 1360232760,
"contextRegistration": [
{
"entities": [
{
"id": "E1",
"type": "T1",
"isPattern": "false"
},
{
"id": "E2",
"type": "T2",
"isPattern": "false"
}
],
"attrs": [
{
"name": "A1",
"type": "TA1"
},
{
"name": "A2",
"type": "TA2"
}
],
"providingApplication": "http://foo.bar/notif"
},
"status": "active"
]
}
csubs コレクション
csubs コレクションは コンテキストのサブスクリプションに関する情報を格納します。コレクション内の各ドキュメントはサブスクリプションに対応しています。
フィールド :
- _id : サブスクリプション ID (サブスクリプションを更新およびキャンセルするためにユーザに提供される値) です。このために _id を使用すると、サブスクリプション ID は一意であり、サブスクリプション ID によるクエリは非常に高速です (_id に自動のデフォルト・インデックスがあるため)
- servicePath : サービスパス機能に関連します。これは、サブスクリプションによってカプセル化されたクエリに関連付けられたサービスパスです。デフォルトは
/#です - expiration : サブスクリプションの有効期限が切れるタイムスタンプです (整数、秒を意味します)。永続的なサブスクリプションの場合、不当に高い値が使用されます。ソースコードの PERMANENT_SUBS_DATETIME を参照してください
- lastNotification : 最後の通知が送信された時刻です (整数、秒を意味します)。これは、通知が送信されるたびに更新され、スロットリング違反を回避します
- throttling : 通知の最小間隔です。0または -1 は、スロットリングがないことを意味します
- reference : 通知の URL です。HTTPまたはMQTTのいずれかを指定します
- mqttTopic: MQTTトピック (MQTT 通知のみ)
- mqttQoS: MQTT QoS 値 (MQTT 通知のみ)
- entities : エンティティの配列 (必須) です。各エンティティの JSON には、id, type, isPattern および isTypePattern が含まれています。従来の理由から、isPattern は
"true"または"false"(テキスト) で、isTypePattern はtrueまたはfalse(ブール値) であることに注意してください - attrs : 属性名の配列 (文字列) (オプション) です
- blacklist :
attrsをホワイトリスト (もしblacklistがfalseまた存在しない場合) またはブラックリスト (もしblackslistがtrueの場合) として解釈する必要があるかどうかを指定するブール値フィールドです - onlyChanged: 変更された属性のみを通知に含める必要があるか (onlyChanged が true の場合)、または含まないか (onlyChanged が false の場合) を指定するブール値フィールド
- metadata : メタデータ名 (文字列) の配列 (オプション) です
- conditions : 通知をトリガーする属性のリストです。
- expression : 更新が来たときに通知を送信するかどうかを評価するために使用される式です。 次のフィールドで構成されています : q, mq, georel, geometry and/or coords (オプション)
- count : サブスクリプションに関連付けられて送信された通知の数です
- format : 通知を送信するために使用する形式。可能な値はは JSON (NGSIv1 レガシー形式の JSON 通知を意味する)、normalized, keyValues, simplifiedNormalized, simplifiedKeyValues, values (最後の5つは NGSIv2 形式で使用されます) です
- status :
active(アクティブなサブスクリプションの場合) またはinactive(非アクティブなサブスクリプションの場合)、 またはoneshot(oneshot サブスクリプション の場合) のいずれか。Orion API は追加の状態 (expiredなど) を考慮しますが、DB にヒットすることはありません (Orion によって管理されます) - description (オプションフィールド) : サブスクリプションを説明するフリーテキスト文字列。最大長は1024です
- custom : このサブスクリプションがカスタマイズされた通知 (Orion API の機能) を使用するかどうかを指定するブール値フィールドです。このフィールドが存在し、その値が "true" であれば、カスタマイズされた通知が使用されていて、
headers,qs,methodおよびpayloadフィールドは考慮されています - headers : 通知カスタマイズ機能の HTTP ヘッダーキーマップを格納するためのオプションのフィールドです
- qs : 通知カスタマイズ機能のためのクエリパラメータのキーマップを格納するオプションのフィールドです
- method : 通知カスタマイズ機能の HTTP メソッドを格納するためのオプションのフィールドです
- payload : 通知カスタマイズ機能のペイロードを格納するオプションのフィールドです
その値が
nullの場合、ペイロードを通知に含める必要がないことを意味します。その値が""の場合、 またはフィールドが省略されている場合は、NGSIv2 正規化形式が使用されます - json : Orion API の通知カスタマイズ機能用に生成された JSON ベースのペイロードに JSON オブジェクトまたは配列を格納するためのオプションのフィールド。この機能の詳細は、こちらです
- ngsi: Orion API の通知カスタマイズ機能用の NGSI パッチ・オブジェクトを格納するためのオプション・フィールド。
この機能の詳細はこちらです。このフィールドの値は、値が
エンティティ・ コレクション の
attrsの簡略化されたバージョンであるattrsキーを持つオブジェクトです - lastFailure : 最後の通知の失敗が発生した時刻です (整数、秒を意味します)。サブスクリプションが失敗したことがない場合は存在しません
- lastFailureReason: 最後の失敗の原因を説明するテキストです。 サブスクリプションが一度も失敗したことがない場合は存在しません。
- lastSuccess : 最後に成功した通知が発生した時刻です (整数、秒を意味します)。サブスクリプションが通知をうまく引き起こさなかった場合は存在しません
- lastSuccessCode: 最後に正常な通知が送信されたときに受信エンドポイントから返された HTTP コード (200, 400, 404, 500 など)。 サブスクリプションが成功した通知を一度も引き起こした ことがない場合は存在しません
- maxFailsLimit: 接続試行の最大制限を指定するために使用されるオプションのフィールド。これにより、失敗した通知の数に達すると、サブスクリプションは自動的に非アクティブ状態に移行します
- failsCounter: サブスクリプションに関連付けられた連続して失敗した通知の数。これは、通知の試行が失敗するたびに1つずつ増加します。通知の試行が成功すると、0にリセットされます
- altTypes: サブスクリプションに関連付けられた変更タイプ (alteration types) のリストを含む配列。フィールドが含まれていない場合は、デフォルトが想定されます (このドキュメントを確認してください)
- covered: すべての
attrsを通知に含める必要があるか (値がtrueの場合)、トリガー・エンティティに存在するものだけを含める必要があるか (値がfalseの場合、またはフィールドが省略されている場合) を指定するブール・フィールド 詳細については、Orion API 仕様の対象サブスクリプション・セクション を参照してください。 - notifyOnMetadataChange:
trueの場合、メタデータはサブスクリプションのトリガーに関する属性の値の一部と見なされます。falseの場合、メタデータはサブスクリプションのトリガーに関する属性の値の一部と見なされません。 デフォルトの動作 (省略された場合) はtrueの動作です。
サンプルドキュメント :
{
"_id" : ObjectId("5697d4d123acbf5e794ab031"),
"expiration" : NumberLong(1459864800),
"reference" : "http://localhost:1234",
"servicePath" : "/",
"entities" : [
{
"id" : ".*",
"type" : "Room",
"isPattern" : "true",
"isTypePattern": false
}
],
"attrs" : [
"humidity",
"temperature"
],
"conditions" : [ "temperature" ],
"expression" : {
"q" : "temperature>40",
"mq" : "temperature.accuracy<1",
"geometry" : "",
"coords" : "",
"georel" : ""
},
"format" : "JSON",
"description": "this is an example subscription",
"status" : "active",
"statusLastChange" : 1637226173.6940024
}