4. API ウォークスルー

4.1. FogFlow Discovery API

4.1.1. 近くのブローカーを探す

外部アプリケーションまたは IoT デバイスの場合、FogFlow Discovery から必要な唯一のインターフェースは、自身の場所に基づいて近くのブローカーを見つけることです。その後、それらは割り当てられた近くのブローカーと対話する必要があるだけです。

POST /ngsi9/discoverContextAvailability

パラメーター 説明
latitude 場所 (location) の緯度
longitude 場所 (location)の緯度
limit 予想されるブローカーの数

以下の例を確認してください。

注釈

JavaScript のコード例では、ライブラリ ngsiclient.js が必要です。application/device/powerpanel のコード リポジトリを参照してください。

curl -iX POST \
  'http://localhost:80/ngsi9/discoverContextAvailability' \
  -H 'Content-Type: application/json' \
  -d '
    {
       "entities":[
          {
             "type":"IoTBroker",
             "isPattern":true
          }
       ],
       "restriction":{
          "scopes":[
             {
                "scopeType":"nearby",
                "scopeValue":{
                   "latitude":35.692221,
                   "longitude":139.709059,
                   "limit":1
                }
             }
          ]
       }
    } '
const NGSI = require('./ngsi/ngsiclient.js');

var discoveryURL = "http://localhost:80/ngsi9";
var myLocation = {
        "latitude": 35.692221,
        "longitude": 139.709059
    };

// find out the nearby IoT Broker according to my location
var discovery = new NGSI.NGSI9Client(discoveryURL)
discovery.findNearbyIoTBroker(myLocation, 1).then( function(brokers) {
    console.log('-------nearbybroker----------');
    console.log(brokers);
    console.log('------------end-----------');
}).catch(function(error) {
    console.log(error);
});

4.2. FogFlow Broker API

https://img.shields.io/swagger/valid/2.0/https/raw.githubusercontent.com/OAI/OpenAPI-Specification/master/examples/v2.0/json/petstore-expanded.json.svg

注釈

Cloud Broker へのアクセスにはポート 80 を使用しますが、Edge Broker の場合、デフォルトのポートは 8070 です。

4.2.1. コンテキストの作成/アップデート

注釈

コンテキスト エンティティを作成またはアップデートするのと同じ API です。コンテキスト アップデートの場合、既存のエンティティがない場合は、新しいエンティティが作成されます。

POST /ngsi10/updateContext

パラメーター 説明
latitude 場所 (location) の緯度
longitude 場所 (location)の緯度
limit 予想されるブローカーの数

例:

curl -iX POST \
  'http://localhost:80/ngsi10/updateContext' \
  -H 'Content-Type: application/json' \
  -d '
    {
        "contextElements": [
            {
                "entityId": {
                    "id": "Device.temp001",
                    "type": "Temperature",
                    "isPattern": false
                },
                "attributes": [
                {
                  "name": "temp",
                  "type": "integer",
                  "value": 10
                }
                ],
                "domainMetadata": [
                {
                    "name": "location",
                    "type": "point",
                    "value": {
                        "latitude": 49.406393,
                        "longitude": 8.684208
                    }
                },{
                    "name": "city",
                    "type": "string",
                    "value": "Heidelberg"
                }
                ]
            }
        ],
        "updateAction": "UPDATE"
    }'
const NGSI = require('./ngsi/ngsiclient.js');
var brokerURL = "http://localhost:80/ngsi10"

var ngsi10client = new NGSI.NGSI10Client(brokerURL);

var profile = {
        "type": "PowerPanel",
        "id": "01"};

var ctxObj = {};
ctxObj.entityId = {
    id: 'Device.' + profile.type + '.' + profile.id,
    type: profile.type,
    isPattern: false
};

ctxObj.attributes = {};

var degree = Math.floor((Math.random() * 100) + 1);
ctxObj.attributes.usage = {
    type: 'integer',
    value: degree
};
ctxObj.attributes.shop = {
    type: 'string',
    value: profile.id
};
ctxObj.attributes.iconURL = {
    type: 'string',
    value: profile.iconURL
};

ctxObj.metadata = {};

ctxObj.metadata.location = {
    type: 'point',
    value: profile.location
};

ngsi10client.updateContext(ctxObj).then( function(data) {
    console.log(data);
}).catch(function(error) {
    console.log('failed to update context');
});

4.2.2. GET を介したコンテキストのクエリ

4.2.2.1. ID でコンテキスト エンティティを取得

GET /ngsi10/entity/#eid

パラメーター 説明
eid エンティティ ID

例:

curl http://localhost:80/ngsi10/entity/Device.temp001

4.2.2.2. 特定のコンテキスト エンティティの特定の属性を取得

GET /ngsi10/entity/#eid/#attr

パラメーター 説明
eid エンティティ ID
attr フェッチする属性名を指定

例:

curl http://localhost:80/ngsi10/entity/Device.temp001/temp

4.2.2.3. 単一のブローカー上のすべてのコンテキスト エンティティを確認

GET /ngsi10/entity

例:

curl http://localhost:80/ngsi10/entity

4.2.3. POST を介してコンテキストをクエリ

POST /ngsi10/queryContext

パラメーター 説明
entityId 特定のエンティティ ID、ID pattern、またはタイプを定義できるエンティティ フィルターを指定
restriction スコープのリストと各スコープは、ドメイン メタデータに基づいてフィルターを定義

4.2.3.1. エンティティ ID のパターンによるコンテキストのクエリ

curl -X POST 'http://localhost:80/ngsi10/queryContext' \
  -H 'Content-Type: application/json' \
  -d '{"entities":[{"id":"Device.*","isPattern":true}]}'
const NGSI = require('./ngsi/ngsiclient.js');
var brokerURL = "http://localhost:80/ngsi10"
var ngsi10client = new NGSI.NGSI10Client(brokerURL);

var queryReq = {}
queryReq.entities = [{id:'Device.*', isPattern: true}];

ngsi10client.queryContext(queryReq).then( function(deviceList) {
    console.log(deviceList);
}).catch(function(error) {
    console.log(error);
    console.log('failed to query context');
});

4.2.3.2. エンティティ タイプによるコンテキストのクエリ

curl -X POST 'http://localhost:80/ngsi10/queryContext' \
  -H 'Content-Type: application/json' \
  -d '{"entities":[{"type":"Temperature","isPattern":true}]}'
const NGSI = require('./ngsi/ngsiclient.js');
var brokerURL = "http://localhost:80/ngsi10"
var ngsi10client = new NGSI.NGSI10Client(brokerURL);

var queryReq = {}
queryReq.entities = [{type:'Temperature', isPattern: true}];

ngsi10client.queryContext(queryReq).then( function(deviceList) {
    console.log(deviceList);
}).catch(function(error) {
    console.log(error);
    console.log('failed to query context');
});

4.2.3.3. ジオスコープ (geo-scope) によるコンテキストのクエリ (サークル)

curl -X POST 'http://localhost:80/ngsi10/queryContext' \
  -H 'Content-Type: application/json' \
  -d '{
        "entities": [{
            "id": ".*",
            "isPattern": true
        }],
        "restriction": {
            "scopes": [{
                "scopeType": "circle",
                "scopeValue": {
                   "centerLatitude": 49.406393,
                   "centerLongitude": 8.684208,
                   "radius": 10.0
                }
            }]
        }
      }'
const NGSI = require('./ngsi/ngsiclient.js');
var brokerURL = "http://localhost:80/ngsi10"
var ngsi10client = new NGSI.NGSI10Client(brokerURL);

var queryReq = {}
queryReq.entities = [{type:'.*', isPattern: true}];
queryReq.restriction = {scopes: [{
                    "scopeType": "circle",
                    "scopeValue": {
                       "centerLatitude": 49.406393,
                       "centerLongitude": 8.684208,
                       "radius": 10.0
                    }
                }]};

ngsi10client.queryContext(queryReq).then( function(deviceList) {
    console.log(deviceList);
}).catch(function(error) {
    console.log(error);
    console.log('failed to query context');
});

4.2.3.4. ジオスコープ (geo-scope) によるコンテキストのクエリ (ポリゴン)

curl -X POST 'http://localhost:80/ngsi10/queryContext' \
  -H 'Content-Type: application/json' \
  -d '{
   "entities":[
      {
         "id":".*",
         "isPattern":true
      }
   ],
   "restriction":{
      "scopes":[
         {
            "scopeType":"polygon",
            "scopeValue":{
               "vertices":[
                  {
                     "latitude":34.4069096565206,
                     "longitude":135.84594726562503
                  },
                  {
                     "latitude":37.18657859524883,
                     "longitude":135.84594726562503
                  },
                  {
                     "latitude":37.18657859524883,
                     "longitude":141.51489257812503
                  },
                  {
                     "latitude":34.4069096565206,
                     "longitude":141.51489257812503
                  },
                  {
                     "latitude":34.4069096565206,
                     "longitude":135.84594726562503
                  }
               ]
            }
        }]
    }
}'
const NGSI = require('./ngsi/ngsiclient.js');
var brokerURL = "http://localhost:80/ngsi10"
var ngsi10client = new NGSI.NGSI10Client(brokerURL);

var queryReq = {}
queryReq.entities = [{type:'.*', isPattern: true}];
queryReq.restriction = {
       "scopes":[
          {
             "scopeType":"polygon",
             "scopeValue":{
                "vertices":[
                   {
                      "latitude":34.4069096565206,
                      "longitude":135.84594726562503
                   },
                   {
                      "latitude":37.18657859524883,
                      "longitude":135.84594726562503
                   },
                   {
                      "latitude":37.18657859524883,
                      "longitude":141.51489257812503
                   },
                   {
                      "latitude":34.4069096565206,
                      "longitude":141.51489257812503
                   },
                   {
                      "latitude":34.4069096565206,
                      "longitude":135.84594726562503
                   }
                ]
             }
          }
       ]
    }

ngsi10client.queryContext(queryReq).then( function(deviceList) {
    console.log(deviceList);
}).catch(function(error) {
    console.log(error);
    console.log('failed to query context');
});

4.2.3.5. ドメイン メタデータ値のフィルターを使用したコンテキストのクエリ

注釈

条件ステートメント (conditional statement) は、コンテキスト エンティティのドメイン メタデータでのみ定義できます。当面は、特定の属性値に基づいてエンティティを除外することはサポートされていません。

curl -X POST 'http://localhost:80/ngsi10/queryContext' \
  -H 'Content-Type: application/json' \
  -d '{
        "entities": [{
            "id": ".*",
            "isPattern": true
        }],
        "restriction": {
            "scopes": [{
                "scopeType": "stringQuery",
                "scopeValue":"city=Heidelberg"
            }]
        }
      }'
const NGSI = require('./ngsi/ngsiclient.js');
var brokerURL = "http://localhost:80/ngsi10"
var ngsi10client = new NGSI.NGSI10Client(brokerURL);

var queryReq = {}
queryReq.entities = [{type:'.*', isPattern: true}];
queryReq.restriction = {scopes: [{
                    "scopeType": "stringQuery",
                    "scopeValue":"city=Heidelberg"
                }]};

ngsi10client.queryContext(queryReq).then( function(deviceList) {
    console.log(deviceList);
}).catch(function(error) {
    console.log(error);
    console.log('failed to query context');
});

4.2.3.6. 複数のフィルターを使用したコンテキストのクエリ

curl -X POST 'http://localhost:80/ngsi10/queryContext' \
  -H 'Content-Type: application/json' \
  -d '{
        "entities": [{
            "id": ".*",
            "isPattern": true
        }],
        "restriction": {
            "scopes": [{
                "scopeType": "circle",
                "scopeValue": {
                   "centerLatitude": 49.406393,
                   "centerLongitude": 8.684208,
                   "radius": 10.0
                }
            }, {
                "scopeType": "stringQuery",
                "scopeValue":"city=Heidelberg"
            }]
        }
      }'
const NGSI = require('./ngsi/ngsiclient.js');
var brokerURL = "http://localhost:80/ngsi10"
var ngsi10client = new NGSI.NGSI10Client(brokerURL);

var queryReq = {}
queryReq.entities = [{type:'.*', isPattern: true}];
queryReq.restriction = {scopes: [{
                    "scopeType": "circle",
                    "scopeValue": {
                       "centerLatitude": 49.406393,
                       "centerLongitude": 8.684208,
                       "radius": 10.0
                    }
                }, {
                    "scopeType": "stringQuery",
                    "scopeValue":"city=Heidelberg"
                }]};

ngsi10client.queryContext(queryReq).then( function(deviceList) {
    console.log(deviceList);
}).catch(function(error) {
    console.log(error);
    console.log('failed to query context');
});

4.2.4. コンテキストを削除

4.2.4.1. ID で特定のコンテキスト エンティティを削除

DELETE /ngsi10/entity/#eid

パラメーター 説明
eid エンティティ ID

例:

curl -iX DELETE http://localhost:80/ngsi10/entity/Device.temp001

4.2.5. コンテキストをサブスクライブ

POST /ngsi10/subscribeContext

パラメーター 説明
entityId 特定のエンティティ ID、ID pattern、またはタイプを定義できるエンティティ フィルターを指定
restriction スコープのリストと各スコープは、ドメイン メタデータに基づいてフィルターを定義
reference ノーティフィケーションを受信する宛先

4.2.5.1. エンティティ ID のパターンによるコンテキストのサブスクライブ

curl -X POST 'http://localhost:80/ngsi10/subscribeContext' \
  -H 'Content-Type: application/json' \
  -d '{
        "entities":[{"id":"Device.*","isPattern":true}],
        "reference": "http://localhost:8066"
    }'
const NGSI = require('./ngsi/ngsiclient.js');
var brokerURL = "http://localhost:80/ngsi10"
var ngsi10client = new NGSI.NGSI10Client(brokerURL);
var mySubscriptionId;

var subscribeReq = {}
subscribeReq.entities = [{id:'Device.*', isPattern: true}];

ngsi10client.subscribeContext(subscribeReq).then( function(subscriptionId) {
    console.log("subscription id = " + subscriptionId);
        mySubscriptionId = subscriptionId;
}).catch(function(error) {
    console.log('failed to subscribe context');
});

4.2.5.2. エンティティ タイプによるコンテキストのサブスクライブ

curl -X POST 'http://localhost:80/ngsi10/subscribeContext' \
  -H 'Content-Type: application/json' \
  -d '{
        "entities":[{"type":"Temperature","isPattern":true}]
        "reference": "http://localhost:8066"
      }'
const NGSI = require('./ngsi/ngsiclient.js');
var brokerURL = "http://localhost:80/ngsi10"
var ngsi10client = new NGSI.NGSI10Client(brokerURL);

var subscribeReq = {}
subscribeReq.entities = [{type:'Temperature', isPattern: true}];

ngsi10client.subscribeContext(subscribeReq).then( function(subscriptionId) {
    console.log("subscription id = " + subscriptionId);
        mySubscriptionId = subscriptionId;
}).catch(function(error) {
    console.log('failed to subscribe context');
});

4.2.5.3. ジオスコープ (geo-scope) によるコンテキストのサブスクライブ

curl -X POST 'http://localhost:80/ngsi10/subscribeContext' \
  -H 'Content-Type: application/json' \
  -d '{
        "entities": [{
            "id": ".*",
            "isPattern": true
        }],
        "reference": "http://localhost:8066",
        "restriction": {
            "scopes": [{
                "scopeType": "circle",
                "scopeValue": {
                   "centerLatitude": 49.406393,
                   "centerLongitude": 8.684208,
                   "radius": 10.0
                }
            }]
        }
      }'
const NGSI = require('./ngsi/ngsiclient.js');
var brokerURL = "http://localhost:80/ngsi10"
var ngsi10client = new NGSI.NGSI10Client(brokerURL);

var subscribeReq = {}
subscribeReq.entities = [{type:'.*', isPattern: true}];
subscribeReq.restriction = {scopes: [{
                    "scopeType": "circle",
                    "scopeValue": {
                       "centerLatitude": 49.406393,
                       "centerLongitude": 8.684208,
                       "radius": 10.0
                    }
                }]};

ngsi10client.subscribeContext(subscribeReq).then( function(subscriptionId) {
    console.log("subscription id = " + subscriptionId);
        mySubscriptionId = subscriptionId;
}).catch(function(error) {
    console.log('failed to subscribe context');
});

4.2.5.4. ドメイン メタデータ値のフィルターを使用してコンテキストをサブスクライブ

注釈

条件ステートメント (conditional statement) は、コンテキスト エンティティのドメイン メタデータでのみ定義できます。当面は、特定の属性値に基づいてエンティティを除外することはサポートされていません。

curl -X POST 'http://localhost:80/ngsi10/subscribeContext' \
  -H 'Content-Type: application/json' \
  -d '{
        "entities": [{
            "id": ".*",
            "isPattern": true
        }],
        "reference": "http://localhost:8066",
        "restriction": {
            "scopes": [{
                "scopeType": "stringQuery",
                "scopeValue":"city=Heidelberg"
            }]
        }
      }'
const NGSI = require('./ngsi/ngsiclient.js');
var brokerURL = "http://localhost:80/ngsi10"
var ngsi10client = new NGSI.NGSI10Client(brokerURL);

var subscribeReq = {}
subscribeReq.entities = [{type:'.*', isPattern: true}];
subscribeReq.restriction = {scopes: [{
                    "scopeType": "stringQuery",
                    "scopeValue":"city=Heidelberg"
                }]};

ngsi10client.subscribeContext(subscribeReq).then( function(subscriptionId) {
    console.log("subscription id = " + subscriptionId);
        mySubscriptionId = subscriptionId;
}).catch(function(error) {
    console.log('failed to subscribe context');
});

4.2.5.5. 複数のフィルターでコンテキストをサブスクライブ

curl -X POST 'http://localhost:80/ngsi10/subscribeContext' \
  -H 'Content-Type: application/json' \
  -d '{
        "entities": [{
            "id": ".*",
            "isPattern": true
        }],
        "reference": "http://localhost:8066",
        "restriction": {
            "scopes": [{
                "scopeType": "circle",
                "scopeValue": {
                   "centerLatitude": 49.406393,
                   "centerLongitude": 8.684208,
                   "radius": 10.0
                }
            }, {
                "scopeType": "stringQuery",
                "scopeValue":"city=Heidelberg"
            }]
        }
      }'
const NGSI = require('./ngsi/ngsiclient.js');
var brokerURL = "http://localhost:80/ngsi10"
var ngsi10client = new NGSI.NGSI10Client(brokerURL);

var subscribeReq = {}
subscribeReq.entities = [{type:'.*', isPattern: true}];
subscribeReq.restriction = {scopes: [{
                    "scopeType": "circle",
                    "scopeValue": {
                       "centerLatitude": 49.406393,
                       "centerLongitude": 8.684208,
                       "radius": 10.0
                    }
                }, {
                    "scopeType": "stringQuery",
                    "scopeValue":"city=Heidelberg"
                }]};

// use the IP and Port number your receiver is listening
subscribeReq.reference =  'http://' + agentIP + ':' + agentPort;


ngsi10client.subscribeContext(subscribeReq).then( function(subscriptionId) {
    console.log("subscription id = " + subscriptionId);
        mySubscriptionId = subscriptionId;
}).catch(function(error) {
    console.log('failed to subscribe context');
});

4.2.5.6. サブスクリプション ID でサブスクリプションをキャンセル

DELETE /ngsi10/subscription/#sid

パラメーター 説明
sid サブスクリプションの発行時に作成されるサブスクリプション ID

curl -iX DELETE http://localhost:80/ngsi10/subscription/#sid

4.3. FogFlow Service Orchestrator APIs

FogFlow での IoT サービスの全体的な開発プロセスを次の図に示します。フォグ ファンクションの開発では、ステップ4と5が組み合わされます。つまり、フォグ ファンクションがサブミットされると、FogFlow エディターによってデフォルトの要件が発行されます。

_images/development_process.png

4.3.1. オペレーターを実装

設計されたサービス トポロジーを定義する前に、サービス トポロジーで使用されるすべてのオペレーターは、ユーザーまたは FogFlow システムの他のプロバイダーによって提供される必要があります。

注釈

現在、2つのテンプレートが提供されています。1つは Node.js ベースの実装用で、もう1つは Python ベースの実装用です。

4.3.2. オペレーターを公開 (Publish the operator)

オペレーターのイメージは、パブリック Docker レジストリーまたはプライベート Docker レジストリーに公開できます。Docker レジストリーを使用しない場合は、オペレーターの Docker イメージがすべてのエッジ ノードで構築されていることを確認する必要があります。現在、FogFlow worker は、タスク インスタンスを起動するコマンドを受信すると、最初にローカル ストレージから必要な Docker イメージを検索します。見つからない場合は、Docker レジストリーに必要な Docker イメージ (FogFlow worker の構成に応じたパブリック イメージまたはプライベート イメージ) のフェッチを開始します。

誰かがイメージを公開したい場合は、次の docker コマンドを使用できます。

docker push  [the name of your image]

注釈

このステップは、docker コマンドのみで実行されます。

4.3.3. オペレーターの定義と登録

構築された NGSI アップデート メッセージをクラウドにデプロイされた IoT Broker に送信することで、オペレーターの Docker イメージを登録することもできます。

これは、オペレーターの Docker イメージを登録するための JavaScript ベースのコード例です。このコード例では、JavaScript ベースのライブラリを使用してFogFlow IoT Broker とやり取りしています。ライブラリは GitHub コード リポジトリ (designer/public/lib/ngsi) から見つけることができ、ngsiclient.js は Web ページに含まれている必要があります。

var image = {
    name: "counter",
    tag: "latest",
    hwType: "X86",
    osType: "Linux",
    operatorName: "counter",
    prefetched: false
};

//register a new docker image
var newImageObject = {};

newImageObject.entityId = {
    id : image.name + ':' + image.tag,
    type: 'DockerImage',
    isPattern: false
};

newImageObject.attributes = {};
newImageObject.attributes.image = {type: 'string', value: image.name};
newImageObject.attributes.tag = {type: 'string', value: image.tag};
newImageObject.attributes.hwType = {type: 'string', value: image.hwType};
newImageObject.attributes.osType = {type: 'string', value: image.osType};
newImageObject.attributes.operator = {type: 'string', value: image.operatorName};
newImageObject.attributes.prefetched = {type: 'boolean', value: image.prefetched};

newImageObject.metadata = {};
newImageObject.metadata.operator = {
    type: 'string',
    value: image.operatorName
};

// assume the config.brokerURL is the IP of cloud IoT Broker
var client = new NGSI10Client(config.brokerURL);
client.updateContext(newImageObject).then( function(data) {
    console.log(data);
}).catch( function(error) {
    console.log('failed to register the new device object');
});

4.3.4. サービス トポロジーを定義して登録

通常、サービス トポロジーは、FogFlow トポロジー エディタを介して定義および登録できます。ただし、独自のコードで定義および登録することもできます。

サービス トポロジーを登録するには、構築された NGSI アップデート メッセージをコードでクラウドにデプロイされた IoT Broker に送信する必要があります。

これは、オペレーターの Docker イメージを登録するための JavaScript ベースのコード例です。このコード例では、JavaScript ベースのライブラリを使用して FogFlow IoT Broker とやり取りします。ライブラリは、GitHub コード リポジトリ (designer/public/lib/ngsi) から見つけることができます。ngsiclient.js を Web ページに含める必要があります。

// the json object that represent the structure of your service topology
// when using the FogFlow topology editor, this is generated by the editor
var topology = {
   "description":"detect anomaly events from time series data points",
   "name":"anomaly-detection",
   "priority": {
        "exclusive": false,
        "level": 100
   },
   "trigger": "on-demand",
   "tasks":[
      {
         "name":"AnomalyDetector",
         "operator":"anomaly",
         "groupBy":"shop",
         "input_streams":[
            {
                  "type": "PowerPanel",
                "shuffling": "unicast",
                  "scoped": true
            },
            {
                  "type": "Rule",
                "shuffling": "broadcast",
                  "scoped": false
            }
         ],
         "output_streams":[
            {
               "type":"Anomaly"
            }
         ]
      },
      {
         "name":"Counter",
         "operator":"counter",
         "groupBy":"*",
         "input_streams":[
            {
               "type":"Anomaly",
               "shuffling": "unicast",
               "scoped": true
            }
         ],
         "output_streams":[
            {
               "type":"Stat"
            }
         ]
      }
   ]
}

//submit it to FogFlow via NGSI Update
var topologyCtxObj = {};

topologyCtxObj.entityId = {
    id : 'Topology.' + topology.name,
    type: topology.name,
    isPattern: false
};

topologyCtxObj.attributes = {};
topologyCtxObj.attributes.status = {type: 'string', value: 'enabled'};
topologyCtxObj.attributes.template = {type: 'object', value: topology};

// assume the config.brokerURL is the IP of cloud IoT Broker
var client = new NGSI10Client(config.brokerURL);

// send NGSI10 update
client.updateContext(topologyCtxObj).then( function(data) {
    console.log(data);
}).catch( function(error) {
    console.log('failed to submit the topology');
});

4.3.5. サービス トポロジーをトリガーする要件エンティティを作成

これは、カスタマイズされた要件エンティティ (requirement entity) を FogFlow に送信することによってサービス トポロジーをトリガーする JavaScript ベースのコード例です。

var rid = 'Requirement.' + uuid();

var requirementCtxObj = {};
requirementCtxObj.entityId = {
    id : rid,
    type: 'Requirement',
    isPattern: false
};

var restriction = { scopes:[{scopeType: geoscope.type, scopeValue: geoscope.value}]};

requirementCtxObj.attributes = {};
requirementCtxObj.attributes.output = {type: 'string', value: 'Stat'};
requirementCtxObj.attributes.scheduler = {type: 'string', value: 'closest_first'};
requirementCtxObj.attributes.restriction = {type: 'object', value: restriction};

requirementCtxObj.metadata = {};
requirementCtxObj.metadata.topology = {type: 'string', value: curTopology.entityId.id};

console.log(requirementCtxObj);

// assume the config.brokerURL is the IP of cloud IoT Broker
var client = new NGSI10Client(config.brokerURL);
client.updateContext(requirementCtxObj).then( function(data) {
    console.log(data);
}).catch( function(error) {
    console.log('failed to send a requirement');
});

4.3.6. 要件エンティティを削除して、サービス トポロジーを終了

これは、要件エンティティ (requirement entity) を削除してサービス トポロジーを終了する JavaScript ベースのコード例です。

var rid = [the id of your created requirement entity];

//
var client = new NGSI10Client(config.brokerURL);
client.deleteContext(rid).then( function(data) {
    console.log(data);
}).catch( function(error) {
    console.log('failed to send a requirement');
});

4.4. NGSI-LD でサポートされている APIs

次の図は、現在のスコープ内の APIs を使用して、FogFlow での NGSI-LD API サポートの目標を達成する方法の概要を示しています。API サポートには、エンティティの作成、登録、サブスクリプション、およびノーティフィケーションが含まれます。

_images/ngsild_architecture.png

4.4.1. Entities API

FogFlow との対話の目的で、IoT デバイスは、特定のコンテキストに従って解決されるエンティティ作成要求でブローカーにアプローチします。ブローカーはさらに、作成されたエンティティに対応して、登録要求を FogFlow Discovery に転送します。

注釈

Cloud broker へのアクセスにはポート80を使用しますが、Edge broker の場合、デフォルトのポートは8070です。ローカルホストは、FogFlow をホストするシステムのコア サービス IP です。

POST /ngsi-ld/v1/entities

4.4.1.3. c. 既存のエンティティに追加の属性を追加

POST /ngsi-ld/v1/entities/

キー バリュー
Content-Type application/json
Accept application/ld+json

リクエスト

curl -iX POST \
'http://localhost:80/ngsi-ld/v1/entities/' \
-H 'Content-Type: application/json' \
-H 'Accept: application/ld+json' \
-H 'Link: <{{link}}>; rel="https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld"; type="application/ld+json"' \
-d'
 {
      "id": ""urn:ngsi-ld:Vehicle:A100",
      "type": "Vehicle",
      ""brandName1"": {
      "brandName1": {
                          "type": "Property",
                          "value": "BMW"
       }
 }'

4.4.1.4. d. 既存のエンティティの特定の属性を更新

PATCH /ngsi-ld/v1/entities/

キー バリュー
Content-Type application/json
Accept application/ld+json

リクエスト

curl -iX POST \
'http://localhost:80/ngsi-ld/v1/entities/' \
-H 'Content-Type: application/json' \
-H 'Accept: application/ld+json' \
-H 'Link: <{{link}}>; rel="https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld"; type="application/ld+json"' \
 -d'
 {
       "id": ""urn:ngsi-ld:Vehicle:A100",
       "type": "Vehicle",

       "brandName": {
                          "type": "Property",
                          "value": "AUDI"
        }
 }'

4.4.1.5. e. NGSI-LD コンテキスト エンティティを削除

DELETE /ngsi-ld/v1/entities/#eid

パラメーター 説明
eid エンティティ ID

例:

curl -iX DELETE http://localhost:80/ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:A100  -H 'Content-Type: application/json' -H 'Accept: application/ld+json'

4.4.1.6. f. NGSI-LD コンテキスト エンティティの属性を削除

DELETE /ngsi-ld/v1/entities/#eid/attrs/#attrName

パラメーター 説明
eid エンティティ ID
attrName 属性名

例:

curl -iX DELETE http://localhost:80/ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:A100/attrs/brandName1

4.4.1.7. g. 特定のエンティティを取得

GET /ngsi-ld/v1/entities/#eid

パラメーター 説明
eid エンティティ ID

例:

curl http://localhost:80/ngsi-ld/v1/entities/urn:ngsi-ld:Vehicle:A4569

4.4.2. サブスクリプション API

新しいサブスクリプションは、サブスクライバーによって発行され、ブローカーに転送され、そこでサブスクライバーの詳細がノーティフィケーション目的で保存されます。ブローカーは FogFlowDiscovery へのリクエストを開始します。ここで、これは新しいサブスクリプションとして登録され、対応するデータの可用性を探します。データを受信すると、サブスクライブしているブローカーに情報が返されます。

4.4.2.1. a. リンク ヘッダーのコンテキストで新しいサブスクリプションを作成

POST /ngsi-ld/v1/subscriptions

ヘッダー フォーマット

キー バリュー
Content-Type application/ld+json
Link <{{link}}>; rel="https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld"; type="application/ld+json"

リクエスト

curl -iX POST\
  'http://localhost:80/ngsi-ld/v1/subscriptions/' \
   -H 'Content-Type: application/ld+json' \
   -H 'Link: <{{link}}>; rel="https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld"; type="application/ld+json"' \
   -d '
    {
             "type": "Subscription",
             "id"  : "urn:ngsi-ld:Subscription:71",
             "entities": [{
                             "id": "urn:ngsi-ld:Vehicle:71",
                             "type": "Vehicle"
             }],
             "watchedAttributes": ["brandName"],
             "notification": {
                             "attributes": ["brandName"],
                             "format": "keyValues",
                             "endpoint": {
                                             "uri": "http://my.endpoint.org/notify",
                                             "accept": "application/json"
                               }
             }
      }'

4.4.2.2. b. すべてのサブスクリプションを取得

GET /ngsi-ld/v1/subscriptions

例:

curl http://localhost:80/ngsi-ld/v1/subscriptions/ -H 'Accept: application/ld+json'

4.4.2.3. c. サブスクリプション ID に基づいて特定のサブスクリプションを取得

GET /ngsi-ld/v1/subscriptions/#sid

パラメーター 説明
sid サブスクリプション ID

例:

curl http://localhost:80/ngsi-ld/v1/subscriptions/urn:ngsi-ld:Subscription:71

4.4.2.4. d. サブスクリプション ID に基づいて特定のサブスクリプションを削除

DELETE /ngsi-ld/v1/subscriptions/#sid

パラメーター 説明
sid サブスクリプション ID

例:

curl -iX DELETE http://localhost:80/ngsi-ld/v1/subscriptions/urn:ngsi-ld:Subscription