このチュートリアルでは、リンクト・データ (Linked Data) の概念を FIWARE プラットフォームに導入します。スーパーマーケット・チェーンのストア・ファインダ・アプリケーションは NGSI-LD を使用して再作成されます。NGSI v2 と NGSI-LD インターフェースの違いが強調され、説明されています。このチュートリアルは最初のチュートリアルと直接類似していますが、 NGSI-LD インターフェースからの API 呼び出しを使用します。

チュートリアルでは cUrl コマンドを使用していますが、 Postman のドキュメントとしても入手できます。

⚠️ 注: このチュートリアルは、システムを NGSI-LD に切り替えたりアップグレードしたりする NGSI-v2 開発者向けに設計されています。リンクト・データシステムを最初から構築する場合、または NGSI-v2 にまだ慣れていない場合は、 NGSI-LD 開発者向けチュートリアルのドキュメントを参照することをお勧めします。

FIWARE データ・エンティティへのリンクト・データの概念の追加¶

“Six degrees of separation doesn't mean that everyone is linked to everyone else in just six steps. It means that a very small number of people are linked to everyone else in a few steps, and the rest of us are linked to the world through those special few.”

― Malcolm Gladwell, The Tipping Point

FIWARE 入門のチュートリアルの紹介では、コンテキスト・データ・エンティティの作成と操作に一般的に使用される NGSI v2 インターフェイスを紹介しました。このインターフェースの進化は、リンクト・データの概念を追加しながらコンテキスト・データ・エンティティを強化するためのメカニズムとして NGSI-LD と呼ばれる補足仕様を作成しました。このチュートリアルでは、新しいインターフェイスの背景にあるアイデアを紹介し、リンクされたデータとしてデータ・エンティティを作成および操作する方法を比較対照します。

このシリーズのその他のチュートリアルでは、データのリレーションシップ、およびリンクト・データを使用してコンテキスト・データ・エンティティを作成し、完全なナレッジ・グラフをトラバースする方法についてさらに説明します。

リンクト・データとは何ですか？¶

インターネットのすべてのユーザはハイパーテキスト・リンクの概念に精通しているでしょう。これは、ある Web ページ上のリンクが既知の場所から別のページをロードするようにブラウザを導くことができる方法です。

人間はリレーションシップの発見の可能性とリンクがどのように機能するかを理解することができますが、コンピュータはこれをはるかに困難に感じ、別の場所に保持されているデータ要素間を移動できるように明確なプロトコルを必要とします。

コンピュータ用の読み取り可能なリンクのシステムを作成するには、データ自体からプログラム的にセマンティックな意味を取得できるように明確に定義されたデータ・フォーマット (JSON-LD) を使用し、両方のデータ・エンティティとエンティティ間のリレーションシップに一意の IDs (URL またはURN) を割り当てる必要がありますが必要です。

正しく定義されたリンクト・データを使用してビッグデータの質問に答えることができます。また、"Store X の棚で現在入手可能な製品とその価格は何ですか？" などの質問にデータのリレーションシップをたどることができます。

ビデオ : リンクト・データとは何ですか？¶

リンクト・データの概念を説明したビデオを見るには、上の画像をクリックしてください。

JSON-LD は JSON を拡張したもので、リンクト・データを JSON で表現するときのあいまいさを避けるための標準的な方法であり、データはマシンによって解析可能な形式で構造化されます。これは、各属性が何を意味するのかについて異なる考えを持つ可能性がある、多数の別々のデータ・ソースから取得されたときにすべてのデータ属性を簡単に比較できるようにする方法です。たとえば、 2つのデータ・エンティティが name 属性を持っているとき、コンピュータは同じ意味で (Username や Surname、何かではなく) "Name of a thing" を参照することが確実にできます。URL とデータ・モデルは、属性が短い形式 (name のような) と完全に指定された長い形式 (http://schema.org/name のような) の両方を持つことを可能にすることによってあいまいさを取り除くために使われます。

JSON-LD は @context 要素の概念を導入します。これはコンピュータが残りのデータをより明快かつ深く解釈できるようにする追加情報を提供します。

さらに JSON-LD 仕様では、明確に定義されたデータ・モデルをデータ自体に関連付ける独自の @type を定義できます。

ビデオ : JSON-LD とは何ですか？¶

JSON-LD の背後にある基本概念を説明したビデオを見るには、上の画像をクリックしてください。

NGSI-LD とは何ですか？¶

NGSI-LD は、リンクト・データ (エンティティのリレーションシップ)、プロパティ・グラフ、およびセマンティクス (JSON-LD が提供する機能を利用) のサポートを改善するために修正された NGSI v2 情報モデルの進化です。この作業は ETSI ISG CIM イニシアチブの下で行われており、更新された仕様は NGSI-LD としてブランド設定されています。NGSI-LD の主な構成要素は、Entity, Property および Relationship です。NGSI-LD エンティティ (インスタンス) は、プロパティまたはリレーションシップの対象になります。伝統的な NGSI v2 データ・モデルに関しては、プロパティは属性とその値の組み合わせと見なすことができます。リレーションシップは、リンクト・データを使用してインスタンス間の関連付けを確立することを可能にします。

NGSI v2 データ・モデル¶

ちなみに、NGSI v2 データ・モデルは非常に単純です。以下のようにまとめることができます :

NGSI v2 の中心的な要素はデータ entity (エンティティ) で、通常は、Store, Shelf などの状態が変化する実際のオブジェクトです。エンティティは name や location などの attributes (属性) を持ち、これらは順番に precision などの metadata (メタデータ)、つまり location の読み取りの正確さを保持します。

すべての entity はエンティティが記述する種類のものを定義する type を持たなければなりませんが、NGSI v2 エンティティに type=Store を与えることは、誰もが自分自身の Store エンティティを同じ方法で形作ることを余儀なくされるように比較的意味がありません。同様に name という名前の属性を追加しても、他の誰かの name 属性と同じデータを突然保持することはありません。

NGSI v2 を使用してリレーションシップを定義することができますが、それは属性に慣例で定義された適切な属性名 (例えば refManagedBy のように ref で始まるもの) を与え、属性 type=Relationship を割り当てます。これも純粋な命名規則で、実際の意味的な重みはありません。

NGSI LD データ・モデル¶

NGSI LD データ・モデルはより複雑で、ナビゲート可能なナレッジ・グラフにつながる、より厳密な使用定義があります。

繰り返しになりますが、entity はコア要素と見なすことができます。すべてのエンティティは、URI (多くの場合 URN) でなければならない一意の id を使用する必要があります。保持されているデータの構造を定義するために使用される type もあります。これも URI でなければなりません。この URI は、Web 上にある明確なデータ・モデルに対応している必要があります。例えば、URI の https://uri.fiware.org/ns/data-models#Building は Building のための共通のデータ・モデルを定義するために使われます。

Entities は、properties と relationships を持つことができます。理想的には、それぞれの property の名前は、ウェブ全体で見いだされる共通の概念に対応する明確に定義された URI であるべきです (例えば、http://schema.org/address はアイテムの物理アドレスのための共通の URI です)。property はそのプロパティの状態を反映する値も持ちます (例えば name="Checkpoint Markt")。最後に、プロパティはそれ自身がプロパティに関するさらなる情報を反映するさらなるプロパティ (別名 properties-of-properties) を持つことができます。プロパティとリレーションシップは、リンクされた埋め込みプロパティ (properties-of-properties または properties-of-relationships または relationships-of-properties または relationships-of-relationships など) を持つことができます :

NGSI LD データ・エンティティ (スーパーマーケットなど) :

一意でなければならない id を持っています。例えば urn:ngsi-ld:Building:store001
明確に定義されたデータ・モデルの完全修飾 URI であるべきである type を持ちます。例えば https://uri.fiware.org/ns/data-models#Building。また、作成者は、JSON-LD @context を介して完全修飾 URIs にマップされた型の短い文字列としてタイプ名を使用できます
エンティティの property を持ちます。例えば、ストアのアドレスを保持する address 属性です。これは http://schema.org/address に展開することができ、これは完全修飾名 (FQN) として知られています
他の property と同様に、address は property の address に対応する value を持ちます。例えば Bornholmer Straß e 65, 10439 Prenzlauer Berg, Berlin
エンティティの property-of-a-property を持ちます。例えば address の Verified フィールドです
エンティティの relationship を持ちます。例えば、managedBy というリレーションシップが他のデータ・エンティティに対応する managedBy フィールド: urn:ngsi-ld:Person:bob-the-manager
リレーションシップ managedBy はそれ自身 property-of-a-relationship (例えば since) を持つことができ、これは Bod がストアの作業を開始した日付を保持します
リレーションシップ managedBy は、それ自身が relationship-of-a-relationship (例えば subordinateTo) を持つことができ、これは階層のボブの上のエリア・マネージャの URN を保持します

ご覧のとおり、ナレッジ・グラフは明確に定義されており、無制限に拡張できます。

リレーションシップについては、以降のチュートリアルで詳しく説明します。

前提条件¶

Docker¶

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

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

Docker Compose は、マルチコンテナ Docker アプリケーションを定義して実行するためのツールです。 YAMLファイルを使用して、アプリケーションに必要なサービスを設定します。これは、すべてのコンテナ・サービスを単一のコマンドで起動できることを意味します。Docker Compose は、Docker for Windows および Docker for Mac の一部としてデフォルトでインストールされますが、Linux ユーザはこちらにある手順に従う必要があります。

Cygwin¶

簡単な bash スクリプトを使ってサービスを開始します。Windows ユーザは、Windows 上の Linux ディストリビューションに似たコマンドライン機能を提供するために cygwin をダウンロードするべきです。

アーキテクチャ¶

デモ・アプリケーションは、準拠している Context Broker と NGSI-LD の呼び出しを送受信します。NGSI v2 と NGSI-LD の両方のインターフェースが Orion Context Broker の実験版で利用可能であるため、私たちのデモ・アプリケーションは1つ FIWARE コンポーネントのみを利用します。

現在、Orion Context Broker は、保持しているコンテキスト・データの永続性を保つためにオープンソースの MongoDB テクノロジに依存しています。したがって、アーキテクチャは2つの要素から構成されます :

NGSI-LD を使ってリクエストを受け取る Orion Context Broker
基礎となる MongoDB データベース :
- データ・エンティティ、サブスクリプション、レジストレーションなどのコンテキスト・データ情報を保持するために Orion Context Broker によって使用されます

2つの要素間のやり取りはすべて HTTP リクエストによって開始されるため、要素をコンテナ化して公開ポートから実行することができます。

必要な設定情報は関連する orion-ld.yml ファイルの services セクションにあります :

orion:
    image: fiware/orion-ld
    hostname: orion
    container_name: fiware-orion
    depends_on:
        - mongo-db
    networks:
        - default
    ports:
        - "1026:1026"
    command: -dbhost mongo-db -logLevel DEBUG
    healthcheck:
        test: curl --fail -s http://orion:1026/version || exit 1

mongo-db:
    image: mongo:4.2
    hostname: mongo-db
    container_name: db-mongo
    expose:
        - "27017"
    ports:
        - "27017:27017"
    networks:
        - default
    command: --nojournal

両方のコンテナは同じネットワーク上に存在します - Orion Context Broker はポート 1026 をリッスンし、MongoDB はデフォルトのポート 27017 をリッスンしています。どちらのコンテナも同じポートを外部に公開しています - これは純粋にチュートリアル・アクセスのためのものです - したがって、cUrl または Postman は同じネットワークの一部でなくてもそれらにアクセスできます。コマンドラインの初期化は一目瞭然です。

入門チュートリアルとの唯一の注目すべき違いは、必要なイメージ名が現在 fiware/orion-ld であるということです。

起動¶

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

git clone https://github.com/FIWARE/tutorials.Linked-Data.git
cd tutorials.Linked-Data
git checkout NGSI-v2

./services orion|scorpio

注 : クリーンアップして最初からやり直す場合は、次のコマンドで実行できます :
./services stop

リンクト・データをベースとした "Powered by FIWARE" アプリの作成¶

このチュートリアルでは、最初の "Powered by FIWARE" スーパーマーケット検索アプリと同じデータ・エンティティを再作成しますが、NGSI v2 ではなく NGSI-LD リンクト・データ・エンティティを使用します。

サービス状態の確認¶

いつものように、公開されたポートに HTTP リクエストをすることで Orion Context Broker が実行されているかどうかを確認できます :

1 リクエスト :¶

curl -X GET \
  'http://localhost:1026/version'

レスポンス :¶

レスポンスは次のようになります :

{
    "orion": {
        "version": "1.15.0-next",
        "uptime": "0 d, 3 h, 1 m, 51 s",
        "git_hash": "af440c6e316075266094c2a5f3f4e4f8e3bb0668",
        "compile_time": "Tue Jul 16 15:46:18 UTC 2019",
        "compiled_by": "root",
        "compiled_in": "51b4d802385a",
        "release_date": "Tue Jul 16 15:46:18 UTC 2019",
        "doc": "https://fiware-orion.readthedocs.org/en/master/"
    }
}

バージョンのレスポンスの形式は変更されていません。release_date は、以下に定義されているリクエストを処理できるようにするために、2019年7月16日以降でなければなりません。

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

リンクト・データ・エンティティを作成するときは、一般的なデータ・モデルを使用することが重要です。これにより、複数のソースからのデータを簡単に結合し、異なるソースからのデータを比較するときのあいまいさを取り除くことができます。

各属性は URI である必要があるため、全体で完全修飾名を使用してリンクト・データを作成するのは困難です。そこで JSON-LD はコンテキスト定義へのポインタを保持できる @context 属性のアイデアを導入しました。 Smart Data Building データ・エンティティを追加するには、次の @context が必要です。

{
    "id": "urn:ngsi-ld:Building:store001",
    "type": "Building",
    ...  other data attributes
    "@context": "https://fiware.github.io/data-models/context.jsonld"
}

コア・コンテキスト¶

https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld は NGSI-LD のコア @context を参照します。これはすべての NGSI エンティティに共通の id や type のような用語を定義し、 Property や Relationship のような用語を定義します。コア・コンテキストは NGSI-LD にとって非常に基本的なもので、デフォルトでリクエストに送信された @context に追加されます。

Smart Data Models¶

https://schema.lab.fiware.org/ld/context は、FIWARE が提供する標準データ・モデルの定義を指します。これを @context に追加すると、GSMA や TM Forum のような他の組織と共同で、 FIWARE Foundation によって定義されたすべてのデータモデルの定義が読み込まれます。 Building に関連する FQNs の概要は以下のようになります :

{
    "@context": {
        "Building": "https://uri.fiware.org/ns/data-models#Building",
        ... etc
        "address": "http://schema.org/address",
        "category": "https://uri.fiware.org/ns/data-models#category",
        "location": "https://uri.etsi.org/ngsi-ld/location",
        "name": "https://uri.etsi.org/ngsi-ld/name",
        ...etc
    }
}

このコンテキスト定義を含めると、エンティティの Building, address, locationに短い名前を使用できるようになりますが、他の情報源と比較するときにコンピュータも FQNs を読み取ることができるようになります。

Context terms are IRIs not URLs¶

JSON-LD仕様によると : "コンテキストは Terms を IRIs にマップするために使用される" ことに注意してください。 - IRI (Internationalized Resource Identifier) は必ずしも URL ではありません - ここを参照してください。したがって、https://uri.etsi.org/ngsi-ld/name などの要素が実際に Web ページに解決されなくても、予期しないことではありません。ただし、http://schema.org/address などの JSON-LD @context ファイル内の多くの IRIs は、実際に、それ自体に関する詳細情報を含む Web ページを返します。

NGSI-LD Core @context を使用する場合、

{
  "@context": {
    "ngsi-ld": "https://uri.etsi.org/ngsi-ld/",
    "geojson": "https://purl.org/geojson/vocab#",
    "id": "@id",
    "type": "@type",
...
    "@vocab": "https://uri.etsi.org/ngsi-ld/default-context/"
  }
}

属性の未解決のショートネームがデフォルトのコンテキストにマッピングされることがわかります:

不明な属性 xxx => https://uri.etsi.org/ngsi-ld/default-context/xxx

そして当然のことながら、これらのデフォルト・コンテキストの IRI は有効な Web ページとしても存在しません。

Context Broker に有効な Building データ・エンティティを作成するには、以下に示すように http://localhost:1026/ngsi-ld/v1/entities エンドポイントに POST リクエストを行います。データ・エンティティが Linked data として認識されるように、適切な Content-Type: application/ld+json も使われることが重要です。

2 リクエスト :¶

curl -iX POST \
  http://localhost:1026/ngsi-ld/v1/entities \
  -H 'Content-Type: application/ld+json' \
  -d '{
    "id": "urn:ngsi-ld:Building:store001",
    "type": "Building",
    "category": {
        "type": "Property",
        "value": ["commercial"]
    },
    "address": {
        "type": "Property",
        "value": {
            "streetAddress": "Bornholmer Straße 65",
            "addressRegion": "Berlin",
            "addressLocality": "Prenzlauer Berg",
            "postalCode": "10439"
        },
        "verified": {
            "type": "Property",
            "value": true
        }
    },
    "location": {
        "type": "GeoProperty",
        "value": {
             "type": "Point",
             "coordinates": [13.3986, 52.5547]
        }
    },
    "name": {
        "type": "Property",
        "value": "Bösebrücke Einkauf"
    },
    "@context": [
        "https://fiware.github.io/data-models/context.jsonld",
        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld"
    ]
}'

Context Broker は @context で言及されているすべてのファイルをナビゲートしてロードしなければならないので、最初のリクエストは時間がかかります。

注: 何らかの理由でリクエストが失敗して、https://schema.lab.fiware.org/ld/context が利用できない場合、 FIWARE データモデル @context の代替コピーは、GitHub の FIWARE データモデルの gh-pages にあります。 @context 値を以下でで置き換えます: https://fiware.github.io/data-models/full-context.jsonld.

稼働中の本番システムでは、サードパーティがコンテキストを確実に読み取ることができるように、@context ファイルが常に利用可能であることが不可欠です。このチュートリアルでは、アーキテクチャをシンプルに保つために、高可用性インフラストラクチャを考慮していません。

3 リクエスト :¶

後続の各エンティティは、与えられた type に対して一意の id を持たなければなりません

curl -iX POST \
  http://localhost:1026/ngsi-ld/v1/entities/ \
  -H 'Content-Type: application/ld+json' \
  -d '{
    "id": "urn:ngsi-ld:Building:store002",
    "type": "Building",
    "category": {
        "type": "Property",
        "value": ["commercial"]
    },
    "address": {
        "type": "Property",
        "value": {
            "streetAddress": "Friedrichstraße 44",
            "addressRegion": "Berlin",
            "addressLocality": "Kreuzberg",
            "postalCode": "10969"
        },
        "verified": {
            "type": "Property",
            "value": true
        }
    },
     "location": {
        "type": "GeoProperty",
        "value": {
             "type": "Point",
              "coordinates": [13.3903, 52.5075]
        }
    },
    "name": {
        "type": "Property",
        "value": "Checkpoint Markt"
    },
    "@context": [
        "https://fiware.github.io/data-models/context.jsonld",
        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld"
    ]
}'

NGSI-LD エンティティ定義内のプロパティの定義¶

id と type 属性は NGSI v2 を使ったことのある人なら誰でも知っているはずで、これらは変わっていません。上記のように、タイプはインクルードされたデータ・モデルを参照するべきです、この場合 Building はインクルードされた URN https://uri.fiware.org/ns/data-models#Building の短い名前として使われています。その後、各 property は2つの属性、 type と value を含む JSON 要素として定義されます。

property 属性の type は以下のいずれかでなければなりません :

"GeoProperty": ロケーションについては"http://uri.etsi.org/ngsi-ld/GeoProperty"。 GeoJSON 形式で経度と緯度のペアとして指定する必要があります。プライマリ・ロケーション属性の推奨名は location です
"Property": "http://uri.etsi.org/ngsi-ld/Property" - 他のすべてのものについては。
時間ベースの値の場合、"Property" も使用されますが、プロパティ値は、 ISO 8601形式にエンコードされた Date, Time または DateTime 文字列でなければなりません。例えば YYYY-MM-DDThh:mm:ssZ

注 : 簡単にするために、このデータ・エンティティには定義されたリレーションシップはありません。リレーションシップは type=Relationship で与えられなければなりません。リレーションシップは次のチュートリアルで議論されます。

NGSI-LD エンティティ定義内の Properties-of-Properties の定義¶

Properties-of-Properties (プロパティのプロパティ) は、メタデータ (つまり、"data about data" (データに関するデータ)) と同等の NGSI-LD です。精度、プロバイダ、使用する単位など、属性値自体のプロパティを記述するために使用されます。いくつかの組み込みメタデータ属性がすでに存在していて、これらの名前は予約されています :

createdAt (type: DateTime): ISO 8601 文字列としての属性作成日
modifiedAt (type: DateTime): ISO 8601 文字列としての属性変更日

さらに observedAt, datasetId, instanceId がオプションで追加される場合もあります。そして location, observationSpace, operationSpace は Geoproperties にとって特別な意味を持ちます。

上記の例では、メタデータの1つの要素 (つまり、property-of-a-property (プロパティのプロパティ)) が address 属性の中にあります。verified フラグは、住所が確認されたかどうかを示します。最も一般的な property-of-a-property は unitCode で、これは測定単位の UN/CEFACT Common Codes を保持するために使用されるべきです。

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

消費アプリケーション (consuming application) は、Orion Context Broker に NGSI-LD HTTP リクエストを送信することで、コンテキスト・データをリクエストできるようになりました。既存の NGSI-LD インタフェースを使用すると、複雑なクエリを実行して結果をフィルタ処理し、FQNs または短い名前でデータを取得できます。

FQN タイプによるエンティティ・データの取得¶

この例では、コンテキスト・データ内のすべての Building エンティティのデータを返します。type パラメータは NGSI-LD では必須であり、レスポンスをフィルタリングするために使用されます。JSON-LD コンテンツを取得するには、Accept HTTP ヘッダが必要です。

4 リクエスト :¶

curl -G -X GET \
  'http://localhost:1026/ngsi-ld/v1/entities' \
  -H 'Accept: application/ld+json' \
  -d 'type=https://uri.fiware.org/ns/data-models%23Building'

レスポンス :¶

レスポンスはデフォルト (https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld) でコアの @context を返し、すべての属性は可能な限り展開されます。

id, type, location, name はコア・コンテキストで定義されており、展開されません
address は http://schema.org/address にマッピングされました
category は https://uri.fiware.org/ns/data-models#category にマッピングされました

エンティティの作成時に属性が FQN に関連付けられていない場合は、短い名前が常に表示されます。

[
    {
        "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld",
        "id": "urn:ngsi-ld:Building:store001",
        "type": "https://uri.fiware.org/ns/data-models#Building",
        "https://schema.org/address": {
            "type": "Property",
            "value": {
                "streetAddress": "Bornholmer Straße 65",
                "addressRegion": "Berlin",
                "addressLocality": "Prenzlauer Berg",
                "postalCode": "10439"
            },
            "verified": {
                "type": "Property",
                "value": true
            }
        },
        "https://uri.etsi.org/ngsi-ld/name": {
            "type": "Property",
            "value": "Bösebrücke Einkauf"
        },
        "https://uri.fiware.org/ns/data-models#category": {
            "type": "Property",
            "value": "https://uri.fiware.org/ns/data-models#commercial"
        },
        "location": {
            "type": "GeoProperty",
            "value": {
                "type": "Point",
                "coordinates": [
                    13.3986,
                    52.5547
                ]
            }
        }
    },
    {
        "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld",
        "id": "urn:ngsi-ld:Building:store002",
        "type": "https://uri.fiware.org/ns/data-models#Building",
        "https://schema.org/address": {
            "type": "Property",
            "value": {
                "streetAddress": "Friedrichstraße 44",
                "addressRegion": "Berlin",
                "addressLocality": "Kreuzberg",
                "postalCode": "10969"
            },
            "verified": {
                "type": "Property",
                "value": true
            }
        },
        "https://uri.etsi.org/ngsi-ld/name": {
            "type": "Property",
            "value": "Checkpoint Markt"
        },
        "https://uri.fiware.org/ns/data-models#category": {
            "type": "Property",
            "value": "https://uri.fiware.org/ns/data-models#commercial"
        },
        "location": {
            "type": "GeoProperty",
            "value": {
                "type": "Point",
                "coordinates": [
                    13.3903,
                    52.5075
                ]
            }
        }
    }
]

ID によるエンティティ・データの取得¶

この例は urn:ngsi-ld:Building:store001 のデータを返します

5 リクエスト :¶

curl -G -X GET \
   -H 'Accept: application/ld+json' \
   'http://localhost:1026/ngsi-ld/v1/entities/urn:ngsi-ld:Building:store001'

レスポンス :¶

レスポンスはデフォルト (https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld) でコアの @context を返し、すべての属性は可能な限り展開されます。

{
    "@context": "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld",
    "id": "urn:ngsi-ld:Building:store001",
    "type": "https://uri.fiware.org/ns/data-models#Building",
    "https://schema.org/address": {
        "type": "Property",
        "value": {
            "streetAddress": "Bornholmer Straße 65",
            "addressRegion": "Berlin",
            "addressLocality": "Prenzlauer Berg",
            "postalCode": "10439"
        },
        "verified": {
            "type": "Property",
            "value": true
        }
    },
    "https://uri.etsi.org/ngsi-ld/name": {
        "type": "Property",
        "value": "Bösebrücke Einkauf"
    },
    "https://uri.fiware.org/ns/data-models#category": {
        "type": "Property",
        "value": "https://uri.fiware.org/ns/data-models#commercial"
    },
    "location": {
        "type": "GeoProperty",
        "value": {
            "type": "Point",
            "coordinates": [
                13.3986,
                52.5547
            ]
        }
    }
}

タイプによるエンティティ・データ取得¶

提供されたデータへの参照が提供されている場合、短い名前のデータを返し、レスポンスを特定のデータの type に制限することが可能です。例えば、以下のリクエストはコンテキスト・データ内のすべての Building エンティティのデータを返します。type パラメータの使用は Building エンティティのみにレスポンスを制限します、options=keyValues クエリ・パラメータの使用はレスポンスを標準の JSON-LD まで減らします。

短い形式の type="Building" を FQN https://uri.fiware.org/ns/data-models#Building に関連付けるために Link ヘッダを供給しなければなりません。フル・リンク・ヘッダの構文は次のとおりです :

Link: <https://fiware.github.io/data-models/context.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json

標準の HTTP の Link ヘッダは、実際に問題のリソースに触れることなくメタデータ (この場合は @context) を渡すことを可能にします。NGSI-LD の場合、メタデータは application/ld+json 形式のファイルです。

6 リクエスト :¶

curl -G -X GET \
  'http://localhost:1026/ngsi-ld/v1/entities' \
    -H 'Link: <https://fiware.github.io/data-models/context.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \
    'http://localhost:1026/ngsi-ld/v1/entities' \
    -H 'Accept: application/ld+json' \
    -d 'type=Building' \
    -d 'options=keyValues'

レスポンス :¶

options=keyValues を使用しているため、レスポンスは JSON のみで構成され、属性の定義 type="Property" や properties-of-properties 要素は含まれていません。リクエストからの Link ヘッダはレスポンスに返される @context として使われていることがわかります。

[
    {
        "@context": "https://fiware.github.io/data-models/context.jsonld",
        "id": "urn:ngsi-ld:Building:store001",
        "type": "Building",
        "address": {
            "streetAddress": "Bornholmer Straße 65",
            "addressRegion": "Berlin",
            "addressLocality": "Prenzlauer Berg",
            "postalCode": "10439"
        },
        "name": "Bösebrücke Einkauf",
        "category": "commercial",
        "location": {
            "type": "Point",
            "coordinates": [
                13.3986,
                52.5547
            ]
        }
    },
    {
        "@context": "https://fiware.github.io/data-models/context.jsonld",
        "id": "urn:ngsi-ld:Building:store002",
        "type": "Building",
        "address": {
            "streetAddress": "Friedrichstraße 44",
            "addressRegion": "Berlin",
            "addressLocality": "Kreuzberg",
            "postalCode": "10969"
        },
        "name": "Checkpoint Markt",
        "category": "commercial",
        "location": {
            "type": "Point",
            "coordinates": [
                13.3903,
                52.5075
            ]
        }
    }
]

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

この例は name 属性 Checkpoint Markt を持つ全ての Building エンティティを返します。フィルタリングは q パラメータを使って行うことができます。文字列がスペースを含む場合、それは URL エンコードされ、単一引用符 " = %22 の中に保持されます。

7 リクエスト :¶

curl -G -X GET \
    'http://localhost:1026/ngsi-ld/v1/entities' \
    -H 'Link: <https://fiware.github.io/data-models/context.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \
    -H 'Accept: application/ld+json' \
    -d 'type=Building' \
    -d 'q=name==%22Checkpoint%20Markt%22' \
    -d 'options=keyValues'

レスポンス :¶

Link ヘッダ https://schema.lab.fiware.org/ld/context は以下に示すように @context の配列を保持します :

{
    "@context": [
        "https://fiware.github.io/data-models/context.jsonld",
        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context-v1.3.jsonld"
    ]
}

したがって、FIWARE Building モデルが含まれています。

これは、Link ヘッダと options=keyValues パラメータを使用すると、以下に示すように短い形式の JSON-LD へのレスポンスが減ることを意味します :

[
    {
        "@context": "https://fiware.github.io/data-models/context.jsonld",
        "id": "urn:ngsi-ld:Building:store002",
        "type": "Building",
        "address": {
            "streetAddress": "Friedrichstraße 44",
            "addressRegion": "Berlin",
            "addressLocality": "Kreuzberg",
            "postalCode": "10969"
        },
        "name": "Checkpoint Markt",
        "category": "commercial",
        "location": {
            "type": "Point",
            "coordinates": [
                13.3903,
                52.5075
            ]
        }
    }
]

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

標準的な Building モデルの中では、category 属性は文字列の配列を参照します。この例では、commercial または office の文字列を含む category 属性を持つすべての Building エンティティを返します。フィルタリングは q パラメータを使って行うことができ、コンマは許容値を区切ります。

8 リクエスト :¶

curl -G -X GET \
    'http://localhost:1026/ngsi-ld/v1/entities' \
    -H 'Link: <https://fiware.github.io/data-models/context.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \
    -H 'Accept: application/ld+json' \
    -d 'type=Building' \
    -d 'q=category==%22commercial%22,%22office%22' \
    -d 'options=keyValues'

レスポンス :¶

レスポンスは、短い形式の属性名を使用してJSON-LD 形式で返されます :

[
    {
        "@context": "https://fiware.github.io/data-models/context.jsonld",
        "id": "urn:ngsi-ld:Building:store001",
        "type": "Building",
        "address": {
            "streetAddress": "Bornholmer Straße 65",
            "addressRegion": "Berlin",
            "addressLocality": "Prenzlauer Berg",
            "postalCode": "10439"
        },
        "name": "Bösebrücke Einkauf",
        "category": "commercial",
        "location": {
            "type": "Point",
            "coordinates": [
                13.3986,
                52.5547
            ]
        }
    },
    {
        "@context": "https://fiware.github.io/data-models/context.jsonld",
        "id": "urn:ngsi-ld:Building:store002",
        "type": "Building",
        "address": {
            "streetAddress": "Friedrichstraße 44",
            "addressRegion": "Berlin",
            "addressLocality": "Kreuzberg",
            "postalCode": "10969"
        },
        "name": "Checkpoint Markt",
        "category": "commercial",
        "location": {
            "type": "Point",
            "coordinates": [
                13.3903,
                52.5075
            ]
        }
    }
]

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

この例では、Kreuzberg (クロイツベルク) 地区にあるすべてのストアを返します。

フィルタリングは q パラメータを使って行うことができます。サブ属性はブラケット構文を使って注釈を付けられます。例えば q=address[addressLocality]=="Kreuzberg"。これは、ドット・シンタックスが使用されていた NGSI v2 とは異なります。

9 リクエスト :¶

curl -G -X GET \
    'http://localhost:1026/ngsi-ld/v1/entities' \
    -H 'Link: <https://fiware.github.io/data-models/context.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \
    -H 'Accept: application/ld+json' \
    -d 'type=Building' \
    -d 'q=address%5BaddressLocality%5D==%22Kreuzberg%22' \
    -d 'options=keyValues'

レスポンス :¶

Link ヘッダと options=keyValues パラメータの使用は JSON-LD へのレスポンスを減らします。

[
    {
        "@context": "https://fiware.github.io/data-models/context.jsonld",
        "id": "urn:ngsi-ld:Building:store002",
        "type": "Building",
        "address": {
            "streetAddress": "Friedrichstraße 44",
            "addressRegion": "Berlin",
            "addressLocality": "Kreuzberg",
            "postalCode": "10969"
        },
        "name": "Checkpoint Markt",
        "category": "commercial",
        "location": {
            "type": "Point",
            "coordinates": [
                13.3903,
                52.5075
            ]
        }
    }
]

メタデータをクエリすることでコンテキスト・データをフィルタ¶

この例は検証されたアドレスを持つすべての Building エンティティのデータを返します。Verified 属性は Property-of-a-Property の例です

メタデータ・クエリ (すなわち Properties of Properties) はドット・シンタックスを使用して注釈付けされます。例えば q=address.verified==true。これは NGSI v2 の mq パラメータに代わるものです。

10 リクエスト :¶

curl -G -X GET \
    'http://localhost:1026/ngsi-ld/v1/entities' \
    -H 'Link: <https://fiware.github.io/data-models/context.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \
    -H 'Accept: application/ld+json' \
    -d 'type=Building' \
    -d 'q=address.verified==true' \
    -d 'options=keyValues'

レスポンス :¶

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

[
    {
        "@context": "https://fiware.github.io/data-models/context.jsonld",
        "id": "urn:ngsi-ld:Building:store001",
        "type": "Building",
        "address": {
            "streetAddress": "Bornholmer Straße 65",
            "addressRegion": "Berlin",
            "addressLocality": "Prenzlauer Berg",
            "postalCode": "10439"
        },
        "name": "Bösebrücke Einkauf",
        "category": "commercial",
        "location": {
            "type": "Point",
            "coordinates": [
                13.3986,
                52.5547
            ]
        }
    },
    {
        "@context": "https://fiware.github.io/data-models/context.jsonld",
        "id": "urn:ngsi-ld:Building:store002",
        "type": "Building",
        "address": {
            "streetAddress": "Friedrichstraße 44",
            "addressRegion": "Berlin",
            "addressLocality": "Kreuzberg",
            "postalCode": "10969"
        },
        "name": "Checkpoint Markt",
        "category": "commercial",
        "location": {
            "type": "Point",
            "coordinates": [
                13.3903,
                52.5075
            ]
        }
    }
]

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

この例では、Berlin の Brandenburg Gate (52.5162N 13.3777W) から2km以内のすべてのストアを返します。ジオ・クエリ・リクエストをするには、geometry, coordinates, georel の3つのパラメータを指定しなければなりません。

NGSI-LD の構文が更新され、coordinates パラメータは、現在では、NGSI v2 で必要とされる単純な緯度と経度ペアではなく、角括弧 (square brackets) を含む geoJSON で表されるようになりました。

geo-query はデフォルトで location 属性に適用されることに注意してください。これは、NGSI-LD でデフォルトで指定されているためです。他の属性を使うのであれば、追加の geoproperty パラメータが必要です。

11 リクエスト :¶

curl -G -X GET \
  'http://localhost:1026/ngsi-ld/v1/entities' \
  -H 'Link: <https://fiware.github.io/data-models/context.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"' \
  -H 'Accept: application/ld+json' \
  -d 'type=Building' \
  -d 'geometry=Point' \
  -d 'coordinates=%5B13.3777,52.5162%5D' \
  -d 'georel=near;maxDistance==2000' \
  -d 'options=keyValues'

レスポンス :¶

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

[
    {
        "@context": "https://fiware.github.io/data-models/context.jsonld",
        "id": "urn:ngsi-ld:Building:store002",
        "type": "Building",
        "address": {
            "streetAddress": "Friedrichstraße 44",
            "addressRegion": "Berlin",
            "addressLocality": "Kreuzberg",
            "postalCode": "10969"
        },
        "name": "Checkpoint Markt",
        "category": "commercial",
        "location": {
            "type": "Point",
            "coordinates": [
                13.3903,
                52.5075
            ]
        }
    }
]

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

FIWARE データ・エンティティへのリンクト・データの概念の追加¶

リンクト・データとは何ですか？¶

ビデオ : リンクト・データとは何ですか？¶

ビデオ : JSON-LD とは何ですか？¶

NGSI-LD とは何ですか？¶

NGSI v2 データ・モデル¶

NGSI LD データ・モデル¶

前提条件¶

Docker¶

Cygwin¶

アーキテクチャ¶

起動¶

リンクト・データをベースとした "Powered by FIWARE" アプリの作成¶

サービス状態の確認¶

1 リクエスト :¶

レスポンス :¶

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

コア・コンテキスト¶

Smart Data Models¶

Context terms are IRIs not URLs¶

2 リクエスト :¶

3 リクエスト :¶

NGSI-LD エンティティ定義内のプロパティの定義¶

NGSI-LD エンティティ定義内の Properties-of-Properties の定義¶

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

FQN タイプによるエンティティ・データの取得¶

4 リクエスト :¶

レスポンス :¶

ID によるエンティティ・データの取得¶

5 リクエスト :¶

レスポンス :¶

タイプによるエンティティ・データ取得¶

6 リクエスト :¶

レスポンス :¶

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

7 リクエスト :¶

レスポンス :¶

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

8 リクエスト :¶

レスポンス :¶

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

9 リクエスト :¶

レスポンス :¶

メタデータをクエリすることでコンテキスト・データをフィルタ¶

10 リクエスト :¶

レスポンス :¶

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

11 リクエスト :¶

レスポンス :¶

License¶