これは、FIWARE Platform のチュートリアルです。スーパーマーケット・チェーンのスト ア・ファインダのデータから始め、コンテキスト・データとして各ストアの住所と場所を FIWARE context broker に渡して、非常に単純な "Powered by FIWARE" アプリケーシ ョンを作成します。
このチュートリアルでは、全体で cUrl コマンドを使用してい ますが 、Postman documentation も利用できます。
アーキテクチャ¶
デモアプリケーションでは 、Orion Context Broker という 1 つの FIWARE コンポーネントしか使用しません。アプリケーションが "Powered by FIWARE" と認定するには、Orion Context Broker を使用するだけで十分です。
現在、Orion Context Broker はオープンソースの MongoDB 技術を利用して、コンテキスト・データの永続性 を維持しています。したがって、アーキテクチャは 2 つの要素で構成されます :
- NGSI-v2 を使用してリ クエストを受信する Orion Context Broker
- バックエンドの MongoDB データベース
- Orion Context Broker が、データ・エンティティなどのコンテキスト・データ 情報、サブスクリプション、登録などを保持するために使用します
2 つの要素間のすべての対話は HTTP リクエストによって開始されるため、エンティティ はコンテナ化され、公開されたポートから実行されます。
前提条件¶
Docker¶
物事を単純にするために、両方のコンポーネントが Docker を使用して実行されます。Docker は、さまざまコンポーネントをそれぞれの環境に 分離することを可能にするコンテナ・テクノロジです。
- Docker を Windows にインストールするには 、こちらの手順に従ってくださ い
- Docker を Mac にインストールするには 、こちらの手順に従ってください
- Docker を Linux にインストールするには 、こちらの手順に従ってください
Docker Compose (オプション)¶
Docker Compose は、マルチコンテナ Docker アプリケーションを定義して実行する ためのツールです 。YAML file ファイルは、アプリケーションのために必要なサービスを構成するために使用します。つ まり、すべてのコンテナ・サービスは 1 つのコマンドで呼び出すことができます 。Docker Compose は、デフォルトで Docker for Windows と Docker for Mac の一部と してインストールされますが、Linux ユーザ はここに記載されている手順に従う必要 があります
次のコマンドを使用して、現在の Docker バージョンと Docker Compose バージ ョンを確認できます :
docker-compose -v
docker versionDocker バージョン 18.03 以降と Docker Compose 1.21 以上を使用していることを確認 し、必要に応じてアップグレードしてください。
コンテナの起動¶
オプション 1) Docker コマンドを直接使用¶
まず、Docker Hub から必要な Docker イメージを取得し、コンテナが接続するネットワ ークを作成します :
docker pull mongo:3.6
docker pull fiware/orion
docker network create fiware_defaultMongoDB データベースを実行している Docker コンテナを 起動し、ネットワークに接続するには、次のコマンドを実行します :
docker run -d --name=mongo-db --network=fiware_default \
--expose=27017 mongo:3.6 --bind_ip_all --smallfilesOrion Context Broker は、次のコマンドを使用して起動し、ネットワークに接続できま す :
docker run -d --name fiware-orion --network=fiware_default \
-p 1026:1026 fiware/orion -dbhost mongo-db注 : クリーンアップして再び開始したい場合は、以下のコマンドを使用して行う ことができます
docker stop fiware-orion
docker rm fiware-orion
docker stop mongo-db
docker rm mongo-db
docker network rm fiware_defaultオプション 2) Docker Compose を使用¶
すべてのサービスは、 docker-compose コマンドを使ってコマンドラインから初期化す
ることができます。リポジトリを複製し、以下のコマンドを実行して必要なイメージを作
成してください :
git clone https://github.com/FIWARE/tutorials.Getting-Started.git
git checkout NGSI-v2
cd tutorials.Getting-Started
docker-compose -p fiware up -d注 : クリーンアップして再起動する場合は、次のコマンドを使用して再起動でき ます :
docker-compose -p fiware down最初の "Powered by FIWARE" アプリを作成¶
サービスの状態を確認¶
公開されたポートに対して HTTP リクエストを行うことで、Orion Context Broker が実 行されているかどうかを確認できます :
1 リクエスト :¶
curl -X GET \
'http://localhost:1026/version'レスポンス :¶
レスポンスは次のようになります :
{
"orion": {
"version": "1.12.0-next",
"uptime": "0 d, 0 h, 3 m, 21 s",
"git_hash": "e2ff1a8d9515ade24cf8d4b90d27af7a616c7725",
"compile_time": "Wed Apr 4 19:08:02 UTC 2018",
"compiled_by": "root",
"compiled_in": "2f4a69bdc191",
"release_date": "Wed Apr 4 19:08:02 UTC 2018",
"doc": "https://fiware-orion.readthedocs.org/en/master/"
}
}
Failed to connect to localhost port 1026: Connection refusedのレスポンス を受け取った時の対応は?
Connection refusedのレスポンスを受け取った場合、Orion Content Broker はこの チュートリアルで期待される場所には見つかりません。各 cUrl コマンドの URL とポ ートを修正した IP アドレスで置き換える必要があります。すべての cUrl コマンドの チュートリアルでは、localhost:1026で orion を使用できると仮定しています。次の対策を試してください :
- Docker コンテナが動作していることを確認するには、以下を試してください :
docker ps実行中の 2 つのコンテナが表示されます。orion が実行されていない場合は、必要に 応じてコンテナを再起動できます。このコマンドは、開いているポート情報も表示しま す。
- Virtual Box と
docker-machineをインストールしてい る場合は、orion docker コンテナが別の IP アドレスから実行されている可能性 があります。次のように仮想ホスト IP を取得する必要があります :curl -X GET \ 'http://$(docker-machine ip default):1026/version'または、コンテナネットワーク内からすべての cUrl コマンドを実行します :
docker run --network fiware_default --rm appropriate/curl -s \ -X GET http://orion:1026/version
コンテキスト・データの作成¶
FIWARE はコンテキスト情報を管理するシステムなので、2 つの新しいエンティティ
(Berlin のストア) を作成することによって、コンテキスト・データをシステムに追
加することができます。どんなエンティティも id と type 属性を持たなければなら
ず、追加の属性はオプションであり、記述されているシステムに依存します。それぞれの
追加属性も typeと value 属性を定義しなければなりません。
2 リクエスト :¶
curl -iX POST \
'http://localhost:1026/v2/entities' \
-H 'Content-Type: application/json' \
-d '
{
"id": "urn:ngsi-ld:Store:001",
"type": "Store",
"address": {
"type": "PostalAddress",
"value": {
"streetAddress": "Bornholmer Straße 65",
"addressRegion": "Berlin",
"addressLocality": "Prenzlauer Berg",
"postalCode": "10439"
}
},
"location": {
"type": "geo:json",
"value": {
"type": "Point",
"coordinates": [13.3986, 52.5547]
}
},
"name": {
"type": "Text",
"value": "Bösebrücke Einkauf"
}
}'3 リクエスト :¶
後続の各エンティティには、指定された type の一意の id が必要です。
curl -iX POST \
'http://localhost:1026/v2/entities' \
-H 'Content-Type: application/json' \
-d '
{
"type": "Store",
"id": "urn:ngsi-ld:Store:002",
"address": {
"type": "PostalAddress",
"value": {
"streetAddress": "Friedrichstraße 44",
"addressRegion": "Berlin",
"addressLocality": "Kreuzberg",
"postalCode": "10969"
}
},
"location": {
"type": "geo:json",
"value": {
"type": "Point",
"coordinates": [13.3903, 52.5075]
}
},
"name": {
"type": "Text",
"value": "Checkpoint Markt"
}
}'データモデルのガイドライン¶
コンテキスト内の各データ・エンティティは、ユースケースによって異なりますが、各デ ータ・エンティティ内の共通構造は、再利用を促進するために標準化された順序にする必 要があります。完全な FIWARE データモデルのガイドラインは 、ここに あります。このチュートリアルでは、次の推奨事項の使用方法を示します :
すべての用語はアメリカ英語で定義されています¶
コンテキスト・データの value フィールドは任意の言語であってもよく、すべての属
性およびタイプは英語を使用して書かれています。
エンティティ・タイプの名前は大文字で始まる必要があります¶
この場合、1 つエンティティ・タイプしか持っていません - Store
エンティティ ID は、NGSI-LD のガイドラインに従った URN でなければなりません¶
NGSI-LD は現時点で
はドラフトの勧告で
すが、各 id は 標準フォーマットに従った URN という提案があります :
urn:ngsi-ld:<entity-type>:<entity-id>。これは、システム内のすべての id がユ
ニークであることを意味します。
データ・タイプ名は、可能であれば schema.org データ・タイプを再利用する必要があります¶
Schema.org は、共通の構造化データ・スキーマを作成するイニ
シアチブです。再利用を促進するために、Store エンティティ内 で
Text と
PostalAddress タイプ名を意図的に使用してい
ます。Open311 (市政問題追跡用) や
Datex II (輸送システム用) などの既存の標準も使用できま
すが、既存のデータモデルに同じ属性が存在するかどうかを確認して再利用することが重
要です。
属性名にはキャメルケースの構文を使用します¶
streetAddress、addressRegion、addressLocality および postalCode 属性のす
べての例は、キャメルケースを使用しています。
位置情報は address および location 属性を使用して定義する必要があります¶
- schema.org のように、市政の位置に
address属性を使用 しています - 地理座標には
location属性を使用しています
GeoJSON を使用して地理空間プロパティをコード化¶
GeoJSON は、単純な地理的特徴を表現するためのオープンな標準
フォーマットです。location 属性が GeoJSON Point location としてエンコードさ
れています。
コンテキスト・データのクエリ¶
コンシューマ向けアプリケーションは、Orion Context Broker への HTTP リクエストを 作成することにより、コンテキスト・データをリクエストできるようになりました。既存 の NGSI インタフェースにより、複雑なクエリを作成し、結果をフィルタリングすること ができます。
現時点では、ストア・ファインダのデモでは、すべてのコンテキスト・データが HTTP リ クエストを介して直接追加されていますが、より複雑なスマートなソリューションでは 、Orion Context Broker は各エンティティに関連付けられたセンサーからコンテキスト を直接取得します。
いくつかの例を示します。それぞれの場合、options=keyValues クエリ・パラメータは
、各属性からタイプ要素を取り除いてレスポンスを短縮するために使用されています。
id でエンティティ・データを取得¶
この例では、 urn:ngsi-ld:Store:001 のデータを返します
4 リクエスト :¶
curl -X GET \
'http://localhost:1026/v2/entities/urn:ngsi-ld:Store:001?options=keyValues'レスポンス :¶
{
"id": "urn:ngsi-ld:Store:001",
"type": "Store",
"address": {
"streetAddress": "Bornholmer Straße 65",
"addressRegion": "Berlin",
"addressLocality": "Prenzlauer Berg",
"postalCode": "10439"
},
"location": {
"type": "Point",
"coordinates": [13.3986, 52.5547]
},
"name": "Bösebrücke Einkauf"
}タイプ別にエンティティ・データを取得¶
この例では、コンテキスト・データ内のすべての Store エンティティのデータを返し
ます
5 リクエスト :¶
curl -X GET \
'http://localhost:1026/v2/entities?type=Store&options=keyValues'レスポンス :¶
[
{
"id": "urn:ngsi-ld:Store:001",
"type": "Store",
"address": {
"streetAddress": "Bornholmer Straße 65",
"addressRegion": "Berlin",
"addressLocality": "Prenzlauer Berg",
"postalCode": "10439"
},
"location": {
"type": "Point",
"coordinates": [13.3986, 52.5547]
},
"name": "Bose Brucke Einkauf"
},
{
"id": "urn:ngsi-ld:Store:002",
"type": "Store",
"address": {
"streetAddress": "Friedrichstraße 44",
"addressRegion": "Berlin",
"addressLocality": "Kreuzberg",
"postalCode": "10969"
},
"location": {
"type": "Point",
"coordinates": [13.3903, 52.5075]
},
"name": "Checkpoint Markt"
}
]属性の値を比較してコンテキスト・データをフィルタリング¶
この例では、Kreuzberg 地区にあるすべてのストアを返します
6 リクエスト :¶
curl -X GET \
http://localhost:1026/v2/entities?type=Store&q=address.addressLocality==Kreuzberg&options=keyValuesレスポンス :¶
[
{
"id": "urn:ngsi-ld:Store:002",
"type": "Store",
"address": {
"streetAddress": "Friedrichstraße 44",
"addressRegion": "Berlin",
"addressLocality": "Kreuzberg",
"postalCode": "10969"
},
"location": {
"type": "Point",
"coordinates": [13.3903, 52.5075]
},
"name": "Checkpoint Markt"
}
]geo:json 属性の値を比較してコンテキスト・データをフィルタリング¶
この例 では、ベルリンのブランデンブルク門から 1.5km 以内のすべてのストアを返 却します (52.5162N 13.3777W)
7 リクエスト :¶
curl -X GET \
'http://localhost:1026/v2/entities?type=Store&georel=near;maxDistance:1500&geometry=point&coords=52.5162,13.3777'レスポンス :¶
[
{
"id": "urn:ngsi-ld:Store:002",
"type": "Store",
"address": {
"streetAddress": "Friedrichstraße 44",
"addressRegion": "Berlin",
"addressLocality": "Kreuzberg",
"postalCode": "10969"
},
"location": {
"type": "Point",
"coordinates": [13.3903, 52.5075]
},
"name": "Checkpoint Markt"
}
]