FIWARE NGSIv1 を知っている開発者向けの NGSIv2 の概要を解説したスライドです。Orion Context Broker version 3.2.0 に対応しています。

1. Contact twitter
@fermingalan
Contact email
fermin.galanmarquez@telefonica.com
(Reference Orion Context Broker version: 3.2.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. • NGSIv2 入門
• RESTful-ness
• URL とペイロードの簡略化
• ネイティブなJSONデータ型
• テキストベースの属性値の set/get
• ジオロケーション機能
• Datetime サポート
• 一時的なエンティティ
• フィルタリング
• サブスクリプションの改善
• レジストレーションの改善
• バッチ操作
• IDs の操作
• ページネーション
• 無制限のテキスト属性
• フロー制御
2
Outline

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. NGSI モデルは、NGSIv2 でも保持されます
Attributes
• Name
• Type
• Value
Entity
• EntityId
• EntityType
1 n
“has”
Metadata
• Name
• Type
• Value
1 n
“has”
4

5. RESTful-ness
• NGSIv1 では
– もともと OMA-NGSI の標準操作に基づいていましたが、実際は RESTful
ではありません
• URLはリソースを識別するのではなく、操作の種類です
• 動詞は常に POST です
• 実際、NGSIv1 は RESTful よりも HTTP ベースの RPC に近い
– 後の段階で拡張された一連の操作（コンビニエンス操作）が追加されました
が、RESTful な完全な原則を適用するのが難しい標準操作の”レガシー”が
追加されました
• 例えば。 二重応答コード
• NGSIv2 は RESTful な原則を念頭において設計されています
– バッチ操作 (NGSIv1の標準操作に類似) も提供しますが、API の
RESTful 操作には影響しません
5

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. URL とペイロードの簡略化
• NGSIv1 では、OMA NGSI との厳密な整合には複雑さと非効率性が
伴います
– メッセージのペイロードには、実際には必要ない構造上のオーバーヘッド要素が多数
含まれています
– 意味論的観点から実際にペイロードを必要としないメソッドのレスポンス・ペイロード。
(例: 更新操作)
– URLs 内の不必要に長い構造要素
• NGSIv2 は URLs とペイロードを単純化し、よりリーンで冗長性の低い
API です
7

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. 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. 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. ネイティブな 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. ネイティブな JSON データ型
12
12
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. テキストベースの属性値の 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
…
86
200 OK
…
例: Car1 エンティティで speed
属性値を設定(set)します
例: Car1 エンティティで speed
属性値を取得(get)します

14. ジオ・ロケーション機能
• NGSIv1では
– エンティティのロケーションは point でなければなりません
– クエリは領域指定（円または多角形、内側または外側の領域）に基づいています。
– queryContext ペイロード・スコープの一部としてのクエリ
• NGSIv2では
– point に加えて,エンティティのロケーションは、line, box, polygon または 任意の
GeoJSON にすることができます
• null もサポートされており、”場所がない“ことを意味します
– クエリは空間的関係とジオメトリに基づいています
• 空間的関係: near (最大距離と最小距離), coveredBy, intersect, equal と disjoint
• ジオメトリ: point, line, box, polygon
– URL の一部としてのクエリ (ペイロード・ベースのアプローチよりユーザ・フレンドリー)
14

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
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. Datetime サポート
• NGSIv1では
– 日付を意味する属性はサポートされていません。従来の文字列とし
て扱われます
• NGSIv2は日付サポートを実装しています
– ミリ秒単位の精度のISO ISO8601フォーマット(部分表現とタイム
ゾーンを含む)に基づいています
• 構文の詳細については、 https://fiware-
orion.readthedocs.io/en/master/user/ngsiv2_implementati
on_notes/index.html#datetime-support を参照してください
• null もサポートされており、”日付なし“を意味します。
– 日時を表すには、予約属性タイプの DateTime を使用します
– 日付ベースのフィルタをサポートしています
17

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. 一時的なエンティティ (Transient entities)
• NGSIv1 では
– 一時的なエンティティはサポートされていません
• NGSIv2 は一時的なエンティティを実装しています
– 特別な意味を持つ、作成/更新時に提供された DateTime 型の dateExpires 属
性 : その時間に達すると、エンティティは期限切れになります
– “expires” とは、実装に依存することを意味します
• Orion の場合、期限切れのエンティティは自動的に削除されます。詳細は Orion のドキュメントを参照してく
ださい
– dateExpires 属性にも日付ベースのフィルタがサポートされています
19

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. • 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. • 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. • デフォルトでは、すべての属性はクエリのレスポンスまたは
通知に含まれます
• GET操作のパラメータとして、およびサブスクリプションの通
知サブフィールドとして、attrs フィールドを使用して、フィル
タリング・リストを指定できます
• attrs フィールドは、特別な属性を明示的に含むためにも使
用できます (デフォルトでは含まれていません)
– dateCreated: エンティティ作成日
– dateModified: エンティティの最終変更日
– dateExpires: エンティティの有効期限
• "*"は、 "すべての通常の属性"の別名として使用できます
23
属性フィルタリングと特殊属性

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. • デフォルトでは、すべての属性メタデータはクエリのレスポンスと通知に
含まれています
• GET操作のパラメータとして、および、サブスクリプションの通知サブ
フィールドとして、metadata フィールドを使用して、フィルタリング・リス
トを指定できます
• metadata フィールドは、明示的には含まれていない特別なメタデータ
を明示的に含むためにも使用できます
– dateCreated, dateModified: 属性作成または最終更新日
– actionType: どの値が通知をトリガする更新に対応するアクション・タイプ
であるか : update”, “append” または “delete” (*)
– previousValue: 通知をトリガする更新を処理する前の属性値を提供し
ます
• “*”は、 “すべての通常のメタデータ"の別名として使用できます
25
メタデータのフィルタリングと特殊属性
(*) actionType "delete" は、まだ、Orion 3.2.0 でサポートされていません

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. サブスクリプションの改善
• NGSIv1 コンテキスト・サブスクリプション API は非常に限られています
– 既存のサブスクリプションを一覧表示する操作はありません
• クライアントが作成されたサブスクリプションの ID を失った場合、API を使用してサブスクリ
プションを取得する方法はありません
– 永久サブスクリプションのサポートはありません
• 不本意ながら長いサブスクリプション(100年など)を作成するのは、汚い回避策です
– 通知構造の修正
• 任意のエンドポイント(例えば、公開 REST サービス) に統合するのが難しい
– フィルタはサポートされていません
– 初期通知は避けられません (いくつかのユースケースでは問題があります)
– 実際に属性値が変更されていない更新では通知は発生しません
– HTTP 通知のみ
27

28. サブスクリプションの改善
• NGSIv2 サブスクリプション API はこれらの制限をすべて解決し、いく
つかの追加機能を導入しています
– “ブラックリスト”に基づく通知属性 (NGSIv1 の”ホワイトリスト”アプローチに加えて)
– サブスクリプションの一時停止/再開機能
– ワンショット・サブスクリプション
– ?options=forcedUpdate URI パラメータは、更新が実際に行われたかどうか
にかかわらず通知を強制します
– 追加フィールド：送信された時間、最後の通知および説明
– onChangedAttributes は、変更された属性のみを通知します
28

29. NGSIv2 サブスクリプションの解剖
29
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.000Z",
"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 のみ
を含む通知が送信されます

30. NGSIv2のサブスクリプションと特殊フィールドを一覧表示
• リスト操作 (NGSIv1では使用できません)
– GET /v2/subscriptions は、すべてのサブスクリプションを一覧表示します
– GET /v2/subscriptions/<id> は、特定のサブスクリプションの情報を取得し
ます
• ホワイトリストとブラックリスト (通知フィールド内)
– “attrs”: [ “A”, “B” ] を “通知にAとBを含める” に使用 (ホワイトリスト)
– “exceptAttrs”: [ “A”, “B” ] を “AおよびBを除くすべての属性を含める” に使
用 (ブラックリスト)
– “attrs”: [ ] を “すべての属性” を含めるために使用 (特別なケース)
• その他の情報フィールド (通知フィールド内)
– timesSent: サブスクリプションがトリガーされ、通知が送信された回数
– lastNotification: 最後の通知に対応する datetime
• その他の情報フィールド(ルートレベルで)
– description: ユーザの便宜のためのフリーテキスト記述テキスト
30

31. NGSIv2の永続的および一時停止されたサブスクリプション
• status 属性は、サブスクリプションの一時停止/再開に使用できます
• GET操作では、 status フィールドは、
– active: サブスクリプションがアクティブです (通知が送信されます)
– inactive:サブスクリプションはアクティブではありません (通知は送信され
ません)
– expired: サブスクリプションは期限切れです (通知は送信されません)
– failed: 次のスライドで説明します
– oneshot:次の次のスライドで説明します
31
PATCH /v2/subscriptions/<id>
…
{
"status": "active"
}
PATCH /v2/subscriptions/<id>
…
{
"status": "inactive"
}
To pause To resume

32. • ステータス failed は、最後に通知が
失敗したことを意味します
– 例: エンドポイントに到達できません
• 通知要素(notifications element)
の詳細情報
– timesSent: 通知の合計回数（成功と失敗
の両方）
– lastSuccess: 通知が正常に送信された最
後の時刻
– lastFailure: 通知が試行され失敗した最
後の時刻
– lastNotification: 通知が送信された最後
の時刻 (成功または失敗のいずれか)
• 結果として、lastNotification の値は
lastFailure または lastSuccess と同じです
– lastFailureReason: 最後の失敗の原因
(テキスト)
– lastSuccessCode: 最後に成功した通知
が送信されたときに受信エンドポイントから返
された http コード (数値)
32
200 OK
Content-Type: application/json
…
[{
"id": " 51c0ac9ed714fb3b37d7d5a8 ",
"expires": "2026-04-05T14:00:00.000Z",
"status": "failed",
"subject": { … },
"notification": {
"timesSent": 3,
"lastNotification": "2016-05-31T11:19:32.000Z",
"lastSuccess": "2016-05-31T10:07:32.000Z",
"lastFailure": "2016-05-31T11:19:32.000Z",
…
}
}]
通知ステータス

33. 33
通知診断ワークフロー
(Notification diagnosis workflow)
サブスクリプションは期限
切れになっているため、通
知は送信されていません。
サブスクリプションを更新し
てそれを永続的なものにす
るか、有効期限を延長しま
す
サブスクリプションは非アク
ティブであるため、通知は送
信されていません。 サブス
クリプションを更新して有効
にします。
通知が送信され、受信側
エンドポイントは正しい受
信を確認します。
通知は送信されていま
すが、受信側のエンドポ
イントは、 HTTP エラー
を報告しています。 受信
エンドポイントを確認しま
す (例 : ログなど)。
通知が送信されないとい
う問題があります。
"lastFailureReason"
フィールド値はそれに関
する追加情報を提供す
るべきです。

34. ワンショット・サブスクリプション
(Oneshot subscription)
• Active ステータスの変形です。
したがって、サブスクリプションが
1回トリガされると (つまり、通知
が送信されると)、自動的に
Inactive ステータスに移行しま
す
• Inactive なサブスクリプションは、
oneshot にステップして、プロセ
スをやり直すことができます
• この場合、サブスクリプションの作
成または更新時の初期通知は送
信されません
200 OK
Content-Type: application/json
…
[{
"id": "51c0ac..",
"status": "oneshot",
…
}
200 OK
Content-Type: application/json
…
[{
"id": "51c0ac..",
"status": "inactive",
…
}
}]
サブスクリプションが
トリガー
PATCH /v2/subscriptions/51c0ac..
{
"status": "oneshot"
}
34

35. NGSIv2の通知フォーマット
• オプションの attrsFormat フィールドを使用すると、表現モードに合わせて異なる通知フレーバを選
択できます
• 通知には、受信者がフォーマットを識別するための NGSIv2-AttrsFormat ヘッダーが含まれます
• legacy は、NGSIv1形式の通知を送信するために attrsFormat の値として使用できます
– レガシーな通知エンドポイントを統合する場合に非常に便利です
35
{
"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
外側のベクトルはエンティティのリス
トを表し、内側のベクトルは各エン
ティティの属性の値を表します (この
単一エンティティの単一属性の例で
はあまり面白くない)

36. • 以前のスライドで定義された標準フォーマットとは別に、
NGSIv2ではすべての通知の側面を再定義できます
• http の代わりに httpCustom が使用され、以下のサブ
フィールドがあります
– URL クエリ・パラメータ
– HTTP メソッド
– HTTP ヘッダ
– ペイロード (必ずしもJSONではない!)
• ${..} 構文に基づく単純なマクロ置換言語を使用して、エンティティ・
データ (id, タイプ または 属性値)で”ギャップを埋める”ことができます
36
NGSIv2 のカスタム通知

37. NGSIv2 のカスタム通知
37
…
"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ではない)を送信し
ます

38. 38
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 タイプ)
のエンティティの速度変更をサブスクライブする

39. 39
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な
ど) で終わる任意の種類のエンティティの速度変更を
サブスクライブします

40. レジストレーションの改善
• NGSIv1 レジストレーション API にはいくつかの制限があります
– レジストレーションがクエリ、更新、またはその両方のいずれであるかを制御する方法
はありません (両方が常に想定されます)
• NGSIv2 レジストレーション API はこれらの制限を解決します
– supportedForwardingMode フィールドで、Orion がコンテキスト・プロバイダ
にクエリのみ、更新のみ、またはその両方を転送する必要があるかどうかを指定でき
ます
– ?options=skipForwardking を使用してクエリで転送を無効にできます
• この場合、クエリは Context Broker のローカル コンテキスト情報のみを使用して評価されます。
40

41. バッチ処理
• NGSIv1では標準的な操作
– POST /v1/updateContext
– POST /v1/queryContext
• 類似していますが、NGSIv2 にはユーザ・フレンドリーな操
作が含まれています
– POST /v2/op/update
– POST /v2/op/query
41

42. 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"
}
}
バッチ処理
42
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 タイプ) を作
成します

43. 200 OK
...
{
"contextResponses": [
{
"contextElement": {
"attributes": [
{
"name": "temp",
"type": "Number",
"value": "25"
}
],
"id": "Room1",
"isPattern": "false",
"type": "Room"
},
"statusCode": { … }}
]
}
バッチ処理
43
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
属性を取得します

44. バッチ・クエリ・スコープ
• これは、一般に GET オペレーションの
URL パラメータとして使用される、
q, mq および geo フィルタを
バッチクエリに含める方法です
44
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 型のすべての
エンティティを取得します

45. 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.
45
(*) Orion マニュアルに記載されている禁止されている文字を除外します。これらの文字は、NGSIv1 API と NGSIv2
API のすべてのフィールドで一般的です。

46. ページネーション
• NGSIv1 では、
– limit, offset と details に基づいています
– 実際にはエラーではないものに対して errorCode を
使用し、詳細フィールドのテキストベースの処理に強制
することで、NGSIv1ペイロードに数を合わせるための
厄介な回避策
– 固定された順序: 常に作成日
• NGSIv2 では、
– limit, offset と options=count に基づいてい
ます
• この部分はあまり変わりません
– レスポンス内の Fiware-Total-Count HTTP ヘッ
ダを使用して、よりクリーンで簡単にカウントを返す方
法
– orderBy パラメータに基づいて構成可能な順序付け
• NGSIv2 仕様の詳細を参照してください
46
"errorCode": {
"code": "200",
"details": "Count: 322",
"reasonPhrase": "OK"
}
Fiware-Total-Count: 322

47. 無制限のテキスト属性 (Unrestricted text attributes)
• NGSiv1 では、
– 禁止文字 (https://fiware-
orion.readthedocs.io/en/master/user/forbidden_characters/index.html
) は常に適用されます
• NGSIv2では、特別な属性タイプTextUnrestrictedを使用して、属性値のこの
チェックを回避できます
– セキュリティに影響を与える可能性があります (インジェクション攻撃)。自己責任で使
用してください！
…
"description": {
"type": "TextUnrestricted",
"value": "Hey! I'm using <forbidden chars>“
}
…
46

48. フロー制御 (Flow control)
• NGSIv1 では、
– Orion 更新レスポンスは、これらの更新によってトリガーされた通知の送信から切り
離されています
– これにより、更新を送信するクライアントが受信者の処理通知よりもはるかに速い場
合、飽和が発生する可能性があります
• NGSIv2 では、Orion が更新にすぐにレスポンスしないように、新しいオプショ
ン (flowControl) を実装します。通知キューの占有サイズに基づいて遅延が
発生します （占有が多いほど、遅延も大きくなります)
– -notifFlowControl CLI オプションと組み合わせて使用されます
– 機能説明: https://fiware-
orion.readthedocs.io/en/master/admin/perf_tuning/index.html#updat
es-flow-control-mechanism
– 詳細な例/チュートリアル:
https://github.com/telefonicaid/fiware-
orion/blob/master/test/flowControlTest/README.md
47

49. 更新の送信が
速すぎる
クライアント
受信者は
それほど
速くありません
ある時点で、Orion の通知キューが
飽和し、新しい通知が破棄されます
フロー制御 (Flow control)
NGSIv1 の場合：
NGSIv2 の場合：
48

50. 有用な参考文献
• 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
50

51. Thanks!
Thanks!