Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

NGSIv1 を知っている開発者向けの NGSIv2 の概要 (Orion 2.0.0対応)

128 views

Published on

FIWARE NGSIv1 を知っている開発者向けのNGSIv2 の概要を解説したスライドです。2018年9月28日にリリースされた、Orion Context Broker version 2.0.0に対応しています。

Published in: Software
  • Be the first to comment

  • Be the first to like this

NGSIv1 を知っている開発者向けの NGSIv2 の概要 (Orion 2.0.0対応)

  1. 1. Contact twitter @fermingalan Contact email fermin.galanmarquez@telefonica.com (Reference Orion Context Broker version: 2.0.0 – Reference NGSIv2 version: 2.0) NGSIv1 を知っている開発者向けの NGSIv2 の概要 (NGSIv2 Overview for Developers That Already Know NGSIv1) (Translated into Japanese by Kazuhito Suda k@fisuda.jp)
  2. 2. • NGSIv2 入門 • RESTful-ness • URL とペイロードの簡略化 • ネイティブなJSONデータ型 • テキストベースの属性値の set/get • ジオロケーション機能 • Datetime サポート • 一時的なエンティティ • フィルタリング • サブスクリプションの改善 • バッチ操作 • IDs の操作 • ページネーション • 今後の予定 2 Outline
  3. 3. NGSI API の2つの“フレイバー” • NGSIv1 (あなたがすでに知っているもの ) – OMA-NGSI のオリジナルの NGSI RESTful バインディング – 2013 年に実装 – リソース URL に /v1 プレフィックスを使用 – 推奨されていないため、サポートは最終的に削除されます。NGSIv1 の使用を、ぜひとも思いとど まってください。 • NGSIv2 – 改良され単純化された OMA-NGSI のバインディング • 単純なことが容易にできる • 複雑なことができる • アジャイル、実装主導型のアプローチ • デベロッパー・フレンドリー (RESTful, JSON, …) – NGSIv1と比較して強化された機能 (例. フィルタリング) – 安定, プロダクション・レディ、すでに利用できるバージョン • 現在の NGSIv2 バージョンは、Release Candidate 2018.07 です。 http://telefonicaid.github.io/fiware-orion/api/v2/stable • 今後の新機能 (このプレゼンテーションの最後の部分を参照してください) – リソース URL に /v2 プレフィックスを使用 • NGSIv2 入門 – https://docs.google.com/presentation/d/1_fv9dB5joCsOCHlb4Ld6A- QmeIYhDzHgFHUWreGmvKU/edit#slide=id.g53c31d7074fd7bc7_0 3
  4. 4. NGSI モデルは、NGSIv2 でも保持されます Attributes • Name • Type • Value Entity • EntityId • EntityType 1 n “has” Metadata • Name • Type • Value1 n “has” 4
  5. 5. RESTful-ness • NGSIv1 では – もともと OMA-NGSI の標準操作に基づいていましたが、実際は RESTful ではありません • URLはリソースを識別するのではなく、操作の種類です • 動詞は常に POST です • 実際、NGSIv1 は RESTful よりも HTTP ベースの RPC に近い – 後の段階で拡張された一連の操作(コンビニエンス操作)が追加されました が、RESTful な完全な原則を適用するのが難しい標準操作の”レガシー”が 追加されました • 例えば。 二重応答コード • NGSIv2 は RESTful な原則を念頭において設計されています – バッチ操作 (NGSIv1の標準操作に類似) も提供しますが、API の RESTful 操作には影響しません 5
  6. 6. RESTful-ness 6 200 OK ... { "contextElement" : { "type" : "", "isPattern" : "false", "id" : "Car1" }, "statusCode" : { "code" : "404", "reasonPhrase" : "No context element found", "details" : "Entity id: /Car1/" } } GET /v1/contextEntities/Car1 404 Not Found ... { "error": "NotFound", "description": "The requested entity has not been found. Check type and id“ } GET /v2/entities/Car1 NGSIv1 NGSIv2 エラー状態を検出するためにクライアントが 両方のステータス・コードを考慮する必要があり、 複雑さが増します RESTful な原則に従い、HTTP レスポ ンス・コードのみで、処理が簡単です 例: Car1 エンティティを取得
  7. 7. URL とペイロードの簡略化 • NGSIv1 では、OMA NGSI との厳密な整合には複雑さと非効率性が 伴います – メッセージのペイロードには、実際には必要ない構造上のオーバーヘッド要素が多数 含まれています – 意味論的観点から実際にペイロードを必要としないメソッドのレスポンス・ペイロード。 (例: 更新操作) – URLs 内の不必要に長い構造要素 • NGSIv2 は URLs とペイロードを単純化し、よりリーンで冗長性の低い API です 7
  8. 8. URL とペイロードの簡略化 8 POST /v1/contextEntities ... { "id": "Car1", "type": "Car", "attributes": [ { "name": "colour", "type": "Text", "value": "red" } ] } 200 OK Location: /v2/entities?type=Car POST /v2/entities … { "id": "Car1", "type": "Car", "colour": { "value": "red", "type": "Text", } } NGSIv1 NGSIv2 NGSIv1 のレスポンス・ペイロードのほと んどは役に立たず、クライアントはステー タス・コードを知る必要があります。 NGSIv2 ではレスポンスにペイロードが 全くありません。 NGSIv2の 短いURLs 200 OK ... { "contextResponses": [ { "attributes": [ { "name": "colour", "type": "float", "value": "" } ], "statusCode": { "code": "200", "reasonPhrase": "OK" } } ], "id": "Car1", "isPattern": "false", "type": “Car" } 構造上の オーバーヘッド 例: 属性“Colour” を “Red” に 設定した Car1 エンティティ (タイプ Car)を作成します
  9. 9. URL とペイロードの簡略化 9 GET /v1/contextEntities/type/Car/id/Car1/attributes/colour GET /v2/entities/Car1/attrs/colour?type=Car NGSIv1 NGSIv2 冗長 (すでにリクエスト URL の一部) 200 OK ... { "attributes": [ { "name": "colour", "type": "Text", "value": " red" } ], "statusCode": { "code": "200", "reasonPhrase": "OK" } } ほとんど役に立たない 200 OK ... { "value": "red", "type": "Text", "metadata": {} } NGSIv2の 短いURLs 構造上の オーバーヘッド 例: Car1 エンティティ (Car タイプ) の 属性 “colour” を取得します
  10. 10. URL とペイロードの簡略化 • さらに、NGSIv2 は単純化されたデータ表現 – keyValues: 属性タイプとメタデータを除外 – values: 属性値のみ (attrs は、結果のベクトルの値を順序付けるために使用) – unique: 重複した値を削除する類似の値 • 取得操作のためだけでなく、作成/更新操作のためにも – この場合、デフォルトの属性タイプが使用されます 10 GET /v2/entities/Car1/attrs?options=keyValues 200 OK ... { "model": "Ford", "colour": "red", "temp": 22 } GET /v2/entities/Car1/attrs?options=values&attrs=model,colour,temp 200 OK ... ["Ford", "red", 22] 例: Car1 エンティティ (Car タイプ) の属性” colour” を取得します
  11. 11. ネイティブな JSON データ型 • NGSIv1では – すべての属性値は、XML エンコーディングに合わせて文字列ベースです • 結局のところ、XML サポートは、Orion 1.0.0では削除されましたが、ひどい遺 産を残しました。  – 作成/更新操作では、最後に数字、ブールなどを使用できますが、文字列に 変換され、内部的に格納されます (*) – 取得操作は常に文字列でエンコードされた値を提供します (**) • NGSIv2 は、JSON 仕様に記述されているすべてのタイプを完全にサ ポートしています (string, number, boolean, object, array と null) 11 (*) 一部の型で、NGSIv1オートキャスト機能が使用される場合を除きます (https://fiware- orion.readthedocs.io/en/master/user/ngsiv1autocast/index.html を参照ください) (**) 例外: NGSIv2で作成/更新されエンティティをNGSIv1で取得すると、文字列化されずにレンダリ ングされます。
  12. 12. ネイティブな JSON データ型 1212 POST /v1/contextEntities ... { "id": "Car1", "type": "Car", "attributes": [ { "name": "speed", "type": "Number", "value": 98 } ] } POST /v2/entities?options=keyValues … { "id": "Car1", "type": "Car", "speed": 98, "isActive": true } NGSIv1 NGSIv2 数字として作成さ れましたが、文字 列として取り出さ れました! GET /v1/contextEntities/Car1/attributes/speed ... { "attributes": [ { "name": "speed", "type": "Number", "value": "98" } ], "statusCode": { … } } GET /v2/entities/Car1/attrs?options=keyValues … { "speed": 98, "isActive": true } 一貫した結果 例: 属性”speed”を98に設定 して Car1 エンティティ (Car タイプ)を作成します
  13. 13. テキストベースの属性値の set/get • NGSIv1では – 同様の機能はありません • NGSIv2は、リクエスト/レスポンスのペイロード内の属性値そのもの以 外に何もせずに直接属性の set/get を提供します。 – set 操作では、属性の型とメタデータはそのまま保持されます 13 PUT /v2/entities/Car1/attrs/speed/value Content-Type: text/plain … 86 GET /v2/entities/Car1/attrs/speed/value 200 OK Content-Type: text/plain … 86200 OK … 例: Car1 エンティティで speed 属性値を設定(set)します 例: Car1 エンティティで speed 属性値を取得(get)します
  14. 14. ジオ・ロケーション機能 • NGSIv1では – エンティティのロケーションは point でなければなりません – クエリは領域指定(円または多角形、内側または外側の領域)に基づいています。 – queryContext ペイロード・スコープの一部としてのクエリ • NGSIv2では – point に加えて,エンティティのロケーションは、line, box, polygon または 任意の GeoJSON にすることができます – クエリは空間的関係とジオメトリに基づいています • 空間的関係: near (最大距離と最小距離), coveredBy, intersect, equal と disjoint • ジオメトリ: point, line, box, polygon – URL の一部としてのクエリ (ペイロード・ベースのアプローチよりユーザ・フレンドリー) 14
  15. 15. ジオ・ロケーション機能 15 NGSIv1 NGSIv2 NGSIv2 ではずっと簡単でコンパクトです POST /v1/queryContext … { "entities": [ { "type": "City", "isPattern": "true", "id": ".*" } ], "restriction": { "scopes": [ { "type" : "FIWARE::Location", "value" : { "circle": { "centerLatitude": "40.418889", "centerLongitude": "-3.691944", "radius": "13500" } } } ] } } GET /v2/entities? idPattern=.*& type=City& georel=near;maxDistance:13500& geometry=point& coords=40.418889,-3.691944 例: マドリード市内中心部 (GPS座標 40.418889, -3691944) までの距離が 13.5km 未満の"City" (idに関係なく)" タイプのすべてのエンティティを取得しま す
  16. 16. ジオ・ロケーション機能 16 Point location (NGSIv1でサポートされている 唯一のロケーション) POST /v2/entities { "id": "E", "type": "T", "location": { "type": "geo:json", "value": { "type": "Polygon", "coordinates": [ [ [2, 1], [4, 3], [5, -1], [2, 1] ] ] } } } POST /v2/entities { "id": "E", "type": "T", "location": { "type": "geo:polygon", "value": [ "2, 2", "8, 7", "-1, 4", "2, 2"] } } POST /v2/entities { "id": "E", "type": "T", "location": { "type": "geo:box", "value": [ "2, 2", "8, 7" ] } } POST /v2/entities { "id": "E", "type": "T", "location": { "type": "geo:point", "value": "40.41,-3.69" } } POST /v2/entities { "id": "E", "type": "T", "location": { "type": "geo:line", "value": [ "2, 2", "8, 7" ] } } Line location (例: ストリート) Box location (例: 四角い建物) Polygon location (例: 市の地区) GeoJSON geometry (完全な柔軟性)
  17. 17. Datetime サポート • NGSIv1では – 日付を意味する属性はサポートされていません。従来の文字列とし て扱われます • NGSIv2は日付サポートを実装しています – ISO ISO8601フォーマット(部分表現とタイムゾーンを含む)に基づ いています • 構文の詳細については、 https://fiware- orion.readthedocs.io/en/master/user/ngsiv2_implementati on_notes/index.html#datetime-support を参照してください – 日時を表すには、予約属性タイプの DateTime を使用します – 日付ベースのフィルタをサポートしています 17
  18. 18. Datetime サポート • 属性値の算術フィルタは、日付が数字であるかのように使用できます • エンティティの dateModified と dateCreated の特殊属性,エンティティの 作成と最終変更のタイムスタンプを取得します – それらは以下を使用してクエリ・レスポンスで示されます attrs=dateModified,dateCreated • エンティティの dateModified と dateCreated の特殊メタデータ, 属性の 作成と最終変更のタイムスタンプを取得します – それらは以下を使用してクエリ・レスポンスで示されます metadata=dateModified,dateCreated 18 POST /v2/entities … { "id": "John", "birthDate": { "type": "DateTime", "value": "1979-10-14T07:21:24.238Z" } } GET /v2/entities?q=birthDate<1985-01-01T00:00:00 例: DateTime タイプを使用して birthDate 属性でエンティティ “John”を作成します
  19. 19. 一時的なエンティティ (Transient entities) • NGSIv1 では – 一時的なエンティティはサポートされていません • NGSIv2 は一時的なエンティティを実装しています – 特別な意味を持つ、作成/更新時に提供された DateTime 型の dateExpires 属 性 : その時間に達すると、エンティティは期限切れになります – “expires” とは、実装に依存することを意味します • Orion の場合、期限切れのエンティティは自動的に削除されます。詳細は Orion のドキュメントを参照してく ださい – dateExpires 属性にも日付ベースのフィルタがサポートされています 19
  20. 20. フィルタリング • NGSIv1 では – 制限されたフィルタリング機能、これは queryContext の複雑なスコープに基づいて います – サブスクリプションではフィルタがサポートされていません • NGSIv2では、メカニズムは、 – もっと簡単です (次のスライドをご覧ください) – クエリとサブスクリプションの両方に適用できます (このプレゼンテーションの後のトピックで説明します) 20 POST /v1/queryContext … { "restriction": { "scopes": [ { "type" : "FIWARE::StringFilter", "value" : "temp<24" … } This is the only interesting part, all the rest is structural overhead Example: filtering entities which temperature is less than 24
  21. 21. • GET /v2/entities 操作では、 …すべてのエンティティを取得します – ... 特定のエンティティ・タイプのエンティティ – ... エンティティ id は、リストの中です – ... エンティティ id が正規表現パターンと一致します • 例: id は “Room” で始まり、2から5までの数字が続きます – …指定された式に一致する属性を持つ、エンティティ • 例: 属性 temp が25より大きい • フィルタは同時に使用できます (例: AND 条件など) 21 GET /v2/entities?type=Room GET /v2/entities?id=Room1,Room2 GET /v2/entities?idPattern=^Room[2-5] フィルタリング GET /v2/entities?q=temp>25 サポートされる演算子: • == (or :), equal • !=, unequal • >, greater than • <, less than • >=, greater than or equal • <=, less than or equal • A..B, range • ^=, pattern (regex) • Existence/inexistence
  22. 22. • GET /v2/entities 操作では、 …すべてのエンティティを取得します – ...エンティのエンティティ・タイプは正規表現パターンと一致します – …サブキーが与えられた式に一致する属性を持つエンティ – …与えられた式にマッチする属性メタデータをもつエンティティ – …サブキーが与えられた式にマッチする属性メタデータを持つエンティティ 22 GET /v2/entities?q=tirePressure.frontRight >130 属性名 属性サブキー (複合属性値のみ) GET /v2/entities?mq=temperature.avg>25 GET /v2/entities?mq=tirePressure.accuracy.frontRight >90 メタデータ・サブキー (複合メタデータ値のみ) メタデータ名 フィルタリング GET /v2/entities?typePattern=T[ABC]
  23. 23. • デフォルトでは、すべての属性はクエリのレスポンスまたは 通知に含まれます • GET操作のパラメータとして、およびサブスクリプションの通 知サブフィールドとして、attrs フィールドを使用して、フィル タリング・リストを指定できます • attrs フィールドは、特別な属性を明示的に含むためにも使 用できます (デフォルトでは含まれていません) – dateCreated: エンティティ作成日 – dateModified: エンティティの最終変更日 – dateExpires: エンティティの有効期限 • "*"は、 "すべての通常の属性"の別名として使用できます 23 属性フィルタリングと特殊属性
  24. 24. • 例 – temp と lum だけの属性を含めます • クエリで: GET /v2/entities?attrs=temp,lum • サブスクリプションで: "attrs": [ "temp", "lum" ] – 他の属性ではなく dateCreated を含めます • クエリで: GET /v2/entities?attrs=dateCreated • サブスクリプションで: "attrs": [ "dateCreated" ] – dateModified とその他すべての(通常の)属性を含めます • クエリで: GET /v2/entities?attrs=dateModified,* • サブスクリプションで: "attrs": [ "dateModified", "*" ] – すべての属性を含めます(attrsを使用しないのと同じ効果です) • クエリで: GET /v2/entities?attrs=* • サブスクリプションで: "attrs": [ "*" ] 24 属性フィルタリングと特殊属性
  25. 25. • デフォルトでは、すべての属性メタデータはクエリのレスポンスと通知に 含まれています • GET操作のパラメータとして、および、サブスクリプションの通知サブ フィールドとして、metadata フィールドを使用して、フィルタリング・リス トを指定できます • metadata フィールドは、明示的には含まれていない特別なメタデータ を明示的に含むためにも使用できます – dateCreated, dateModified: 属性作成または最終更新日 – actionType: どの値が通知をトリガする更新に対応するアクション・タイプ であるか : update”, “append” または “delete” (*) – previousValue: 通知をトリガする更新を処理する前の属性値を提供し ます • “*”は、 “すべての通常のメタデータ"の別名として使用できます 25 メタデータのフィルタリングと特殊属性 (*) actionType "delete" は、まだ、Orion 2.0.0 でサポートされていません
  26. 26. メタデータのフィルタリングと特殊属性 • 例 – メタデータ MD1 と MD2 のみを含めます • クエリで: GET /v2/entities?metadata=MD1,MD2 • サブスクリプションで: "metadata": [ "MD1", "MD2" ] – previousValue を含み、他のメタデータは含みません • クエリで: GET /v2/entities?metadata=previousValue • サブスクリプションで: "attrs": [ "previousValue" ] – actionType とその他すべての通常のメタデータを含めます • クエリで: GET /v2/entities?metadata=actionType,* • サブスクリプションで: "attrs": [ "actionType", "*" ] – すべてのメタデータを含めます (メタデータを使用しない場合と同じ 効果です) • クエリで: GET /v2/entities?metadata=* • サブスクリプションで: "metadata": [ "*" ] 26
  27. 27. サブスクリプションの改善 • NGSIv1 コンテキスト・サブスクリプション API は非常に限られています – 既存のサブスクリプションを一覧表示する操作はありません • クライアントが作成されたサブスクリプションの ID を失った場合、API を使用してサブスクリ プションを取得する方法はありません – 永久サブスクリプションのサポートはありません • 不本意ながら長いサブスクリプション(100年など)を作成するのは、汚い回避策です – 通知構造の修正 • 任意のエンドポイント(例えば、公開 REST サービス) に統合するのが難しい – フィルタはサポートされていません • NGSIv2 サブスクリプション API はこれらの制限をすべて解決し、いく つかの追加機能を導入しています – “ブラックリスト”に基づく通知属性 (NGSIv1 の”ホワイトリスト”アプローチに加えて) – サブスクリプションの一時停止/再開機能 – 追加フィールド:送信された時間、最後の通知および説明 27
  28. 28. NGSIv2 サブスクリプションの解剖 28 POST /v2/subscriptions … { "subject": { "entities": [ { "id": "Room1", "type": "Room" } ] }, "condition": { "attrs": [ "temp" ] }, "notification": { "http": { "url": "http://<host>:<port>/publish" }, "attrs": [ "temp" ] }, "expires": "2026-04-05T14:00:00.00Z", "throttling": 5 } 201 Created Location: /v2/subscriptions/51c0ac9ed714fb3b37d7d5a8 ... POST /v1/subscribeContext … { "entities": [ { "type": "Room", "isPattern": "false", "id": "Room1" } ], "attributes": [ "temp“ ], "reference": "http://<host>:<port>/publish", "duration": "P1M", "notifyConditions": [ { "type": "ONCHANGE", "condValues": [ "temp" ] } ], "throttling": "PT5S" } 200 OK ... { "subscribeResponse": { "duration": "P1M", "subscriptionId": "51c0ac9ed714fb3b37d7d5a8", "throttling": "PT5S" } } NGSIv1 NGSIv2 より簡単なレスポンス (ペイロードなし) NGSIv2 で期限切れと制限 を指定する簡単な方法 冗長 例: Room1 エンティティに サブスクライブします。した がって、temp 属性で変更が 発生するたびに temp のみ を含む通知が送信されます
  29. 29. NGSIv2のサブスクリプションと特殊フィールドを一覧表示 • リスト操作 (NGSIv1では使用できません) – GET /v2/subscriptions は、すべてのサブスクリプションを一覧表示します – GET /v2/subscriptions/<id> は、特定のサブスクリプションの情報を取得し ます • ホワイトリストとブラックリスト (通知フィールド内) – “attrs”: [ “A”, “B” ] を “通知にAとBを含める” に使用 (ホワイトリスト) – “exceptAttrs”: [ “A”, “B” ] を “AおよびBを除くすべての属性を含める” に使 用 (ブラックリスト) – “attrs”: [ ] を “すべての属性” を含めるために使用 (特別なケース) • その他の情報フィールド (通知フィールド内) – timesSent: サブスクリプションがトリガーされ、通知が送信された回数 – lastNotification: 最後の通知に対応する datetime • その他の情報フィールド(ルートレベルで) – description: ユーザの便宜のためのフリーテキスト記述テキスト 29
  30. 30. NGSIv2の永続的および一時停止されたサブスクリプション • status 属性は、サブスクリプションの一時停止/再開に使用できます • GET操作では、 status フィールドは、 – active: サブスクリプションがアクティブです (通知が送信されます) – inactive:サブスクリプションはアクティブではありません (通知は送信され ません) – expired: サブスクリプションは期限切れです (通知は送信されません) – failed: 次のスライドで説明します 30 PATCH /v2/subscriptions/<id> … { "status": "active" } PATCH /v2/subscriptions/<id> … { "status": "inactive" } To pause To resume
  31. 31. • ステータス failed は、最後に通知が 失敗したことを意味します – 例: エンドポイントに到達できません • 通知要素(notifications element) の詳細情報 – timesSent: 通知の合計回数(成功と失敗 の両方) – lastSuccess: 通知が正常に送信された最 後の時刻 – lastFailure: 通知が試行され失敗した最 後の時刻 – lastNotification: 通知が送信された最後 の時刻 (成功または失敗のいずれか) • 結果として、lastNotification の値は lastFailure または lastSuccess と同じです 31 200 OK Content-Type: application/json … [{ "id": " 51c0ac9ed714fb3b37d7d5a8 ", "expires": "2026-04-05T14:00:00.00Z", "status": "failed", "subject": { … }, "notification": { "timesSent": 3, "lastNotification": "2016-05-31T11:19:32.00Z", "lastSuccess": "2016-05-31T10:07:32.00Z", "lastFailure": "2016-05-31T11:19:32.00Z", … } }] 通知ステータス
  32. 32. NGSIv2の通知フォーマット • オプションの attrsFormat フィールドを使用すると、表現モードに合わせて異なる通知フレーバを選 択できます • 通知には、受信者がフォーマットを識別するための NGSIv2-AttrsFormat ヘッダーが含まれます • legacy は、NGSIv1形式の通知を送信するために attrsFormat の値として使用できます – レガシーな通知エンドポイントを統合する場合に非常に便利です 32 { "subscriptionId": "12345", "data": [ { "id": "Room1", "type": "Room", "temperature": { "value": 23, "type": "Number", "metadata": {} } } ] } { "subscriptionId": "12345", "data": [ { "id": "Room1", "type": "Room", "temperature": 23 } ] } { "subscriptionId": "12345", "data": [ [ 23 ] ] } normalized (default) keyValues values 外側のベクトルはエンティティのリス トを表し、内側のベクトルは各エン ティティの属性の値を表します (この 単一エンティティの単一属性の例で はあまり面白くない)
  33. 33. • 以前のスライドで定義された標準フォーマットとは別に、 NGSIv2ではすべての通知の側面を再定義できます • http の代わりに httpCustom が使用され、以下のサブ フィールドがあります – URL クエリ・パラメータ – HTTP メソッド – HTTP ヘッダ – ペイロード (必ずしもJSONではない!) • ${..} 構文に基づく単純なマクロ置換言語を使用して、エンティティ・ データ (id, タイプ または 属性値)で”ギャップを埋める”ことができます 33 NGSIv2 のカスタム通知
  34. 34. NGSIv2 のカスタム通知 34 … "httpCustom": { "url": "http://foo.com/entity/${id}", "headers": { "Content-Type": "text/plain" }, "method": "PUT", "qs": { "type": "${type}" }, "payload": "The temperature is ${temp} degrees" } … PUT http://foo.com/entity/DC_S1-D41?type=Room Content-Type: text/plain Content-Length: 31 The temperature is 23.4 degrees PUT /v2/entities/DC_S1-D41/attrs/temp/value?type=Room … 23.4 カスタム通知設定 update notification 例:エンティティid とタイプ を URL の一部として使用し て、温度値のテキスト通知 (例:JSONではない)を送信し ます
  35. 35. 35 POST /v2/subscriptions … { "subject": { "entities": [ { "id": "Truck11", "type": "RoadVehicle" }, { "idPattern": "^Car[2-5]", "type": "RoadVehicle" } ], "condition": { "attrs": [ "speed" ], "expression": { "q": "speed>90", "georel": "near;maxDistance:100000", "geometry": "point", "coords": "40.418889,-3.691944" } } }, … } • フィルタ (前のスライドで説明) は、 サブスクリプションでも使用できます – id – type – id pattern – attribute values – geographical location NGSIv2 のサブスクリプション・フィルタ 例: スピードが90を超え、マドリッドの市内中心部ま での車両の距離が100km未満の場合は、id Truck11 または Car2〜Car5 (どちらも RoadVehicle タイプ) のエンティティの速度変更をサブスクライブする
  36. 36. 36 POST /v2/subscriptions … { "subject": { "entities": [ { "idPattern": ".*", "typePattern": ".*Vehicle" }, ], "condition": { "attrs": [ "speed" ], "expression": { "q": "speed>90", "mq": "speed.average==80..100", "georel": "near;maxDistance:100000", "geometry": "point", "coords": "40.418889,-3.691944" } } }, … } • サブスクリプションでも使用できます – type pattern – metadata value NGSIv2 のサブスクリプション・フィルタ 例: 速度が90を超え、その平均メタデータが80〜90 で、マドリッド市内中心部までの車両距離が100未満 である場合は、Vehicle (RoadVehicle, AirVehicleな ど) で終わる任意の種類のエンティティの速度変更を サブスクライブします
  37. 37. バッチ処理 • NGSIv1では標準的な操作 – POST /v1/updateContext – POST /v1/queryContext • 類似していますが、NGSIv2 にはユーザ・フレンドリーな操 作が含まれています – POST /v2/op/update – POST /v2/op/query 37
  38. 38. POST /v1/updateContext … { "updateAction": "APPEND“, "contextElements": [ { "type": "Room", "isPattern": "false", "id": "Room1", "attributes": [ { "name": "temp", "type": "float", "value": "29" } ] } ] } 200 OK ... { "contextResponses" : [ … ], "statusCode" : { "code" : "200", "details" : "OK" } } バッチ処理 38 POST /v2/op/update { "actionType": "append", "entities": [ { "type": "Room", "id": "Room1", "temperature": { "type": "Number", "value": 29 } } ] } 201 Created NGSIv1 NGSIv2 構造上の オーバーヘッド NGSIv2 レスポンスにペイ ロードはまったくありません 無用なものがたく さんあります 例: 属性 temp を29に設 定した Room1 エンティ ティ(Room タイプ) を作 成します
  39. 39. 200 OK ... { "contextResponses": [ { "contextElement": { "attributes": [ { "name": "temp", "type": "Number", "value": "25" } ], "id": "Room1", "isPattern": "false", "type": "Room" }, "statusCode": { … }} ] } バッチ処理 39 POST /v1/queryContext … { "entities": [ { "type": "Room", "isPattern": "true", "id": ".*" } , "attributes": [ "temp" ] ] } POST /v2/op/query … { "entities": [ { "idPattern": ".*", "type": "T" } ], "attrs": [ "temp" ] } NGSIv1 NGSIv2 リクエストは多かれ少 なかれ同じですが、 レスポンスを比較する と NGSIv2 のシンプルさ が明らかになります 200 OK ... [ { "id": "Room1", "type": "Room", "temp": { "type": "Number", "value": 25 } } ] 例: Room タイプ のすべてのエン ティティの temp 属性を取得します
  40. 40. バッチ・クエリ・スコープ • これは、一般に GET オペレーションの URL パラメータとして使用される、 q, mq および geo フィルタを バッチクエリに含める方法です 40 POST /v2/op/query … { "entities": [ { "idPattern": ".*", "type": "T" } ], "attrs": [ "temp" ], "expression": { "q": "temp>40", "georel": "near;maxDistance:20000", "geometry": "point", "coords": "40.31,-3.75" } } 例: 属性が 40より大きく、座標へのエンティ ティの距離 (40.31, -3.75) が 20 km 未満で ある限り、temp 属性 を持つ T 型のすべての エンティティを取得します
  41. 41. ページネーション • NGSIv1 では、 – limit, offset と details に基づいています – 実際にはエラーではないものに対して errorCode を 使用し、詳細フィールドのテキストベースの処理に強制 することで、NGSIv1ペイロードに数を合わせるための 厄介な回避策 – 固定された順序: 常に作成日 • NGSIv2 では、 – limit, offset と options=count に基づいてい ます • この部分はあまり変わりません – レスポンス内の Fiware-Total-Count HTTP ヘッ ダを使用して、よりクリーンで簡単にカウントを返す方 法 – orderBy パラメータに基づいて構成可能な順序付け • NGSIv2 仕様の詳細を参照してください 41 "errorCode": { "code": "200", "details": "Count: 322", "reasonPhrase": "OK" } Fiware-Total-Count: 322
  42. 42. IDs の操作 • NGSIv1 では、 – エンティティ id、属性名などのフィールドは、任意の値を持つことができます (*) – これは、これらのフィールドが通知を通じて伝播されたときに多くの場所で IDs として 機能するために使用されるため、多くの問題を引き起こす可能性があります • 例:これらのフィールドがテーブル名にマッピングされている場合、Cygnus の MySQL シン クに問題がある可能性があります – さらに、NGSIv1 では、IDs や属性名を ""(空の文字列)として扱うことができます。 これは奇妙で、一般的にはクライアントのエラー状態です • NGSIv2 は、ID フィールドの使用の健全性を保証するための一連の制限を設 定します。 特に: – 許可される文字は、以下のものを除いてプレーン ASCII セットの文字です: 制御文字, ホワイト・ スペース, &, ?, / and #. – 最大フィールド長は256文字です – 最小フィールド長は1文字です – 上記のルールは、次の6つのフィールド (IDフィールドとして識別されます)に適用されます: entity id, entity type, attribute name, attribute type, metadata name, metadata type. 42 (*) Orion マニュアルに記載されている禁止されている文字を除外します。これらの文字は、NGSIv1 API と NGSIv2 API のすべてのフィールドで一般的です。
  43. 43. 有用な参考文献 • NGSI と Orion の紹介 – https://github.com/telefonicaid/fiware-orion#introductory- presentations • Orion マニュアル – https://fiware-orion.readthedocs.io • FIWARE Catalogue の Orion のページ – http://catalogue.fiware.org/enablers/publishsubscribe-context- broker-orion-context-broker • NGSIv2 仕様 – http://fiware.github.io/specifications/ngsiv2/stable – http://fiware.github.io/specifications/ngsiv2/latest • StackOverflow での Orion のサポート – http://stackoverflow.com/questions/tagged/fiware-orion で 既存のQ&Aを探してください – “fiware-orion” タグをつけて、質問してください • FIWARE Tour Guide Application – https://github.com/fiware/tutorials.TourGuide-App 43
  44. 44. Thanks!Thanks!

×