このチュートリアルでは、FIWARE ユーザに CRUD オペレーションについて説明します。チュートリアルでは、以前の在庫管理の例で作成されたデータを基に、CRUD オペレーションの概念を紹介し、ユーザがコンテキスト内に保持されているデータをオペレーションできるようにします。

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

データ・エンティティ¶

FIWARE プラットフォーム内では、エンティティは、実世界に存在する物理的または概念的オブジェクトの状態を表します。

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

シンプルな在庫管理システムでは、現在 4 つのエンティティ型があります。エンティティ間の関係は、次のように定義されます :

Store : ストアは実世界のレンガとモルタルの建物です。ストアには次のようなプロパティがあります :
- name : ストアの名前。例えば、"Checkpoint Markt"
- address : ストアの住所。例えば、"Friedrichstraße 44, 10969 Kreuzberg, Berlin"
- location : ストアの物理的なローケーション。例えば、52.5075 N, 13.3903 E
Shelf : 棚は販売したいオブジェクトを保持するための、現実世界のオブジェクトです。各棚には次のようなプロパティがあります :
- name : 棚の名前。例えば、"Wall Unit"
- location : 棚の物理的なローケーション。例えば、52.5075 N, 13.3903 E
- maximum_capacity : 棚の最大容量
- 棚(shelf)が置かれているストア(store)への関連付け
Product : 製品は販売するものとして定義されています。それは概念的なオブジェクトです。製品には次のような特性があります :
- name : 製品の名前。例えば、"Vodka"
- price : 製品の価格。例えば、13.99 ユーロ
- size : 製品のサイズ。例えば、小さい
Inventory Item : インベントリ項目は製品、店舗、棚、および物理的な物を関連付けるために使用される別の概念エンティティです。以下のようなプロパティを持ちます :
- product : 販売されている製品へのアソシエーション
- store : 製品が販売されている店舗への関連付け
- shelf : 製品が展示されている棚への関連
- stock_count : 倉庫で利用可能な製品の在庫数
- shelf_count : 棚で利用可能な製品の在庫数

ご覧のとおり、上記で定義されたエンティティには、変更される可能性のあるプロパティがいつか含まれています。たとえば、製品価格が変化し、在庫が売却され、棚の商品数が減少する可能性があります。

アーキテクチャ¶

このアプリケーションは、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-compose.yml ファイルの services セクションにあります:

orion:
    image: fiware/orion:latest
    hostname: orion
    container_name: orion
    depends_on:
        - mongo-db
    networks:
        - default
    expose:
        - "1026"
    ports:
        - "1026:1026"
    command: -dbhost mongo-db -logLevel DEBUG

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

どちらのコンテナも同じネットワークに常駐しています。Orion Context Broker はポート 1026 でリッスンしており、MongoDB はデフォルトポート 271071 でリッスンしています。このチュートリアルでは、ネットワークの外部から2つのポートを利用できるようにして、cUrl または Postman がネットワーク内から実行することなくアクセスできるようにしました。コマンドラインの初期化は、一目瞭然でなければなりません。

前提条件¶

Docker¶

物事を単純にするために、両方のコンポーネントが Docker を使用して実行されます。Docker は、環境ごとに各コンポーネントをパッケージ化し、独立して実行することができるコンテナ・テクノロジです。

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

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

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

docker-compose -v
docker version

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

Cygwin¶

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

起動¶

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

git clone https://github.com/FIWARE/tutorials.CRUD-Operations.git
cd tutorials.CRUD-Operations
git checkout NGSI-v2

./services start

このコマンドは、起動時に以前のストア・ファインダのチュートリアルのシードデータもインポートします。

CRUD とは？¶

Create, Read, Update, Delete は、永続ストレージの 4 つの基本機能です。これらのオペレーションは、通常、頭文字の CRUD を使用して参照されます。データベース内では、これらのオペレーションはそれぞれ一連のコマンドに直接マッピングされますが、RESTful API との関係はやや複雑です。

Orion Context Broker は、NGSI-v2 を使用してコンテキスト・データをオペレーションします。RESTful API として、コンテキスト内に保持されているデータをオペレーションするリクエストは、HTTP 動詞を CRUD オペレーションにマッピングする際に見られる標準的な規則に従います。

エンティティ CRUD オペレーション¶

<entity-id> がコンテキスト内で認識されていない、または未指定のオペレーションでは、/v2/entities エンドポイントが使用されます。

<entity-id> がコンテキスト内で認識されると、個々のデータ・エンティティは、/v2/entities/<entity-id> エンドポイントを使用してオペレーションできます。

エンティティ識別子は、 NGSI-LD specification ガイドラインに従った URNs であることが推奨されます。したがって、各 id は、標準形式に従った URN です : urn:ngsi-ld:<entity-type>:<entity-id>。これは、コンテキスト・データ内のすべての id を一意にするのに役立ちます。

HTTP 動詞	`/v2/entities`	`/v2/entities/<entity-id>`
POST	新しいエンティティを作成し、コンテキストに追加します。	指定されたエンティティの属性を作成または更新します。
GET	コンテキストからエンティティ・データを読み込みます。これにより、複数のエンティティからのデータが返されます。データはフィルタリングできます。	指定されたエンティティからエンティティ・データを読み込みます。これは、単一のエンティティからのデータのみを返します。データはフィルタリングできます。
PUT	❌	❌
PATCH	❌	❌
DELETE	❌	コンテキストからエンティティを削除します。

エンティティ・エンドポイントの完全なリストは、NGSI v2 Swagger Specification で、見つけることができます。

属性 CRUD オペレーション¶

属性に対して CRUD オペレーションを実行するには、<entity-id> を知る必要があります。各属性は実質的にキーと値のペアです。

3 つのエンドポイントがあります :

/v2/entities/<entity-id>/attrs は、1 つ以上の既存の属性を更新するパッチオペレーションにのみ使用されます。
/v2/entities/<entity-id>/attrs/<attribute> は、属性を全体としてオペレーションするために使用されます。
/v2/entities/<entity-id>/attrs/<attribute>/value は、属性の value を読み取りまたは更新に使用され、type をそのまま残します。

HTTP 動詞	`.../attrs`	`.../attrs/<attribute>`	`.../attrs/<attribute>/value`
POST	❌	❌	❌
GET	❌	❌	指定したエンティティから属性の値を読み込みます。これは単一のフィールドを返します。
PUT	❌	❌	指定されたエンティティから単一属性の値を更新します。
PATCH	既存のエンティティから 1 つまたは複数の既存の属性を更新します。	❌	❌
DELETE.	❌	既存のエンティティから既存の属性を削除します。	❌

属性エンドポイントの完全なリストは、NGSI v2 Swagger Specification で見つけることができます。

バッチ CRUD オペレーション¶

さらに、Orion Context Broker は、単一オペレーションで複数のエンティティをオペレーションするためのコンビニエンス・バッチ・オペレーションのエンドポイント /v2/op/update を持っています。

バッチ・オペレーションは、ペイロードが2つのプロパティを持つオブジェクトである POST リクエストによって常にトリガされます :

actionType : アクションの種類を呼び出すために指定します。例、delete
entities : 更新するエンティティのリストを保持しているオブジェクトの配列です。オペレーションを実行するため関連エンティティ・データと一緒に使用されます

FIWARE を使用した CRUD オペレーションの例¶

次の例では、Orion Context Broker が、localhost のポート 1026 をリッスンしていると仮定し、最初のシード・データを前のチュートリアルからインポートしました。

すべての例は、在庫管理システムで定義された Product エンティティを参照しています。したがって、CRUD オペレーションは、製品または一連の製品の追加、読み取り、修正および削除に関連します。これは、ストアの地域マネージャーの典型的な使用例です。たとえば、価格の設定や販売可能な製品の決定です。それぞれのケースで受け取った実際のレスポンスは、その時のシステムのコンテキスト・データの状態によって異なります。すでに間違ってエンティティを削除した場合は、コマンドラインからデータを再ロードして初期コンテキストを復元することができます。

./import-data

作成 (Create) オペレーション¶

作成 (Create) オペレーションは、HTTP POST へマップします。

/v2/entities エンドポイントは、新しいエンティティを作成するために使用されます
/v2/entities/<entity> エンドポイントは、新しい属性を追加するために使用されます

新しく作成されたエンティティは、id と type 属性を持たなければならず、他の属性はオプションであり、モデル化されるシステムに依存します。しかし、追加の属性が存在する場合、それぞれは type と value の両方を指定する必要があります。

オペレーションが成功した場合、レスポンスは、204 - No Context になるか、オペレーションが失敗した場合、422 - Unprocessable Entity になります

新しいデータ・エンティティの作成¶

この例では、新しい Product エンティティ (99 セントの "Lemonade") をコンテキストに追加します。

1 リクエスト :¶

curl -iX POST \
  --url 'http://localhost:1026/v2/entities' \
  --header 'Content-Type: application/json' \
  --data ' {
      "id":"urn:ngsi-ld:Product:010", "type":"Product",
      "name":{"type":"Text", "value":"Lemonade"},
      "size":{"type":"Text", "value": "S"},
      "price":{"type":"Integer", "value": 99}
}'

新しいエンティティは、/v2/entities エンドポイントに POST リクエストを行うことで追加できます。

いずれかの属性がすでにコンテキストに存在する場合、リクエストは失敗します。

2 リクエスト :¶

GET リクエストを行うことで、新しい Product がコンテキスト内に見つかるかどうかを確認することができます :

curl -X GET \
  --url 'http://localhost:1026/v2/entities/urn:ngsi-ld:Product:010?type=Product'

新しい属性の作成¶

この例では、id=urn:ngsi-ld:Product:001 の既存 Product エンティティに新しい specialOffer 属性を追加します。

3 リクエスト :¶

curl -iX POST \
  --url 'http://localhost:1026/v2/entities/urn:ngsi-ld:Product:001/attrs' \
  --header 'Content-Type: application/json' \
  --data '{
      "specialOffer":{"value": true}
}'

新しい属性は、/v2/entities/<entity>/attrs エンドポイントに POST リクエストを行うことで追加できます。

ペイロードは、示されているように属性名と値を保持する JSON オブジェクトで構成する必要があります。

type が指定されていない場合、デフォルト・タイプ(Boolean, Text, Number または StructuredValue)が割り当てられます。

同じ id を使用する後続のリクエストは、コンテキスト内の属性の値を更新します。

4 リクエスト :¶

GET リクエストを行うことで、新しい Product 属性がコンテキスト内にあるかどうかを確認することができます :

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

ご覧のように、 "Beer" Product エンティティにブール値の specialOffer フラグが付けられています。

新しいデータ・エンティティまたは属性のバッチ作成¶

この例では、コンビニエンス・バッチ処理エンドポイントを使用して、2 つの新しい Product エンティティと 1 つの新しい属性 (offerPrice)をコンテキストに追加します。

5 リクエスト :¶

curl -iX POST \
  --url 'http://localhost:1026/v2/op/update' \
  --header 'Content-Type: application/json' \
  --data '{
  "actionType":"append_strict",
  "entities":[
    {
      "id":"urn:ngsi-ld:Product:011", "type":"Product",
      "name":{"type":"Text", "value":"Brandy"},
      "size":{"type":"Text", "value": "M"},
      "price":{"type":"Integer", "value": 1199}
    },
    {
      "id":"urn:ngsi-ld:Product:012", "type":"Product",
      "name":{"type":"Text", "value":"Port"},
      "size":{"type":"Text", "value": "M"},
      "price":{"type":"Integer", "value": 1099}
    },
    {
      "id":"urn:ngsi-ld:Product:001", "type":"Product",
      "offerPrice":{"type":"Integer", "value": 89}
    }
  ]
}'

いずれかの属性がすでにコンテキストに存在する場合、リクエストは失敗します。

バッチ処理は、2 つの属性のペイロードで /v2/op/update エンドポイントを使用します

actionType=append_strict は、すべてのエンティティ/属性が新しい場合にのみ　　リクエストが成功することを意味します
entities 属性は、作成したいエンティティの配列を保持しています。

actionType=append_strict バッチ・オペレーションで同じデータを使用した後続のリクエストでは、エラー・レスポンスが発生します。

新しいデータ・エンティティのバッチ作成/上書き¶

この例では、コンビニエンス・バッチ処理エンドポイントを使用して、2 つの Product エンティティと 1 つの属性(offerPrice)をコンテキストに追加または修正します。

エンティティがすでに存在する場合、リクエストはエンティティの属性を更新します
エンティティが存在しない場合は、新しいエンティティが作成されます

6 リクエスト :¶

curl -iX POST \
  --url 'http://localhost:1026/v2/op/update' \
  --header 'Content-Type: application/json' \
  --data '{
  "actionType":"append",
  "entities":[
    {
      "id":"urn:ngsi-ld:Product:011", "type":"Product",
      "name":{"type":"Text", "value":"Brandy"},
      "size":{"type":"Text", "value": "M"},
      "price":{"type":"Integer", "value": 1199}
    },
    {
      "id":"urn:ngsi-ld:Product:012", "type":"Product",
      "name":{"type":"Text", "value":"Port"},
      "size":{"type":"Text", "value": "M"},
      "price":{"type":"Integer", "value": 1099}
    }
  ]
}'

バッチ処理では、次の 2 つの属性を持つペイロードで、/v2/op/update エンドポイントを使用します :

actionType=append は、既存のエンティティが存在する場合は上書きすることを意味します
エンティティ属性は、作成/上書きするエンティティの配列を保持します

同じデータ (すなわち、同じエンティティおよび actionType=append ) を含む後続のリクエストは、コンテキスト状態を変更しません。

読み取り (Read) オペレーション¶

/v2/entities エンドポイントは、エンティティをリストするために使用されます
/v2/entities/<entity> エンドポイントは、単一のエンティティの詳細情報を取得するために使用されています

フィルタリング¶

options パラメータ (attrs パラメータと組み合わせて)は、返されるフィールドをフィルタリングすることができます
q パラメータは、返されるエンティティをフィルタリングするために使用できます

データ・エンティティ(詳細)を読み取り¶

この例では、既知の id を持つ既存 Product エンティティから完全なコンテキストを読み取ります。

7 リクエスト :¶

curl -X GET \
  --url 'http://localhost:1026/v2/entities/urn:ngsi-ld:Product:010?type=Product'

レスポンス :¶

Product urn:ngsi-ld:Product:010 は 99 セントの"Lemonade" です。レスポンスは以下のようになります :

{
    "id": "urn:ngsi-ld:Product:010",
    "type": "Product",
    "name": { "type": "Text", "value": "Lemonade", "metadata": {} },
    "price": { "type": "Integer", "value": 99, "metadata": {} },
    "size": { "type": "Text", "value": "S", "metadata": {} }
}

コンテキスト・データは、/v2/entities/<entity> エンドポイントに GET リクエストを出すことによって取り出すことができます。

データ・エンティティから属性の読み取り¶

この例では、既知の id を持つ既存 Product エンティティから単一の属性 (name)の値を読み取ります。

8 リクエスト :¶

curl -X GET \
  --url 'http://localhost:1026/v2/entities/urn:ngsi-ld:Product:001/attrs/name/value'

レスポンス :¶

Product urn:ngsi-ld:Product:001 は 99 セントの"Beer"です。レスポンスは以下のようになります :

"Beer"

コンテキスト・データは、/v2/entities/<entity>/attrs/<attribute>/value エンドポイントに GET リクエストを出すことによって取り出すことができます。

データ・エンティティ(キー値のペア)の読み取り¶

この例では、既存の Product エンティティのコンテキストから2つの属性 (nameとprice) のキーと値のペアを既知の id で読み込みます。

9 リクエスト :¶

curl -X GET \
  --url 'http://localhost:1026/v2/entities/urn:ngsi-ld:Product:001?type=Product&options=keyValues&attrs=name,price'

レスポンス :¶

Product urn:ngsi-ld:Product:001 は 99 セントの"Beer"です。レスポンスは以下のようになります :

{
    "id": "urn:ngsi-ld:Product:001",
    "type": "Product",
    "name": "Beer",
    "price": 99
}

options=keyValues パラメータと attrs パラメータを組み合わせて、キーと値のペアを取得します。

データ・エンティティから複数の属性値の読み取り¶

この例では、既存の Product エンティティのコンテキストから、既知の ID を持つ2つの属性 (nameと price) の値を読み込みます。

10 リクエスト :¶

curl -X GET \
  --url 'http://localhost:1026/v2/entities/urn:ngsi-ld:Product:001?type=Product&options=values&attrs=name,price'

レスポンス :¶

Product urn:ngsi-ld:Product:001 は 99 セントの"Beer"です。レスポンスは以下のようになります :

["Beer", 99]

options=values パラメータと attrs パラメータを組み合わせることで、配列内の値のリストを返します。

すべてのデータ・エンティティ(詳細)を一覧表示¶

この例では、すべての Product エンティティの完全なコンテキストをリストしています。

11 リクエスト :¶

curl -X GET \
  --url 'http://localhost:1026/v2/entities?type=Product'

レスポンス :¶

起動時にコンテキストが9つの製品を保持し、3つが作成オペレーションによって追加され、フル・コンテキストに12の製品が含まれるようになりました。

[
    {
        "id": "urn:ngsi-ld:Product:001",
        "type": "Product",
        "name": { "type": "Text", "value": "Beer", "metadata": {} },
        "offerPrice": { "type": "Integer", "value": 89, "metadata": {} },
        "price": { "type": "Integer", "value": 99, "metadata": {} },
        "size": { "type": "Text", "value": "S", "metadata": {} },
        "specialOffer": { "type": "Boolean", "value": true, "metadata": {} }
    },
    {
        "id": "urn:ngsi-ld:Product:002",
        "type": "Product",
        "name": { "type": "Text", "value": "Red Wine", "metadata": {} },
        "price": { "type": "Integer", "value": 1099, "metadata": {} },
        "size": { "type": "Text", "value": "M", "metadata": {} }
    },
    {
        "id": "urn:ngsi-ld:Product:003",
        "type": "Product",
        "name": { "type": "Text", "value": "White Wine", "metadata": {} },
        "price": { "type": "Integer", "value": 1499, "metadata": {} },
        "size": { "type": "Text", "value": "M", "metadata": {} }
    },
    {
        "id": "urn:ngsi-ld:Product:004",
        "type": "Product",
        "name": { "type": "Text", "value": "Vodka", "metadata": {} },
        "price": { "type": "Integer", "value": 5000, "metadata": {} },
        "size": { "type": "Text", "value": "XL", "metadata": {} }
    },
    {
        "id": "urn:ngsi-ld:Product:005",
        "type": "Product",
        "name": { "type": "Text", "value": "Lager", "metadata": {} },
        "price": { "type": "Integer", "value": 99, "metadata": {} },
        "size": { "type": "Text", "value": "S", "metadata": {} }
    },
    {
        "id": "urn:ngsi-ld:Product:006",
        "type": "Product",
        "name": { "type": "Text", "value": "Whisky", "metadata": {} },
        "price": { "type": "Integer", "value": 99, "metadata": {} },
        "size": { "type": "Text", "value": "S", "metadata": {} }
    },
    {
        "id": "urn:ngsi-ld:Product:007",
        "type": "Product",
        "name": { "type": "Text", "value": "Gin", "metadata": {} },
        "price": { "type": "Integer", "value": 99, "metadata": {} },
        "size": { "type": "Text", "value": "S", "metadata": {} }
    },
    {
        "id": "urn:ngsi-ld:Product:008",
        "type": "Product",
        "name": { "type": "Text", "value": "Apple Juice", "metadata": {} },
        "price": { "type": "Integer", "value": 99, "metadata": {} },
        "size": { "type": "Text", "value": "S", "metadata": {} }
    },
    {
        "id": "urn:ngsi-ld:Product:009",
        "type": "Product",
        "name": { "type": "Text", "value": "Orange Juice", "metadata": {} },
        "price": { "type": "Integer", "value": 99, "metadata": {} },
        "size": { "type": "Text", "value": "S", "metadata": {} }
    },
    {
        "id": "urn:ngsi-ld:Product:010",
        "type": "Product",
        "name": { "type": "Text", "value": "Lemonade", "metadata": {} },
        "price": { "type": "Integer", "value": 99, "metadata": {} },
        "size": { "type": "Text", "value": "S", "metadata": {} }
    },
    {
        "id": "urn:ngsi-ld:Product:011",
        "type": "Product",
        "name": { "type": "Text", "value": "Brandy", "metadata": {} },
        "price": { "type": "Integer", "value": 1199, "metadata": {} },
        "size": { "type": "Text", "value": "M", "metadata": {} }
    },
    {
        "id": "urn:ngsi-ld:Product:012",
        "type": "Product",
        "name": { "type": "Text", "value": "Port", "metadata": {} },
        "price": { "type": "Integer", "value": 1099, "metadata": {} },
        "size": { "type": "Text", "value": "M", "metadata": {} }
    }
]

すべてのデータ・エンティティ(キー値のペア)を一覧表示¶

この例では、すべての Product エンティティの name と price 属性を示します。

12 リクエスト :¶

curl -X GET \
  --url 'http://localhost:1026/v2/entities/?type=Product&options=keyValues&attrs=name,price'

レスポンス :¶

起動時にコンテキストが9つの製品を保持し、3つが作成オペレーションによって追加され、フル・コンテキストに12の製品が含まれるようになりました。

[
    {
        "id": "urn:ngsi-ld:Product:001",
        "type": "Product",
        "name": "Beer",
        "price": 99
    },
    {
        "id": "urn:ngsi-ld:Product:002",
        "type": "Product",
        "name": "Red Wine",
        "price": 1099
    },
    {
        "id": "urn:ngsi-ld:Product:003",
        "type": "Product",
        "name": "White Wine",
        "price": 1499
    },
    {
        "id": "urn:ngsi-ld:Product:004",
        "type": "Product",
        "name": "Vodka",
        "price": 5000
    },
    {
        "id": "urn:ngsi-ld:Product:005",
        "type": "Product",
        "name": "Lager",
        "price": 99
    },
    {
        "id": "urn:ngsi-ld:Product:006",
        "type": "Product",
        "name": "Whisky",
        "price": 99
    },
    {
        "id": "urn:ngsi-ld:Product:007",
        "type": "Product",
        "name": "Gin",
        "price": 99
    },
    {
        "id": "urn:ngsi-ld:Product:008",
        "type": "Product",
        "name": "Apple Juice",
        "price": 99
    },
    {
        "id": "urn:ngsi-ld:Product:009",
        "type": "Product",
        "name": "Orange Juice",
        "price": 99
    },
    {
        "id": "urn:ngsi-ld:Product:010",
        "type": "Product",
        "name": "Lemonade",
        "price": 99
    },
    {
        "id": "urn:ngsi-ld:Product:011",
        "type": "Product",
        "name": "Brandy",
        "price": 1199
    },
    {
        "id": "urn:ngsi-ld:Product:012",
        "type": "Product",
        "name": "Port",
        "price": 1099
    }
]

指定されたエンティティ・タイプのフル・コンテキスト・データは、/v2/entities エンドポイントへの GET リクエストを行い、type パラメータを指定することによって取得できます。options=keyValues パラメータおよび attrs パラメータと組み合わせて、キーと値を取得します。

Type でデータ・エンティティを一覧表示¶

この例では、すべての Prodcut エンティティの id と type が一覧表示されます。

13 リクエスト :¶

curl -X GET \
  --url 'http://localhost:1026/v2/entities/?type=Product&options=count&attrs=__NONE'

レスポンス :¶

起動時にコンテキストが9つの製品を保持し、3つが作成オペレーションによって追加され、フル・コンテキストに12の製品が含まれるようになりました。

[
    {
        "id": "urn:ngsi-ld:Product:001",
        "type": "Product"
    },
    {
        "id": "urn:ngsi-ld:Product:002",
        "type": "Product"
    },
    {
        "id": "urn:ngsi-ld:Product:003",
        "type": "Product"
    },
    {
        "id": "urn:ngsi-ld:Product:004",
        "type": "Product"
    },
    {
        "id": "urn:ngsi-ld:Product:005",
        "type": "Product"
    },
    {
        "id": "urn:ngsi-ld:Product:006",
        "type": "Product"
    },
    {
        "id": "urn:ngsi-ld:Product:007",
        "type": "Product"
    },
    {
        "id": "urn:ngsi-ld:Product:008",
        "type": "Product"
    },
    {
        "id": "urn:ngsi-ld:Product:009",
        "type": "Product"
    },
    {
        "id": "urn:ngsi-ld:Product:010",
        "type": "Product"
    },
    {
        "id": "urn:ngsi-ld:Product:011",
        "type": "Product"
    },
    {
        "id": "urn:ngsi-ld:Product:012",
        "type": "Product"
    }
]

指定されたエンティティ・タイプのコンテキスト・データは、/v2/entities エンドポイントへの GET リクエストを行い、type パラメータを指定することによって取得できます。これと、options=count, attrs=__NONE を組み合わせ id て指定された type の id 属性を返します。

注: NGSIv2 仕様では、attrs= は "データが応答に含まれる属性名のコンマ区切りのリスト" である必要があると指定されています。id と type を属性名として使用することはできません。__NONE などの属性に存在しない名前を attrs= パラメータに指定すると、一致する属性はなく、常にエンティティの ID と Type のみを取得できす。

更新 (Update) オペレーション¶

上書きオペレーションは HTTP PUT にマップされます。HTTP PATCH を使用すると、一度に複数の属性を更新できます。

/v2/entities/<entity>/attrs/<attribute>/value エンドポイントは属性を更新するために使用されます
/v2/entities/<entity>/attrs エンドポイントは、複数の属性を更新するために使用されます

属性の値を上書き¶

この例では、id=urn:ngsi-ld:Product:001 を持つ Entity の price 属性の値を次のように更新します。

14 リクエスト :¶

curl -iX PUT \
  --url 'http://localhost:1026/v2/entities/urn:ngsi-ld:Product:001/attrs/price/value' \
  --header 'Content-Type: text/plain' \
  --data 89

既存の属性値は、/v2/entities/<entity>/attrs/<attribute>/value エンドポイントに PUT リクエストを行うことで変更できます。

データ・エンティティの複数の属性を上書き¶

この例は、id=urn:ngsi-ld:Product:001 を持つ、Entity の price 属性と name 属性の両方の値を同時に更新します。

15 リクエスト :¶

curl -iX PATCH \
  --url 'http://localhost:1026/v2/entities/urn:ngsi-ld:Product:001/attrs' \
  --header 'Content-Type: application/json' \
  --data ' {
      "price":{"type":"Integer", "value": 89},
      "name": {"type":"Text", "value": "Ale"}
}'

複数のデータ・エンティティの属性のバッチ上書き¶

この例では、コンビニエンス・バッチ処理エンドポイントを使用して、既存の製品を更新します。

16 リクエスト :¶

curl -iX POST \
  --url 'http://localhost:1026/v2/op/update' \
  --header 'Content-Type: application/json' \
  --data '{
  "actionType":"update",
  "entities":[
    {
      "id":"urn:ngsi-ld:Product:001", "type":"Product",
      "price":{"type":"Integer", "value": 1199}
    },
    {
      "id":"urn:ngsi-ld:Product:002", "type":"Product",
      "price":{"type":"Integer", "value": 1199},
      "size": {"type":"Text", "value": "L"}
    }
  ]
}'

バッチ処理では、2 つの属性のペイロードを持つ /v2/op/update エンドポイントを使用します。

actionType=append は、既存のエンティティが存在する場合はそれを上書きすることを意味しますが、entities 属性は更新したいエンティティの配列を保持します。

複数のデータ・エンティティの属性のバッチ作成/上書き¶

この例では、コンビニエンス・バッチ処理エンドポイントを使用して、既存の製品を更新します。

17 リクエスト :¶

curl -iX POST \
  --url 'http://localhost:1026/v2/op/update' \
  --header 'Content-Type: application/json' \
  --data '{
  "actionType":"append",
  "entities":[
    {
      "id":"urn:ngsi-ld:Product:001", "type":"Product",
      "price":{"type":"Integer", "value": 1199}
    },
    {
      "id":"urn:ngsi-ld:Product:002", "type":"Product",
      "price":{"type":"Integer", "value": 1199},
      "specialOffer": {"type":"Boolean", "value":  true}
    }
  ]
}'

バッチ処理では、2 つの属性のペイロードを持つ /v2/op/update エンドポイントを使用します。

actionType=append は、既存のエンティティが存在する場合はそれを上書きすることを意味しますが、entities 属性は更新したいエンティティの配列を保持します。

エンティティ・データの一括置換¶

この例では、既存の製品のエンティティのデータを置き換えるために、コンビニエンス・バッチ処理エンドポイントを使用しています。

18 リクエスト :¶

curl -iX POST \
  --url 'http://localhost:1026/v2/op/update' \
  --header 'Content-Type: application/json' \
  --data '{
  "actionType":"replace",
  "entities":[
    {
      "id":"urn:ngsi-ld:Product:010", "type":"Product",
      "price":{"type":"Integer", "value": 1199}
    }
  ]
}'

バッチ処理では、2 つの属性のペイロードを持つ /v2/op/update エンドポイントを使用します。 - actionType=replace は、既存のエンティティが存在する場合はそれを上書きすることを意味しますが、entities 属性はデータを置き換えるエンティティの配列を保持します。

削除 (DELETE) オペレーション¶

削除 (Delete) オペレーションは、HTTP DELETE にマップします。

/v2/entities/<entity> エンドポイントは、エンティティを削除するために使用できます
/v2/entities/<entity>/attrs/<attribute> エンドポイントは、属性を削除するために使用できます

レスポンスは、オペレーションが成功すれば、204 - No Content となり、失敗すれば、404 - Not Found となります。

データのリレーションシップ¶

コンテキスト内に互いに関係するエンティティがある場合、エンティティを削除するときは注意が必要です。エンティティが削除されるとリファレンスが残っていないことを確認する必要があります。

カスケード削除の構成はこのチュートリアルの範囲を超えていますが、バッチ削除リクエストを使用することもできます。

エンティティの削除¶

この例では、id=urn:ngsi-ld:Product:001 のエンティティをコンテキストから削除します。

19 リクエスト :¶

curl -iX DELETE \
  --url 'http://localhost:1026/v2/entities/urn:ngsi-ld:Product:010'

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

同じ id を使用する後続のリクエストは、エンティティがもはやコンテキストに存在しないため、エラーレスポンスになります。

エンティティからの属性の削除¶

この例では、id=urn:ngsi-ld:Product:001 のエンティティから specialOffer 属性を削除します。

20 リクエスト :¶

curl -iX DELETE \
  --url 'http://localhost:1026/v2/entities/urn:ngsi-ld:Product:001/attrs/specialOffer'

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

属性がコンテキストに存在しない場合は、エラー・レスポンスになります。

複数のエンティティの一括削除¶

この例では、コンビニエンス・バッチ処理エンドポイントを使用して、 Product エンティティを削除します。

21 リクエスト :¶

curl -iX POST \
  --url 'http://localhost:1026/v2/op/update' \
  --header 'Content-Type: application/json' \
  --data '{
  "actionType":"delete",
  "entities":[
    {
      "id":"urn:ngsi-ld:Product:001", "type":"Product"
    },
    {
      "id":"urn:ngsi-ld:Product:002", "type":"Product"
    }
  ]
}'

バッチ処理では、2 つの属性のペイロードを持つ /v2/op/update エンドポイントを使用します。

actionType=delete は、コンテキストから何かを削除することを意味し、entities属性は、削除するエンティティの id を保持します。

コンテキスト内にエンティティが存在しない場合は、結果はエラー・レスポンスが返されます。

エンティティからの複数の属性のバッチ削除¶

この例では、コンビニエンス・バッチ処理エンドポイントを使用して、 Product エンティティからいくつかの属性を削除します。

22 リクエスト :¶

curl -iX POST \
  --url 'http://localhost:1026/v2/op/update' \
  --header 'Content-Type: application/json' \
  --data '{
  "actionType":"delete",
  "entities":[
    {
      "id":"urn:ngsi-ld:Product:003", "type":"Product",
      "price":{},
      "name": {}
    }
  ]
}'

バッチ処理では、2 つの属性のペイロードを持つ /v2/op/update エンドポイントを使用します。

actionType=delete は、コンテキストから何かを削除することを意味し、entities属性は、削除する属性の配列を保持します。

コンテキストに属性が存在しない場合、結果はエラーレスポンスになります。

既存のデータ・リレーションシップを見つける¶

この例では、urn:ngsi-ld:Product:001 に直接関連するすべてのエンティティのキーを返します。

23 リクエスト :¶

curl -X GET \
  --url 'http://localhost:1026/v2/entities/?q=refProduct==urn:ngsi-ld:Product:001&options=count&attrs=type'

レスポンス :¶

[
    {
        "id": "urn:ngsi-ld:InventoryItem:001",
        "type": "InventoryItem"
    }
]

このリクエストによって空の配列が返された場合、エンティティには関連付けられていません。安全に削除できます
レスポンスが一連の InventoryItem エンティティをリストする場合、関連する Product エンティティがコンテキストから削除される前に削除する必要があります

以前に、Product urn:ngsi-ld:Product:001 を削除したので、上で見たものは、実際にぶら下がている参照 (a dangling reference) です。たとえば、返された InventoryItem は、もはや存在しない Product を参照します。

データ・エンティティ¶

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

アーキテクチャ¶

前提条件¶

Docker¶

Cygwin¶

起動¶

CRUD とは？¶

エンティティ CRUD オペレーション¶

属性 CRUD オペレーション¶

バッチ CRUD オペレーション¶

FIWARE を使用した CRUD オペレーションの例¶

作成 (Create) オペレーション¶

新しいデータ・エンティティの作成¶

1 リクエスト :¶

2 リクエスト :¶

新しい属性の作成¶

3 リクエスト :¶

4 リクエスト :¶

新しいデータ・エンティティまたは属性のバッチ作成¶

5 リクエスト :¶

新しいデータ・エンティティのバッチ作成/上書き¶

6 リクエスト :¶

読み取り (Read) オペレーション¶

フィルタリング¶

データ・エンティティ(詳細)を読み取り¶

7 リクエスト :¶

レスポンス :¶

データ・エンティティから属性の読み取り¶

8 リクエスト :¶

レスポンス :¶

データ・エンティティ(キー値のペア)の読み取り¶

9 リクエスト :¶

レスポンス :¶

データ・エンティティから複数の属性値の読み取り¶

10 リクエスト :¶

レスポンス :¶

すべてのデータ・エンティティ(詳細)を一覧表示¶

11 リクエスト :¶

レスポンス :¶

すべてのデータ・エンティティ(キー値のペア)を一覧表示¶

12 リクエスト :¶

レスポンス :¶

Type でデータ・エンティティを一覧表示¶

13 リクエスト :¶

レスポンス :¶

更新 (Update) オペレーション¶

属性の値を上書き¶

14 リクエスト :¶

データ・エンティティの複数の属性を上書き¶

15 リクエスト :¶

複数のデータ・エンティティの属性のバッチ上書き¶

16 リクエスト :¶

複数のデータ・エンティティの属性のバッチ作成/上書き¶

17 リクエスト :¶

エンティティ・データの一括置換¶

18 リクエスト :¶

削除 (DELETE) オペレーション¶

データのリレーションシップ¶

エンティティの削除¶

19 リクエスト :¶

エンティティからの属性の削除¶

20 リクエスト :¶

複数のエンティティの一括削除¶

21 リクエスト :¶

エンティティからの複数の属性のバッチ削除¶

22 リクエスト :¶

既存のデータ・リレーションシップを見つける¶

23 リクエスト :¶

レスポンス :¶

License¶