これは、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 version

Docker バージョン 20.10 以降と Docker Compose 1.29 以上を使用していることを確認し、必要に応じてアップグレードしてください。

コンテナの起動¶

オプション 1) Docker コマンドを直接使用¶

まず、Docker Hub から必要な Docker イメージを取得し、コンテナが接続するネットワークを作成します :

docker pull mongo:4.4
docker pull fiware/orion
docker network create fiware_default

MongoDB データベースを実行している Docker コンテナを起動し、ネットワークに接続するには、次のコマンドを実行します :

docker run -d --name=mongo-db --network=fiware_default \
  --expose=27017 mongo:4.4 --bind_ip_all

Orion 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 コマンド、または、Compose V2 にある新しい docker compose コマンド (ハイフンなし -) を使用してコマンドラインから初期化できます。次のようにコマンドを実行して、リポジトリのクローンを作成し、必要なイメージを作成してください:

git clone https://github.com/FIWARE/tutorials.Getting-Started.git
cd tutorials.Getting-Started
git checkout NGSI-v2

export $(cat .env | grep "#" -v)
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": "3.0.0",
        "uptime": "0 d, 0 h, 17 m, 19 s",
        "git_hash": "d6f8f4c6c766a9093527027f0a4b3f906e7f04c4",
        "compile_time": "Mon Apr 12 14:48:44 UTC 2021",
        "compiled_by": "root",
        "compiled_in": "f307ca0746f5",
        "release_date": "Mon Apr 12 14:48:44 UTC 2021",
        "machine": "x86_64",
        "doc": "https://fiware-orion.rtfd.io/en/3.0.0/",
        "libversions": {
            "boost": "1_66",
            "libcurl": "libcurl/7.61.1 OpenSSL/1.1.1g zlib/1.2.11 nghttp2/1.33.0",
            "libmicrohttpd": "0.9.70",
            "openssl": "1.1",
            "rapidjson": "1.1.0",
            "mongoc": "1.17.4",
            "bson": "1.17.4"
        }
    }
}

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"
        },
        "metadata": {
            "verified": {
                "value": true,
                "type": "Boolean"
            }
        }
    },
    "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"
        },
        "metadata": {
            "verified": {
                "value": true,
                "type": "Boolean"
            }
        }
    },
    "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 は最近、完全な ESTI 仕様として公開されました。提案では、各 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 としてエンコードされています。

属性メタデータ¶

メタデータは、データに関するデータ ("data about data") であり、精度, プロバイダ, タイムスタンプなどの属性値自体のプロパティを記述するために使用される追加データです。いくつかの組み込みメタデータ属性がすでに存在し、これらの名前は予約されています。

dateCreated (type: DateTime): 属性作成日 (ISO8601 文字列)
dateModified (type: DateTime): 属性変更日 (ISO8601 文字列)
previousValue (type: any): 以前の値。通知時のみ
actionType (type: Text): アクションタイプ。通知時のみ

メタデータの1つの要素は、address 属性内にあります。verified フラグは、アドレスが確認されたかどうかを示します。

コンテキスト・データのクエリ¶

コンシューマ向けアプリケーションは、Orion Context Broker への HTTP リクエストを作成することにより、コンテキスト・データをリクエストできるようになりました。既存の NGSI インタフェースにより、複雑なクエリを作成し、結果をフィルタリングすることができます。

現時点では、ストア・ファインダのデモでは、すべてのコンテキスト・データが HTTP リクエストを介して直接追加されていますが、より複雑なスマートなソリューションでは、Orion Context Broker は各エンティティに関連付けられたセンサーからコンテキストを直接取得します。

いくつかの例を示します。それぞれの場合、options=keyValues クエリ・パラメータは、各属性からタイプ要素を取り除いてレスポンスを短縮するために使用されています。

id でエンティティ・データを取得¶

この例では、 urn:ngsi-ld:Store:001 のデータを返します

4 リクエスト :¶

curl -G -X GET \
   'http://localhost:1026/v2/entities/urn:ngsi-ld:Store:001' \
   -d 'options=keyValues'

レスポンス :¶

options=keyValues を使用しているため、レスポンスは属性 type 要素と metadata 要素を含まない JSON のみで構成されます。

{
    "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 エンティティのデータを返します。type パラメータは、レスポンスを Store エンティティのみに制限します。

5 リクエスト :¶

curl -G -X GET \
    'http://localhost:1026/v2/entities' \
    -d 'type=Store' \
    -d 'options=keyValues'

レスポンス :¶

options=keyValues を使用しているため、レスポンスは属性 type 要素と metadata 要素を含まない JSON のみで構成されます。

[
    {
        "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"
    }
]

属性の値を比較してコンテキスト・データをフィルタリング¶

この例では、name 属性 CheckpointMarkt を持つすべてのストアを返します。フィルタリングは q パラメータを使用して実行できます。文字列にスペースが含まれている場合は、URL エンコードして、一重引用符 ' = %27 で囲むことができます。

6 リクエスト:¶

curl -G -X GET \
    'http://localhost:1026/v2/entities' \
    -d 'type=Store' \
    -d 'q=name==%27Checkpoint%20Markt%27' \
    -d 'options=keyValues'

レスポンス:¶

options=keyValues を使用しているため、レスポンスは属性 type 要素と metadata 要素を含まない JSON のみで構成されます。

[
    {
        "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 地区にあるすべてのストアを返します

フィルタリングは q パラメータを使用して実行できます-サブ属性はドット構文を使用して注釈が付けられます。例えば address.addressLocality

7 リクエスト :¶

curl -G -X GET \
    'http://localhost:1026/v2/entities' \
    -d 'type=Store' \
    -d 'q=address.addressLocality==Kreuzberg' \
    -d 'options=keyValues'

レスポンス :¶

options=keyValues を使用しているため、レスポンスは属性 type 要素と metadata 要素を含まない JSON のみで構成されます。

[
    {
        "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"
    }
]

メタデータをクエリしてコンテキスト・データをフィルタリング¶

この例では、確認済みのアドレス (verified address) を持つすべての Store エンティティのデータを返します。

メタデータのクエリは、mq パラメータを使用して行うことができます。

8 リクエスト :¶

curl -G -X GET \
    'http://localhost:1026/v2/entities' \
    -d 'type=Store' \
    -d 'mq=address.verified==true' \
    -d 'options=keyValues'

レスポンス :¶

options=keyValues を使用しているため、レスポンスは属性 type 要素と metadata 要素を含まない JSON のみで構成されます。

[
    {
        "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"
    },
    {
        "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)

:nine リクエスト :¶

curl -G -X GET \
  'http://localhost:1026/v2/entities' \
  -d 'type=Store' \
  -d 'georel=near;maxDistance:1500' \
  -d 'geometry=point' \
  -d 'coords=52.5162,13.3777' \
  -d 'options=keyValues'

レスポンス :¶

options=keyValues を使用しているため、レスポンスは属性 type 要素と metadata 要素を含まない JSON のみで構成されます。

[
    {
        "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"
    }
]

このシリーズの他のチュートリアルを読むことで見つけることができます :

101. Getting Started
102. Entity Relationships
103. CRUD Operations
104. Context Providers
105. Altering the Context Programmatically
106. Subscribing to Changes in Context

201. Introduction to IoT Sensors
202. Provisioning an IoT Agent
203. IoT over MQTT
204. Using an alternative IoT Agent
205. Creating a Custom IoT Agent
250. Introduction to Fast-RTPS and Micro-RTPS

301. Persisting Context Data using Apache Flume (MongoDB, MySQL, PostgreSQL)
302. Persisting Context Data using Apache NIFI (MongoDB, MySQL, PostgreSQL)
303. Querying Time Series Data (MongoDB)
304. Querying Time Series Data (CrateDB)
305. Big Data Analysis (Flink)

401. Managing Users and Organizations
402. Roles and Permissions
403. Securing Application Access
404. Securing Microservices with a PEP Proxy
405. XACML Rules-based Permissions
406. Administrating XACML via a PAP

501. Creating Application Mashups
503. Introduction to Media Streams
507. Cloud-Edge Computing

601. Introduction to Linked Data
602. Linked Data Relationships and Data Models
603. Traversing Linked Data Programmatically
604. Linked Data Subscriptions and Registrations

全てのドキュメントはここにあります。

反復型開発¶

ストア・ファインダ・デモのコンテキストは非常にシンプルです。各ストアの現在の在庫数をコンテキスト・データとして Orion Context Broker に渡すことで、在庫管理システム全体を簡単に拡張することができます。

これまでのところ単純ですが、このスマート・アプリケーションをどのように反復できるかを考えてみましょう :

ビジュアライゼーション・コンポーネントを使用して各ストアの在庫状態を監視するリアルタイム・ダッシュボードを作成することができます。[Wirecloud]
倉庫とストアの現在のレイアウトを Context Broker に渡すことができるので、在庫の場所を地図上に表示することができます。[Wirecloud]
ストア管理者のみがアイテムの価格を変更できるように、ユーザ管理コンポーネント [Wilma, AuthZForce, Keyrock] を追加することができます
棚が空でないことを保証して商品が販売するので、倉庫内で閾値警報を発生させることができます。[publish/subscribe function of Orion Context Broker]
倉庫から積み込まれるアイテムの生成された各リストは、補充の効率を最大にするために計算することができます。[Complex Event Processing - CEP]
入り口にモーション・センサーを追加して顧客数をカウントすることもできます。[IDAS]
顧客がと入店するたびに、モーション・センサーがベルを鳴らすことができます。[IDAS]
各ストアにビデオ・フィードを導入するための一連のビデオカメラを追加することができます。[Kurento]
ビデオ画像を顧客が店内に立っている場所を認識するために処理することができます。[Kurento]
システム内の履歴データを維持し、処理することによって、顧客の足跡と滞留時間を計算することができます。ストアのどの領域が最も関心を集めているかを確認することができます。[connection through Cygnus to Apache Flink]
異常な行動を認識したパターンは、盗難を避けるために警告を発するのに使用することができます。[Kurento]
群衆の移動に関するデータは、科学的研究に有用です。ストアの状態に関するデータは、外部に公開することができます。[extensions to CKAN]

アーキテクチャ¶

前提条件¶

Docker¶

Docker Compose (オプション)¶

コンテナの起動¶

オプション 1) Docker コマンドを直接使用¶

オプション 2) Docker Compose を使用¶

最初の "Powered by FIWARE" アプリを作成¶

サービスの状態を確認¶

1 リクエスト :¶

レスポンス :¶

コンテキスト・データの作成¶

2 リクエスト :¶

3 リクエスト :¶

データモデルのガイドライン¶

すべての用語はアメリカ英語で定義されています¶

エンティティ・タイプの名前は大文字で始まる必要があります¶

エンティティ ID は、NGSI-LD のガイドラインに従った URN でなければなりません¶

データ・タイプ名は、可能であれば schema.org データ・タイプを再利用する必要があります¶

属性名にはキャメルケースの構文を使用します¶

位置情報は address および location 属性を使用して定義する必要があります¶

GeoJSON を使用して地理空間プロパティをコード化¶

属性メタデータ¶

コンテキスト・データのクエリ¶

id でエンティティ・データを取得¶

4 リクエスト :¶

レスポンス :¶

タイプ別にエンティティ・データを取得¶

5 リクエスト :¶

レスポンス :¶

属性の値を比較してコンテキスト・データをフィルタリング¶

6 リクエスト:¶

レスポンス:¶

サブ属性の値を比較してコンテキスト・データをフィルタリング¶

7 リクエスト :¶

レスポンス :¶

メタデータをクエリしてコンテキスト・データをフィルタリング¶

8 リクエスト :¶

レスポンス :¶

geo:json 属性の値を比較してコンテキスト・データをフィルタリング¶

:nine リクエスト :¶

レスポンス :¶

反復型開発¶

各反復は、標準インタフェースを備えた既存のコンポーネントを介してソリューションに付加価値を与え、開発時間を最小限に抑えます。¶

License¶

位置情報は `address` および `location` 属性を使用して定義する必要があります¶