- 禁止されている文字
- 通知のカスタムペイロードデコード
- カスタム通知を無効にするオプション
- カスタム通知の変更不可能なヘッダ
- エンティティ・ロケーションの属性に制限
geo:json属性でサポートされる GeoJSON タイプ- 通知の従来の属性フォーマット
- 日時サポート
- ユーザ属性または組み込み名前と一致するメタデータ
- サブスクリプション・ペイロードの検証
actionTypeメタデータnoAttrDetailオプション- 通知スロットリング
- 異なる属性型間の順序付け
- 初期通知
- Oneshot サブスクリプション
- 変更された属性のみを通知
lastFailureReasonおよびlastSuccessCodeのサブスクリプション・フィールドflowControlオプションforcedUpdateオプション- レジストレーション
POST /v2/op/notifyでサポートされないkeyValues- 廃止予定の機能
このドキュメントでは、Orion Context Broker が NGSI v2 仕様で行った具体的な実装について考慮する必要があるいくつかの考慮事項について説明します。
NGSIv2 仕様の "フィールド構文の制限" セクションから :
上記のルールに加えて、NGSIv2 サーバの実装では、クロス・スクリプト注入攻撃を避けるために、それらのフィールドまたは他のフィールドに構文上の制限を追加することができます。
Orion に適用される追加の制限事項は、マニュアルの 禁止されている文字のセクションに記載されているものです。
属性値で禁止文字のチェックをスキップするために、"TextUnrestricted" 属性タイプ (および NGSIv2 仕様で定義されているもの以外の特別な属性タイプ) を使用できることに注意してください。 ただし、セキュリティ上の問題 (スクリプト・インジェクション攻撃の可能性) がある可能性がある ため、自己責任で使用してください!
禁止された文字の制限のために、Orion は発信カスタム通知に追加のデコード・ステップを適用します。これについては、このマニュアルの このセクションで詳しく説明します。
Orion は、-disableCustomNotifications CLI パラメータを使用してカスタム通知を無効にするように設定できます。
この場合 :
httpCustomがhttpとして解釈されます。すなわち、urlを除くすべてのサブフィールドは無視されます。- マクロ置換
${...}は実行されません。
カスタム・通知で次のヘッダを上書きすることはできません :
Fiware-CorrelatorNgsiv2-AttrsFormat
そのような試み (例えば "httpCustom": { ... "headers": {"Fiware-Correlator": "foo"} ...}) は無視されます。
NGSIv2 仕様の "エンティティの地理空間プロパティ" のセクションから :
クライアントアプリケーションは、(適切な NGSI アトリビュート型を提供することによって) ジオスペース・プロパティを伝えるエンティティ属性を定義する責任があります。通常これは
locationという名前のついたエンティティ属性ですが、エンティティに複数の地理空間属性が含まれているユース・ケースはありません。たとえば、異なる粒度レベルで指定された場所、または異なる精度で異なる場所の方法によって提供された場所です。それにもかかわらず、空間特性には、バックエンド・データベースによって課せられたリソースの制約下にある特別なインデックスが必要であることは注目に値します。したがって、実装では、空間インデックスの制限を超えるとエラーが発生する可能性があります。これらの状況で推奨される HTTP ステータス・コードは413です。リクエスト・エンティティが大きすぎます。また、レスポンス・ペイロードで報告されたエラーは、NoResourcesAvailableである必要があります。
Orion の場合、その制限は1つの属性です。
NGSIv2 仕様では、geo:json 属性に使用される可能性のある GeoJSON タイプに制限を設定していません。
ただし、現在の Orion の実装 (MongoDB の機能に基づく) にはいくつかの制限があります。
次のタイプのテストに成功しました :
- Point
- MultiPoint
- LineString
- MultiLineString
- Polygon
- MultiPolygon
その一方で、次のタイプは機能しません (使用しようとすると "Database Error" が発生します) :
- Feature
- GeometryCollection
- FeatureCollection
実施されたテストの詳細については、 こちらをご覧ください。
NGSIv2 仕様の attrsFormat で述べている値とは別に、Orion は、NGSIv1 形式の通知を送信するために、legacy 値もサポートしています。このようにして、ユーザは NGSIv1 レガシー通知レシーバを使用した NGSIv2 サブスクリプション (フィルタリングなど) の拡張の恩恵を受けることができます。
NGSIv1 は非推奨であることに注意してください。したがって、legacy 通知形式をもう使用しないことを推奨します。
NGSIv2 仕様の "Special Attribute Types" セクションから :
DateTime : 日付を ISO8601 形式で識別します。これらの属性は、より大きい、より小さい、より大きい、等しい、より小さい、等しいおよび範囲のクエリ演算子で使用できます。
次の考慮事項は、属性の作成/更新時間または q と mq フィルタで使用される時に考慮しなければならない :
- Datetimes は、date, time, timezone の指定子で構成され、次のいずれかのパターンで表されます :
<date><date>T<time><date>T<time><timezone>- フォーマット
<date><timezone>は許可されていないことに注意してください。ISO8601 によると : "タイムゾーン指定子が必要な場合、それは結合された日付と時刻に従います"
<date>ついては、それがパターンに従わなければならない :YYYY-MM-DDYYYY: year (4桁)MM: month (2桁)DD: day (2桁)
- これについて
<time>は、ISO8601 仕様に記述されているパターンのいずれかに従わなければならない :hh:mm:ss.sssまたはhhmmss.sss。現時点では、Orion は内部的には.00として保存されますが、マイクロ秒 (またはより小さい解像度) を含む時間を処理することができます。ただし、これは将来変更される可能性があります (関連する問題を参照)hh:mm:ssまたはhhmmssです- ``hh:mm
またはhhmm`。この場合、秒は `00` に設定されます hh。この場合、分と秒は00に設定されます- もし
<time>省略された場合、時、分、秒が00に設定されます
<timezones>については、ISO8601 仕様に記述されているパターンのいずれかに従わなければならない :Z±hh:mm±hhmm±hh
- ISO8601 は、" 時間表現で UTC 関係情報が与えられていない場合、その時間は現地時間であると想定される " と規定している。ただし、クライアントとサーバが異なるゾーンにある場合、これはあいまいです。したがって、この曖昧さを解決するために、時間帯指定子が省略されている場合、Orion は常にタイムゾーン
Zを想定します
Orion は常にフォーマット YYYY-MM-DDThh:mm:ss.ssZ を使用して日時属性/メタデータを提供します。クライアント/レシーバが任意のタイムゾーンで実行されている可能性があるため、UTC/Zulu タイムゾーンを使用していることに注意してください。これは将来変更される可能性があります (関連する問題を参照)。
属性とメタデータの型としての文字列 "ISO8601" もサポートされています。この効果は、"DateTime" を使用した場合と同じです。
(このセクションの内容は、dateExpires 属性を除くすべての組み込み関数に適用されます。dateExpires に関する特定の情報については、一時的なエンティティのドキュメントを参照してください)。
まず、NGSIv2 組み込み属性やメタデータと同じ名前のものを使用しないことを強く推奨します。実際、NGSIv2 仕様では、これを禁止しています。仕様の "属性名の制限" と "メタデータ名の制限" のセクションを参照してください。
しかし、もし、あなたがそのような属性やメタデータを (おそらくレガシーの理由により) 持っていたとしても、以下の点を考慮に入れてください :
- NGSIv2 組み込みの属性および/またはメタデータと同じ名前のものを作成/更新することができます。Orion は、そうするでしょう
- ユーザ定義の属性および/またはメタデータは、GET リクエストまたはサブスクリプションで明示的に宣言する必要なく表示されます。 たとえば、エンティティ E1 に値 "2050-01-01" を持つ、
dateModified属性を作成した場合、GET /v2/entities/E1がそれを取得します。?attrs=dateModifiedを使う必要はありません。 - (GET オペレーションまたは通知にレスポンスして) レンダリングされると、明示的に宣言されていても、ユーザ定義の属性/メタデータが組み込み関数より優先されます。たとえば、エンティティ E1 に値 "2050-01-01" を持つ
dateModified属性を作成し、GET /v2/entities?attrs=dateModifiedをリクエストすると、"2050-01-01" が得られます。 - しかし、フィルタリング (すなわち
qまたはmq) は組み込み関数の値に基づいています。 たとえば、エンティティ E1 に値 "2050-01-01" を持つdateModified属性を作成し、GET /v2/entities?q=dateModified>2049-12-31をリクエストした場合、エンティティは取得されません。"2050-01-01" は "2049-12-31" よりも大きいですが、エンティティを変更した日付 (2018年か2019年のいずれかの日付) は "2049-12-31" より大きくなりません。これは何らかの形で矛盾していることに注意してください (つまり、ユーザ定義はレンダリングでは優先されますがフィルタリングでは優先されません)、将来変更される可能性があります。
Orion が NGSIv2 サブスクリプション・ペイロードで実装する特定の検証は、次のとおりです :
- description: オプション (最大長1024)
- subject: 必須
- entities: 必須
- id or idPattern: そのうちの1つは必須です (ただし、同時に両方は許可されません)。id は ID の NGSIv2 制限に従わなければなりません。idPattern は空ではなく、有効な正規表現でなければなりません
- type or typePattern: 任意です (ただし、両方同時に許可されません)。type は ID の NGSIv2 制限に従う必要があります。型は空であってはいけません。typePattern は有効な正規表現で、空ではない必要があります
- condition: オプション (但し、存在する場合は内容を持たなければなりません。つまり
{}は許可されていません)- attrs: オプション (ただし、存在する場合はリストでなければなりません。空リストも許されます)
- expression: オプション (ただし、存在する場合は内容を持たなければなりません。つまり {} は許可されていません)
- q: オプション (ただし、存在する場合は空でなければなりません。つまり
""は許可されていません) - mq: オプション (ただし、存在する場合は空でなければなりません。つまり
""は許可されていません) - georel: オプション (ただし、存在する場合は空でなければなりません。つまり
""は許可されていません) - geometry: オプション (ただし、存在する場合は空でなければなりません。つまり
""は許可されていません) - coords: オプション (ただし、存在する場合は空でなければなりません。つまり
""許可されていません)
- q: オプション (ただし、存在する場合は空でなければなりません。つまり
- entities: 必須
- notification:
- http:
httpCustomが省略された場合は存在しなければならず、そうでなければ禁止されています- url: 必須 (有効な URL である必要があります)
- httpCustom:
httpが省略されている場合は存在し、そうでない場合は禁止されていなければなりません- url: 必須 (空でなければなりません)
- headers: オプション (ただし、存在する場合はコンテンツが必要です。つまり
{}は許可されていません) - qs: オプション (ただし、存在する場合はコンテンツが必要です。つまり
{}は許可されていません) - method: オプション (存在する場合は有効な HTTP メソッドでなければなりません)
- payload: オプション (空の文字列を使用できます)
- attrs: オプション (ただし、存在する場合はリストでなければなりません。空リストも許可されます)
- metadata: オプション (ただし、存在する場合はリストでなければなりません。空リストも許可されます)
- exceptAttrs: オプションです (ただし、
attrsも使用されている場合は存在できません。存在する場合は空でないリストでなければなりません) - attrsFormat: オプション (存在する場合は有効な
attrs形式のキーワードでなければなりません)
- http:
- throttling: オプション (整数でなければなりません)
- expires: オプション (日付または空の文字列 "" でなければなりません)
- status: オプション (有効なステータス・キーワードである必要があります)
NGSIv2 仕様のセクション "組み込みメタデータ" から actionType メタデータ関連 :
その値はリクエストオペレーションの型によって異なります : 更新のための
update, 作成のためのappend, 削除のためのdelete。その型は常に Text です。
現在の Orion の実装では、"update (更新)" と "append (追加)" がサポートされています。この問題が完了すると、"delete (削除)" のケースがサポートされます。
URI param options の値 noAttrDetail は、NGSIv2 型のブラウジング・クエリ (GET /v2/types および GET /v2/types/<type>) が、属性型の詳細を提供しないようにするために使用されます。使用すると、各属性名に関連付けられた types リストが [] に設定されます。
このオプションを使用すると、Orion はこれらのクエリをはるかに迅速に解決します。特に、それぞれが異なる型の多数の属性の場合は、これは、ユース・ケースに属性型の詳細が必要ない場合に非常に便利です。場合によっては、noAttrDetails オプションで30秒から 0.5 秒の節約が検出されました。
サブスクリプション・スロットリングに関する NGSIv2 仕様から :
throttling : 2つの連続した通知の間に経過する必要のある秒単位の最小限の時間。オプションです。
Orion がこれを実装する方法は、保護期間のスロットル中に通知を破棄することです。したがって、あまりにも近づいてしまえば、通知が失われる可能性があります。ユース・ケースがこのように通知を失うことをサポートしていない場合は、スロットリングを使用しないでください。
さらに、Orion はローカルでスロットリングを実装します。multi-CB 構成では、最終通知の尺度が各 Orion ノードに対してローカルであることを考慮してください。各ノードは DB と定期的に同期してより新しい値を取得しますが (ここではこれ以上)、特定のノードに古い値があることがありますので、スロットリングは100％正確ではありません。
NGISv2 仕様 "Ordering Results" セクションから :
エンティティのリストを取得するオペレーションでは、順序付けの結果を得る際に条件として使用される属性またはプロパティを
orderByURI パラメータで指定できます
これは、各型が他の型に関してどのように順序づけられるかの実装アスペクトです。Orion の場合、基本的な実装(MongoDB)で使用されているものと同じ基準を使用します。詳細については、次のリンクを参照してください。
最低から最高まで :
- Null
- Number
- String
- Object
- Array
- Boolean
NGSIv2 仕様では、サブスクリプションの対象となるエンティティの更新に基づいて、特定のサブスクリプションに対応する通知をトリガするルールを "サブスクリプション" セクションで説明しています。そのような定期的な通知以外にも、Orion は、また、サブスクリプションの作成/更新時時に初期通知を送信することがあります。
初期通知は、新しい URI パラメータオプション skipInitialNotification
を使用して設定できます。
例えば、POST /v2/subscriptions?options=skipInitialNotification または、
PATCH /v2/subscriptions/{subId}?options=skipInitialNotification です。
初期通知 について、ドキュメントで詳細を 確認してください。
Orionは、NGSIv2 仕様のサブスクリプション用に定義された status 値の他に、
oneshotを使用することもできます。
Oneshot サブスクリプションのドキュメントで詳細を確認してください
Orion は、NGSIv2 仕様で説明されているものとは別に、サブスクリプションの中で追加のフィールド onlyChangedAttrs
(notification 内に) をサポートしています。 このフィールドは true または false の値を取ります
(フィールドが省略された場合、デフォルトは false です)。 true に設定されている場合、サブスクリプションに
関連した通知は attrs または exceptAttrs フィールドと組み合わせて、トリガーしている更新リクエストで
変更された属性のみを含みます。
例えば、attrs が [A、B、C] のデフォルトの振る舞い (onlyChangedAttrs が false の場合) とトリガー更新が
A のみを修正した場合、A, B, C が通知されます(つまり、トリガー更新は関係ありません)。 しかし、onlyChangedAttrs
が true でトリガー更新が A のみを修正した場合、通知には A のみが含まれます。
GET /v2/subscriptions および GET /v2/subscriptions/subId リクエストの
NGSIv2 仕様で説明されているサブスクリプション・フィールドとは別に、
Orion は通知フィールド内でこの2つの追加フィールドをサポートしています :
lastFailureReason: 最後の失敗の原因を記述するテキスト文字列 (すなわち、失敗がlastFailureの時点で発生した)lastSuccessCode: 最後に成功した通知が送信されたときに 受信エンドポイントによって返された HTTP コード (200, 400, 404, 500 など) (つまり、成功がlastSuccessの時点で発生した)
どちらも通知に関する問題の分析に使用できます。 詳しくは、 問題診断ドキュメント のセクションを参照してください。
これにより、更新操作でフロー制御を使用する必要があることを指定できます。これにより、パフォーマンスが
向上し、高負荷シナリオでの飽和を回避できます。これは、-notifFlowControl パラメータ
を使用して ContextBroker が開始されている場合にのみ機能し、そうでない場合は無視されます。
フロー制御メカニズムは、ドキュメントのこのセクション
で説明しています。
次のリクエストでは、flowControl URI param オプションを使用できます :
POST /v2/entities/E/attrs?options=flowControlPOST /v2/entities/E/attrs?options=append,flowControlPOST /v2/op/update?options=flowControlPUT /v2/entities/E/attrs?options=flowControlPUT /v2/entities/E/attrs/A?options=flowControlPUT /v2/entities/E/attrs/A/value?options=flowControlPATCH /v2/entities/E/attrs?options=flowControl
NGSIv2 仕様に含まれるものに対する追加の URI パラメータ・オプションとして、Orion は forcedUpdate を実装します。実際の属性の更新があってもなくても、更新オペレーションが一致するサブスクリプションを トリガして、対応する通知を送信する必要があることを指定するために使用できます。デフォルトの動作 (つまり、forcedUpdate URI param オプションを使用しない場合) は、属性が実際に更新された場合にのみ 更新されることに注意してください。
次のリクエストでは、forcedUpdate URI param オプションを使用できます :
POST /v2/entities/E/attrs?options=forcedUpdatePOST /v2/entities/E/attrs?options=append,forcedUpdatePOST /v2/op/update?options=forcedUpdatePUT /v2/entities/E/attrs?options=forcedUpdatePUT /v2/entities/E/attrs/A?options=forcedUpdatePUT /v2/entities/E/attrs/A/value?options=forcedUpdatePATCH /v2/entities/E/attrs?options=forcedUpdate
Orion は、次の点を除いて、NGSIv2 仕様に記載されているレジストレーション管理を実装しています。
PATCH /v2/registration/<id>は実装されていません。したがって、レジストレーションを直接更新することはできません。つまり、レジストレーションを削除して再作成する必要があります。この issueについてはこちらをご覧くださいidPatternはサポートされていますtypePatternは実装されていません- 唯一の有効な
supportedForwardingModeはallです。他の値を使用しようとすると、501 Not Implemented エラー応答で終了します。この issue についてはこちらをご覧ください dataProvided内でのexpressionフィールドはサポートされていません。フィールドは単に無視されます。これについては この issue を見てください。statusでのinactive値はサポートされていません。つまり、フィールドは正しく格納され/取得されますが、値がinactiveの場合でもレジストレーションは常にアクティブです。これについては、この issue を見てください
NGSIv2 仕様によると :
NGSIv2 サーバ実装は、コンテキスト情報ソースへのクエリまたは更新転送を実装することができます
Orion がこのような転送を実装する方法は次のとおりです :
POST /v2/op/queryクエリ転送のためPOST /v2/op/update更新転送のため
コンテキスト情報ソースへの転送に関するより多くの情報は、このドキュメントにあります。
Orion は NGSIv2 仕様に含まれていない追加フィールド (provider 内の) legacyForwardingを実装しています。legacyForwarding の値が true の場合、NGSIv1 ベースのクエリ/更新はそのレジストレーションに関連したリクエストを転送するために使用されます。NGSIv1 は廃止予定ですが、一部のコンテキスト・プロバイダはまだ NGSIv2 に移行されていない可能性があるため、このモードは便利です。
現在の Orion の実装は、POST /v2/op/notify オペレーションの keyValues オプションをサポートしていません。それを使用しようとすると、400 Bad Request エラーが発生します。
安定版の NGSIv2 仕様の変更を最小限に抑えようとしていますが、最後にいくつかの変更が必要でした。したがって、現在の NGSIv2 stable 仕様には現れない機能が変更されていますが、Orion は後方互換性を維持するために(非推奨の機能として)サポートしています。
特に、options のパラメータ内の dateCreated 及び dateModified の使用はまだサポートされています (安定した RC-2016.05 で導入され、RC-2016.10 で除去されました)。例えば options=dateModified です。ただし、代わりに attrs の使用することを強くお勧めします (すなわち attrs=dateModified,*)。