FIWARE Banner

FIWARE Core Context Management License: MIT NGSI v1 Support badge NGSI v2
Documentation

このチュートリアルでは、FIWARE ユーザにコンテキスト・データとコンテキスト・プロ バイダについて説明しています。チュートリアルは、以前 の在庫管理の例で作成され た Store エンティティをベースにしていて、ユーザは、Orion Context Broker 内で 直接保持されていないストアに関するデータを取得できます。

このチュートリアルでは、cUrl コマンドを使用していますが 、Postman documentation も利用できます。

Run in Postman


コンテキスト・データとコンテキスト・プロバイダ

"知識には二つのタイプがある。物事を知っているということ。もう一つはどこを探す べきかを知っているということ。"

— Samuel Johnson (Boswell's Life of Johnson)

FIWARE プラットフォーム内では、エンティティは、実世界に存在する物理的または概念 的オブジェクトの状態を表します。たとえば、Store は実際のレンガやモルタルの建 物です。

そのエンティティのコンテキスト・データは、与えられた瞬間における実世界オブジェク トの状態を定義します。

これまでのチュートリアルでは、Orion Context Broker 内の Store エンティティの コンテキスト・データをすべて保持しています。たとえば、ストアには次のような属性が あります :

  • id : ストアの一意の識別子。たとえば、urn:ngsi-ld:Store:002
  • name : ストアの名前。たとえば、"Checkpoint Markt"
  • address :ストアの住所。たとえば、 "Friedrichstraße 44, 10969 Kreuzberg, Berlin"
  • location : ストアの物理的な場所。たとえば、52.5075 N, 13.3903 E

ご覧のように、これらの属性のほとんどは完全に静的 (場所など) で、他のものは定期的 に変更されることはありませんが、ストリートの名前を変更したり、ストアの名を変更す ることができます。

しかし、Store エンティティに関する別のクラスのコンテキスト・データがあります 。これは、より動的な情報です。たとえば、次のような情報があります :

  • temperature : ストアの現在の温度
  • relativeHumidity : ストアの現在の相対湿度
  • tweets : ストアに関する最近のソーシャルメディアのつぶやき

この情報は常に変化しており、静的にデータベースに保持されている場合、データは常に 古くなります。コンテキスト・データを最新に保ち、オンデマンドでシステムの現在の状 態を取得できるようにするには、エンティティのコンテキストがリクエストされるたびに 、これらの動的データ属性の新しい値を取得する必要があります。

スマートなソリューションは、現実世界の現状に対応するように設計されています。ソー シャルメディア, IoT センサー, ユーザ入力などの外部ソースからの動的なデータ読み取 りに依存しているため、それらは "aware" (アウェア)です。FIWARE プラットフォームは 、リアルタイム・コンテキスト・データの収集と提示を透過的にします。Orion Context Broker に対して NGSI リクエストが行われるたびに、登録された外部コンテキスト・プロバイダからのリアルタ イム・データ読み取りと一緒に、データベース内に保持されているデータを結合すること によって常に最新のコンテキストを戻すからです。

Orion Context Broker は、これらのリクエストを満たすために、まず次の 2 種類の情報 を提供する必要があります :

  • Orion 自体で保持された静的コンテキスト・データ。 Orion が知っている ("knows") エンティティ
  • 既存のエンティティに関連付けられた登録済みの外部コンテキストプロバイダ 。Orion が情報を見つけることができる ("find information" )エンティティ

在庫管理システム内のエンティティ

私たちの簡単な在庫管理システムで、Store エンティティは、id, name, address および location 属性を返します。我々は、以下の無料で公開されているの データソースからのリアルタイムのコンテキスト・データを追加してこれを補強します :

エンティティ間のリレーションシップは、次のように定義されます :

アーキテクチャ

このアプリケーションは 、Orion Context Broker という 1 つの FIWARE コンポーネントしか使用しません。アプリケーションが "Powered by FIWARE" と認定するには、Orion Context Broker を使用するだけで十分 です。

現在、Orion Context Broker はオープンソースの MongoDB 技術を利用して、コンテキスト・データの永続性 を維持しています。外部ソースからコンテキスト・データをリクエストするには、単純な コンテキスト・プロバイダ NGSI プロキシを追加する必要があります。

したがって、アーキテクチャは 3 つの要素で構成されます :

  • NGSI を使用してリ クエストを受信する Orion Context Broker
  • バックエンドの MongoDB データベース
    • Orion Context Broker が、データ・エンティティなどのコンテキスト・データ 情報、サブスクリプション、登録などを保持するために使用します
  • コンテキスト・プロバイダ NGSI proxy は次のようになります :
    • NGSI を使用し てリクエストを受信する
    • 独自の API を独自のフォーマットで使用して、公開されているデータソースへ のリクエストを行います
    • NGSI 形式でコ ンテキスト・データを Orion Context Broker に返します

要素間のすべての対話は HTTP リクエストによって開始されるため、エンティティはコン テナ化され、公開されたポートから実行されます。

コンテキスト・プロバイダ NGSI proxy に必要な設定情報は、関連する docker-compose.yml ファイルの services セクションにあります:

tutorial:
    image: fiware/tutorials.context-provider
    hostname: context-provider
    container_name: fiware-tutorial
    networks:
        - default
    expose:
        - "3000"
    ports:
        - "3000:3000"
    environment:
        - "DEBUG=tutorial:*"
        - "PORT=3000"
        - "CONTEXT_BROKER=http://orion:1026/v2"
        - "OPENWEATHERMAP_KEY_ID=<ADD_YOUR_KEY_ID>"
        - "TWITTER_CONSUMER_KEY=<ADD_YOUR_CONSUMER_KEY>"
        - "TWITTER_CONSUMER_SECRET=<ADD_YOUR_CONSUMER_SECRET>"

tutorial コンテナは以下のように環境変数によってドライブされます:

Key Value Description
DEBUG tutorial:* ロギングに使用されるデバッグフラグです
WEB_APP_PORT 3000 データを表示するためにコンテキスト・プロバイダ NGSI proxy と Web アプリケーションで使用されるポート
CONTEXT_BROKER http://orion:1026/v2 コンテキストを更新するために接続する Context Broker の URL
OPENWEATHERMAP_KEY_ID <ADD_YOUR_KEY_ID> Open Weather Map API へのアクセスを得るために使用されるコンシューマ・キー
TWITTER_CONSUMER_KEY <ADD_YOUR_CONSUMER_KEY> Twitter API へのアクセスを得るために使用されるコンシューマ・キー
TWITTER_CONSUMER_SECRET <ADD_YOUR_CONSUMER_SECRET> Twitter API へのアクセスを得るために使用されるユーザ・キー

このチュートリアルでは、YAML ファイルに記述されている他の tutorial コンテナの 設定値は使用していません。

MongoDB と Orion Context Broker の設定情報については 、以前のチュートリアルで 説明しました。

前提条件

Docker

物事を単純にするために、両方のコンポーネントは Docker を使用して実行されます。Docker は、さまざまコンポーネントをそれぞれの環境に 分離することを可能にするコンテナ・テクノロジです。

  • Docker を Windows にインストールするには 、こちらの手順に従ってくださ い
  • Docker を Mac にインストールするには 、こちらの手順に従ってください
  • Docker を Linux にインストールするには 、こちらの手順に従ってください

Docker Compose は、マルチコンテナ Docker アプリケーションを定義して実行する ためのツールです 。YAML file ファイルは、アプリケーションのために必要なサービスを構成するために使用します。つ まり、すべてのコンテナ・サービスは 1 つのコマンドで呼び出すことができます 。Docker Compose は、デフォルトで Docker for Windows と Docker for Mac の一部と してインストールされますが、Linux ユーザ はここに記載されている手順に従う必要 があります。

次のコマンドを使用して、現在の Docker バージョンと Docker Compose バージ ョンを確認できます :

docker-compose -v
docker version

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

Cygwin

シンプルな Bash スクリプトを使用してサービスを開始します。Windows ユーザは cygwin をダウンロードして、Windows の Linux ディストリ ビューションに似たコマンドライン機能を提供する必要があります。

コンテキスト・プロバイダ NGSI プロキシ

単純な nodejs Express アプリケ ーションが、リポジトリの一部としてバンドルされています。このアプリケーションは 、4 つの異なるコンテキスト・プロバイダに対して NGSI v1 インターフェイスを提供し ます。Open Weather Map API, Twitter Search API と 、2 つのダミーデータのコンテキ スト・プロバイダである、いつも同じデータを返すスタティック・データのプロバイダと 、呼び出されるたびに値が変わるランダム・データのコンテキスト・プロバイダです。

プロキシ・エンドポイントに関する詳細は 、こちらを 参照してください。

  • Open Weather Map API にアクセスするには、<https://openweathermap.org/api> でキーを申請する必要があります
  • Twitter Search API にアクセスするには、https://developer.twitter.com/ から Twitter でアプリを作成し 、コンシューマ・キーとコンシューマ・シークレットを 取得する必要があります

docker-compose.yml のリポジトリのルートにあるプレースホルダを、アプリケーショ ン用に取得した値に置き換えます :

environment:
    - "DEBUG=tutorial:*"
    - "CONTEXT_BROKER=http://orion:1026/v2"
    - "OPENWEATHERMAP_KEY_ID=<ADD_YOUR_KEY_ID>"
    - "TWITTER_CONSUMER_KEY=<ADD_YOUR_CONSUMER_KEY>"
    - "TWITTER_CONSUMER_SECRET=<ADD_YOUR_CONSUMER_SECRET>"

API キーにサインアップしたくない場合は、代わりにランダム・データ・コンテキスト・ プロバイダのデータを使用できます。

起動

リポジトリ内で提供される bash スクリプトを実行すると、コマンドラインからすべての サービスを初期化できます。リポジトリを複製し、以下のコマンドを実行して必要なイメ ージを作成してください :

git clone git@github.com:FIWARE/tutorials.Context-Providers.git
cd tutorials.Context-Providers

./services create; ./services start;

このコマンドは、起動時に以前 の在庫管理の例からシード ・データをインポートします。

コンテキスト・プロバイダの使用

ヘルスチェック

nodejs proxy アプリケーションは、4 つのコンテキスト・プロバイダのそれぞれに health エンドポイントを提供します。適切なエンドポイントにリクエストを行うと、 プロバイダが実行中であり、外部データを受信できるかどうかがチェックされます。アプ リケーションはポート 3000 で実行されます。

スタティック・データのコンテキスト・プロバイダ (ヘルスチェック)

この例では、スタティック・データのコンテキスト・プロバイダのエンドポイントの状態 を返します。

エラーでないレスポンスの場合、NGSI プロキシがネットワーク上で利用可能であり、値 を返すことを示しています。各リクエストは同じデータを返します。

1 リクエスト :

curl -X GET \
  'http://localhost:3000/health/static'

レスポンス :

{
    "array": ["Arthur", "Dent"],
    "boolean": true,
    "number": 42,
    "structuredValue": { somevalue: 'this' },
    "text": "I never could get the hang of Thursdays"
}

ランダムデータのコンテキスト・プロバイダ (ヘルスチェック)

この例では、ランダム・データ・ジェネレータのコンテキスト・エンドポイントの正常性 を返します。

エラーでないレスポンスの場合、NGSI プロキシがネットワーク上で利用可能であり、値 を返すことを示しています。各リクエストはランダムなダミー・データを返します。

2 リクエスト :

curl -X GET \
  'http://localhost:3000/health/random'

レスポンス :

{
    "array": ["sit", "consectetur", "sint", "excepteur"],
    "boolean": false,
    "number": 4,
    "structuredValue": { somevalue: 'this' },
    "text": " nisi reprehenderit pariatur. Aute ea"
}

Twitter API コンテキスト・プロバイダ (ヘルスチェック)

この例は、Twitter API コンテキスト・プロバイダのエンドポイントの正常性を返します 。

エラーでないレスポンスの場合、NGSI プロキシがネットワーク上で利用可能であり、値 を返すことを示しています。

プロキシが Twitter API に接続するように正しく設定されている場合は、一連のツイー トが返されます。

Twitter API は OAuth2 を使用します :

  • Twitter API のコンシューマ・キーとコンシューマ・シークレットを取得するには 、https://developer.twitter.com/ から Twitter でアプリを作成する必要があり ます。その後、コンシューマ・キーとコンシューマ・シークレットを含むページに移 動します
  • 詳細は https://developer.twitter.com/ を参照してください。

3 リクエスト :

curl -X GET \
  'http://localhost:3000/health/twitter'

レスポンス :

このレスポンスには、FIWARE に関する 15 のツイートが含まれます。完全なレスポンス はかなり長いですが、断片は以下のようなものです :

{
    "statuses": [
    {
        "created_at": "Mon Apr 23 13:08:35 +0000 2018",
        "id": 988404265227038700,
        "id_str": "988404265227038721",
        "text": "@FIWARE: Full house today during the Forum Industrie 4.0 at @Hannover_Messe as #FIWARE Foundation CEO ...",
        "truncated": false,
        "entities": {
            ... ETC
        },
        "metadata": {
            ... ETC
        }
        ... ETC
    }
    ... ETC

    ],
    "search_metadata": {
        "completed_in": 0.089,
        "max_id": 988407193497108500,
        "max_id_str": "988407193497108481",
        "next_results": "?max_id=988373340074242048&q=FIWARE&include_entities=1",
        "query": "FIWARE",
        "refresh_url": "?since_id=988407193497108481&q=FIWARE&include_entities=1",
        "count": 15,
        "since_id": 0,
        "since_id_str": "0"
    }

}

詳細から分かるように、各ツイートの textは、statuses 配列内にあります。

Weather API コンテキスト・プロバイダ (ヘルスチェック)

この例では、スタティック・データのコンテキスト・プロバイダのエンドポイントの状態 を返します。

エラーでないレスポンスの場合、NGSI プロキシがネットワーク上で利用可能であり、値 を返すことを示しています。各リクエストは同じデータを返します。

4 リクエスト :

curl -X GET \
  'http://localhost:3000/health/weather'

レスポンス :

レスポンスには、ベルリンの現在の天気に関するデータが含まれます。完全なレスポンス はかなり長いですが、断片は以下のようなものです :

{
  "coord": {
    "lon": 13.39,
    "lat": 52.52
  },
  "weather": [
    {
      "id": 800,
      "main": "Clear",
      "description": "clear sky",
      "icon": "01d"
    }
  ],
  "base": "stations",
  "main": {
    "temp": 299.64,
    "pressure": 1019,
    "humidity": 36,
    "temp_min": 299.15,
    "temp_max": 300.15
  },
  ...ETC
  "id": 2950159,
  "name": "Berlin",
  "cod": 200
}

ご覧のように、現在の温度と相対湿度の詳細は、 current_observation 属性内にあり ます。

NGSI v1 QueryContext エンドポイントへのアクセス

コンテキスト・プロバイダの 3000 ポートは Docker コンテナの外部に公開されている ため、curl はコンテキスト・プロバイダに直接リクエストを行うことができます。これ は、Orion Context Broker によって行われたリクエストをシミュレートします 。appropriate/curl の Docker イメージを実行することによって、Docker コンテナ・ ネットワークの一部としてリクエストを作成することもシミュレートできます。

まず、Docker コンテナ内で使用されているネットワークの名前を取得します :

docker network ls

次に、--network パラメータを含む次の curl コマンドを実行します :

docker run --network fiware_default --rm appropriate/curl \
  -X GET 'http://context-provider:3000/health/random'

ご覧のとおり、ネットワーク内では、コンテキスト・プロバイダのホスト名は context-provider です。

単一の属性値の取得

この例では、NGSI v1 queryContext エンドポイントを使用して、スタティック・デー タ・ジェネレータのコンテキスト・プロバイダから temperature の読み取りをリクエ ストします。リクエストされた属性は、POST ボディの attributes 配列内にあります 。

Orion Context Broker は、コンテキスト・プロバイダが登録されると、この queryContext エンドポイントに同様のリクエストを行います。

5 リクエスト :

curl -iX POST \
  'http://localhost:3000/proxy/v1/static/temperature/queryContext' \
  -H 'Content-Type: application/json' \
  -d '{
    "entities": [
        {
            "type": "Store",
            "isPattern": "false",
            "id": "urn:ngsi-ld:Store:001"
        }
    ],
    "attributes": [
        "temperature"
    ]
} '

レスポンス :

レスポンスは NGSI v1 レスポンス形式で示されます。attributes 要素は、返されたデ ータの value:42 を持つ type:Number オブジェクトを保持しています。

{
    "contextResponses": [
        {
            "contextElement": {
                "attributes": [
                    {
                        "name": "temperature",
                        "type": "Number",
                        "value": 42
                    }
                ],
                "id": "urn:ngsi-ld:Store:001",
                "isPattern": "false",
                "type": "Store"
            },
            "statusCode": {
                "code": "200",
                "reasonPhrase": "OK"
            }
        }
    ]
}

複数の属性値の取得

Orion Context Broker が複数のデータ値をリクエストすることは可能です。この例では 、NGSI v1 queryContext エンドポイントを使用して、ランダム・データ・ジェネレー タのコンテキスト・プロバイダからtemperaturerelativeHumidity の読み取りを リクエストします。リクエストされた属性は、POST ボディの attributes 配列内にあ ります。

6 リクエスト :

curl -iX POST \
  'http://localhost:3000/proxy/v1/random/weatherConditions/queryContext' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: 2ae9e6d6-802b-4a62-a561-5c7739489fb3' \
  -d '{
    "entities": [
        {
            "type": "Store",
            "isPattern": "false",
            "id": "urn:ngsi-ld:Store:001"
        }
    ],
    "attributes": [
        "temperature",
        "relativeHumidity"
    ]
}'

レスポンス :

レスポンスは NGSI v1 レスポンス形式で示されます。attributes 要素は、返されたデ ータを保持しています。

{
    "contextResponses": [
        {
            "contextElement": {
                "attributes": [
                    {
                        "name": "temperature",
                        "type": "Number",
                        "value": 27
                    },
                    {
                        "name": "relativeHumidity",
                        "type": "Number",
                        "value": 21
                    }
                ],
                "id": "urn:ngsi-ld:Store:001",
                "isPattern": "false",
                "type": "Store"
            },
            "statusCode": {
                "code": "200",
                "reasonPhrase": "OK"
            }
        }
    ]
}

コンテキスト・プロバイダの登録アクション

すべてのコンテキスト・プロバイダの登録アクションは、v2/registrations エンドポ イントで行われます。標準の CRUD マッピングが適用されます :

  • Creation (作成) は HTTP POST にマップされます
  • Reading/Listing (読み込み/一覧) は HTTP GET にマップされます
  • Deletin (削除) は HTTP DELETE にマップされます

新しいコンテキスト・プロバイダの登録

この例では、ランダム・データのコンテキスト・プロバイダを Orion Context Broker に 登録します。

リクエストのボディには、"URL http://context-provider:3000/proxy/v1/random/weatherConditions は、 id=urn:ngsi-ld:Store:001 と呼ばれるエンティティ の relativeHumiditytemperature データ を提供することができます" と記述します。

値は決して、 Orion 内に保持されず、登録されたコンテキスト・プロバイダからの 要求に応じて常にリクエストされます。Orion は、どのコンテキスト・プロバイダがコン テキスト・データを提供できるかについての登録情報を保持するだけです。

"legacyForwarding": true フラグがあると、登録されたコンテキスト・プロバイダが NGSI v1 インターフェイスを提供していることを示します。したがって、Orion は 、http://context-provider:3000/proxy/v1/random/weatherConditions/queryContext 形式のデータを POST でリクエストし、NGSI v1 形式のデータを受け取ります。

: Weather API に登録している場合、provider の中に 次の url を置くこと で、Berlin の temperaturerelativeHumidity のライブ値を取得することがで きます :

  • http://context-provider:3000/proxy/v1/weather/weatherConditions

このリクエストは、201 - Created レスポンス・コードとともに返されます。レスポ ンスの Location ヘッダには、Orion で保持されている登録レコードへのパスが含まれ ています :

7 リクエスト :

curl -iX POST \
  'http://localhost:1026/v2/registrations' \
  -H 'Content-Type: application/json' \
  -d '{
  "description": "Relative Humidity Context Source",
  "dataProvided": {
    "entities": [
      {
        "id": "urn:ngsi-ld:Store:001",
        "type": "Store"
      }
    ],
    "attrs": [
      "relativeHumidity"
    ]
  },
  "provider": {
    "http": {
      "url": "http://context-provider:3000/proxy/v1/random/weatherConditions"
    },
     "legacyForwarding": true
  }
}'

コンテキスト・プロバイダが登録されると、/entities/<entity-id> エンドポイントを 使用して、Store エンティティのコンテキスト urn:ngsi-ld:Store:001 がリクエ ストされた場合、新しいコンテキスト・データがインクルードされます :

8 リクエスト :

curl -X GET \
  'http://localhost:1026/v2/entities/urn:ngsi-ld:Store:001?type=Store'

レスポンス :

{
    "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": {}
    },
    "location": {
        "type": "geo:json",
        "value": {
            "type": "Point",
            "coordinates": [13.3986, 52.5547]
        },
        "metadata": {}
    },
    "name": {
        "type": "Text",
        "value": "Bösebrücke Einkauf",
        "metadata": {}
    },
    "temperature": {
        "type": "Number",
        "value": "22.6",
        "metadata": {}
    },
    "relativeHumidity": {
        "type": "Number",
        "value": "58%",
        "metadata": {}
    }
}

同様に、単一の属性は、 /entities/<entity-id>/attrs/<attribute> にリクエストす ることで取得できます。

9 リクエスト :

curl -X GET \
  'http://localhost:1026/v2/entities/urn:ngsi-ld:Store:001/attrs/relativeHumidity/value'

レスポンス :

"58%"

登録されたコンテキスト・プロバイダの読み込み

この例では、id が 5addeffd93e53f86d8264521 の登録データをコンテキストから読み込 みます。

登録データは、/v2/registrations/<entity> エンドポイントに GET リクエストを行う ことで取得できます。

19 リクエスト :

curl -X GET \
  'http://localhost:1026/v2/registrations/5ad5b9435c28633f0ae90671'

登録されているすべてのコンテキスト・プロバイダの一覧

この例では、登録されているすべてのコンテキスト・プロバイダをリストします。

指定されたエンティティ・タイプの完全なコンテキスト・データは 、/v2/registrations/ エンドポイントに GET リクエストを行うことで取得できます。

11 リクエスト :

curl -X GET \
  'http://localhost:1026/v2/registrations'

レスポンス :

[
    {
        "id": "5addeffd93e53f86d8264521",
        "description": "Random Weather Conditions",
        "dataProvided": {
            "entities": [
                {
                    "id": "urn:ngsi-ld:Store:002",
                    "type": "Store"
                }
            ],
            "attrs": ["temperature", "relativeHumidity"]
        },
        "provider": {
            "http": {
                "url": "http://context-provider:3000/proxy/v1/random/weatherConditions"
            },
            "supportedForwardingMode": "all",
            "legacyForwarding": true
        },
        "status": "active"
    }
]

登録済みのコンテキスト・プロバイダの削除

登録は、/v2/registrations/<entity>エンドポイントに DELETE リクエストを行うこと によって削除できます。

curl -iX DELETE \
  'http://localhost:1026/v2/registrations/5ad5b9435c28633f0ae90671'

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


License

MIT © 2018-2019 FIWARE Foundation e.V.