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

1. Contact twitter
@fermingalan
Contact email
fermin.galanmarquez@telefonica.com
(Reference Orion Context Broker version: 2.3.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
• Value1 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 データ型
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. テキストベースの属性値の 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. ジオ・ロケーション機能
• NGSIv1では
– エンティティのロケーションは point でなければなりません
– クエリは領域指定（円または多角形、内側または外側の領域）に基づいています。
– queryContext ペイロード・スコープの一部としてのクエリ
• NGSIv2では
– point に加えて,エンティティのロケーションは、line, box, polygon または 任意の
GeoJSON にすることができます
– クエリは空間的関係とジオメトリに基づいています
• 空間的関係: 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 を参照してください
– 日時を表すには、予約属性タイプの 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 2.3.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 サービス) に統合するのが難しい
– フィルタはサポートされていません
– 初期通知は避けられません (いくつかのユースケースでは問題があります)
– 実際に属性値が変更されていない更新では通知は発生しません
27

28. サブスクリプションの改善
• NGSIv2 サブスクリプション API はこれらの制限をすべて解決し、いく
つかの追加機能を導入しています
– “ブラックリスト”に基づく通知属性 (NGSIv1 の”ホワイトリスト”アプローチに加えて)
– サブスクリプションの一時停止/再開機能
– ワンショット・サブスクリプション
– サブスクリプション時に ?options=skipInitialNotification を使用して初期通
知を無効にすることができます
– ?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.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 のみ
を含む通知が送信されます

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.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",
…
}
}]
通知ステータス

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では標準的な操作
– POST /v1/updateContext
– POST /v1/queryContext
• 類似していますが、NGSIv2 にはユーザ・フレンドリーな操
作が含まれています
– POST /v2/op/update
– POST /v2/op/query
40

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

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

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

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

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

47. Thanks!Thanks!