Data API を使用すると、デバイスから FIWARE IoT Stack に保存されている情報にアクセスできます :
- データの更新とクエリ
- データ更新のサブスクライブ
- ジオロケーションデータのクエリ
FIWARE IoT Stack のさまざまなコンポーネント間のすべての通信は、次のセクションで説明するNGSI RESTful インターフェイスインターフェイス/プロトコルを介して行われます。NGSI RESTful インターフェイスは、OMA NGSI 仕様に基づいています。これは、メタデータを含むあらゆる型のデータを扱うことを可能にする標準インターフェースです。
次のセクションに進む前に、SlideShare の NGSI と Orion Context Broker 入門プレゼンテーションを見てみることをお勧めします。
データの更新とクエリ¶
Context Broker GE がエクスポートする REST 操作を使用してコンテキスト情報を更新するアプリケーションアーキテクチャの一部として実行されるプロセスは、コンテキストプロデューサの役割を果たします。例として、レストラン評価のアプリケーションを考えてみ・ましょう。NiceEating と呼びましょう。ユーザのスマートフォン上で動作するアプリケーションのクライアント部分はコンテキストプ・ロデューサの役割を果たし、レストランの評価を可能にします。
マルチテナンシーの観点から、アプリケーションに対応するサービスとサブサービスがそれぞれ "smartown" と "NiceEating" であると考えてみましょう。以下の例に示すすべてのリクエストには、Fiware-service
と Fiware-servicepath
対応するヘッダーが含まれます。プラットフォームの観点からは、これらのヘッダーは必須です。このドキュメントにマルチテナンシーの詳細があります。。この例には、X-Auth-Token
要求を認証するために必要なヘッダーも含まれています。詳細について は、セキュリティのセクションを参照してください)。
一方、Context Broker GE がエクスポートする REST 操作を使用してコンテキスト情報を照会するアプリケーションのアーキテクチャの一部として実行されるプロセスは、コンテキスト・コンシューマの役割を果たします。NiceEating アプリの場合、レストランの評価をクエリできるようにするモバイルアプリケーションがユーザのスマートフォンで動作し、コンテキスト・コンシューマの役割を果たします。アプリケーションの特定の部分は、コンテキスト・プロデューサとコンテキスト・コンシューマの両方の役割を果たします。これは、NiceEatingアプリのモバイルクライアントの場合で、エンドユーザはレストランの料金について評価し、評価ををクエリすることができます。
NiceEating アプリケーションに関連するエンティティは、Restaurant, Client および Rating のタイプです。所定のユーザがレストランをスコアする、例えば、0から5までの尺度で、"Client1234" は "LeBistro" レストランについて "4" と評価する場合。スマートフォンアプリケーションは、以下のHTTP リクエストを発行して、コンテキスト・コンシューマの役割を果たします :
POST <cb_host>:<cb_port>/v2/entities
Content-Type: application/json
Fiware-service: smartown
Fiware-servicepath: /NiceEating
X-Auth-Token: D3wiv5j7y6oiwo9w4ds5u20Y0bb6pL
{
"id": "LeBistro::Client1234",
"type": "Rating",
"score": {
"type" : "Integer",
"value" : 4
}
}
新しい評価エンティティが作成されるたびに、該当するレストランの平均評価は、レストランのエンティティを適宜更新するアプリケーション(コンテキスト・プロデューサーの役割も果たしている)のバックエンドによって更新されます :
PUT <cb_host>:<cb_port>/v2/entities/LeBistro/attrs/average_scoring?type=Restaurant
Content-Type: application/json
Fiware-service: smartown
Fiware-servicepath: /NiceEating
X-Auth-Token: D3wiv5j7y6oiwo9w4ds5u20Y0bb6pL
{
"type": "Float",
"value" : 4.2
}
または、よりコンパクトに :
PUT <cb_host>:<cb_port>/v2/entities/LeBistro/attrs/average_scoring/value?type=Restaurant
Content-Type: text/plain
Fiware-service: smartown
Fiware-servicepath: /NiceEating
X-Auth-Token: D3wiv5j7y6oiwo9w4ds5u20Y0bb6pL
4.2
最後に、スマートフォン・アプリケーションを使用して、レストランの情報を取得することができます。その場合、アプリケーションはコンテキスト・コンシューマとして動作し、レストランのエンティティをクエリします。たとえば、average_scoring 属性を取得するには、クライアント・アプリケーションで次のようにクエリを実行します :
GET <cb_host>:<cb_port>/v2/entities/LeBistro/attrs/average_scoring?type=Restaurant
Fiware-service: smartown
Fiware-servicepath: /NiceEating
X-Auth-Token: D3wiv5j7y6oiwo9w4ds5u20Y0bb6pL
次のようなJSONレスポンスが得られます :
{
"type": "Float",
"value": 3.2
}
"LeBistro" レストランのすべての属性の値を一度に取得することもできます :
GET <cb_host>:<cb_port>/v2/entities/LeBistro/attrs?type=Restaurant
Fiware-service: smartown
Fiware-servicepath: /NiceEating
X-Auth-Token: D3wiv5j7y6oiwo9w4ds5u20Y0bb6pL
次のようなJSONレスポンスが得られます :
{
"name": {
"type": "Text",
"value": "Le Bistro"
},
"average_scoring": {
"type": "Float",
"value": 4.2
},
"location": {
"type": "geo:point",
"value": "40.419697, -3.691281"
},
"postal_address": {
"type": "Address",
"value": {
"street": "Calle Alcala 57",
"city": "Madrid",
"country": "Spain"
}
},
"cousine_type": {
"type": "Text",
"value": "french"
}
}
postal_address 属性に注意してください。NGSI の属性値は、文字列、数値などの単純な型に限定されません。JSON オブジェクトまたは配列を属性値として使用することもできます。
また、属性値のみを含むよりコンパクトな応答を得るには、次のように keyValues 形式を使用できます。
GET <cb_host>:<cb_port>/v2/entities/LeBistro?type=Restaurant&options=keyValues
Fiware-service: smartown
Fiware-servicepath: /NiceEating
X-Auth-Token: D3wiv5j7y6oiwo9w4ds5u20Y0bb6pL
次のようなJSONレスポンスが得られます :
{
"name": "Le Bistro",
"average_scoring": 4.2,
"location": "40.419697, -3.691281",
"postal_address": {
"street": "Calle Alcala 57",
"city": "Madrid",
"country": "Spain"
},
"cousine_type": "french"
}
最後に、Context Broker GE はフィルタを使用したクエリが可能です。たとえば、平均得点が 4 を超えるすべてのレストランを取得するには、次の操作が可能です :
GET /v2/entities?type=Restaurant&q=average_scoring>4
Fiware-service: smartown
Fiware-servicepath: /NiceEating
X-Auth-Token: D3wiv5j7y6oiwo9w4ds5u20Y0bb6pL
データ更新のサブスクライブ¶
コンテキスト・コンシューマは、同期方法でクエリを使用して情報を取得すること ("コンテキスト情報の更新とクエリの方法" を参照) とは別に、通知を使用してコンテキスト情報を非同期で取得することもできます。このシナリオでは、Context Broker GEは、サブスクリプション要求で指定した所定の条件で通知を送信するように"プログラム"されます。
NiceEating の場合、アプリケーション・バックエンドはサブスクリプションを使用する可能性があります。したがって、新しい評価がどのユーザによってもキャストされるたびに、レストランの平均スコアを再計算して、Context Broker GEに戻すため、バックエンドに通知されます。
POST <cb_host>:<cb_port>/v2/subscriptions
Content-Type: application/json
Fiware-service: smartown
Fiware-servicepath: /NiceEating
X-Auth-Token: D3wiv5j7y6oiwo9w4ds5u20Y0bb6pL
{
"description": "New ratings subscription",
"subject": {
"entities": [
{
"idPattern": ".*",
"type": "Rating"
}
],
"condition": {
"attrs": [ "score" ]
}
},
"notification": {
"http": {
"url": "http://backend.niceeating.foo.com:1028/ratings"
},
"attrs": [ "score" ]
}
}
もう1つのケースは、特定のレストランの平均レーティングの変更をサブスクライブするアプリケーションです。これは、他のレストランオーナーがレストランのスコアがどのように変わっているかを知るのに役立ちます。
POST <cb_host>:<cb_port>/v2/subscriptions
Content-Type: application/json
Fiware-service: smartown
Fiware-servicepath: /NiceEating
X-Auth-Token: D3wiv5j7y6oiwo9w4ds5u20Y0bb6pL
{
"description": "Average ratings changes subscription",
"subject": {
"entities": [
{
"idPattern": ".*",
"type": "Restaurant"
}
],
"condition": {
"attrs": [ "average_scoring" ]
}
},
"notification": {
"http": {
"url": "http://myapp.foo.com:1028/restaurant_average_scorings"
},
"attrs": [ "average_scoring" ]
}
}
ジオロケーションデータのクエリ¶
Context Broker GEの非常に強力な機能の1つは、地理位置検索を実行できることです。サークルまたはポリゴンで定義された領域の内側または外側にあるエンティティにクエリを実行できます。
例えば、マドリード市内中心部 (GPS座標40.418889、-3.691944で識別) から13km以内のレストランをすべて照会するには、コンテキストコンシューマアプリケーションは次のクエリを使用します。
GET /v2/entities?type=Restaurant&georel=near;maxDistance:1000&geometry=point&coords=40.418889,-3.691944
Fiware-service: smartown
Fiware-servicepath: /NiceEating
X-Auth-Token: D3wiv5j7y6oiwo9w4ds5u20Y0bb6pL
詳細情報¶
この簡単な紹介では、Context Broker の機能の一部のみを示しています。その他の機能は次のとおりです :
- ページネーション (Pagination)
- 型ブラウジング (Type browsing)
- このドキュメントで説明されている"greater than"フィルタとは別のより多くのフィルタ (More filters)
- 作成および変更の日付のサポート (Creation and modification dates support)
- メタデータ (Metadata)
- 登録とコンテキスト・プロバイダ (Registrations and context providers)
Contire Broker(Orion)) では、この機能、リファレンス API のドキュメント、およびソースコードを提供する FIWARE コンポーネントに関する詳細情報を得ることができます。