User & Programmers Manual

インデックス

使用法

統計情報レジストリ (Stats Registry)

ライブラリは、ライブラリの仕事に関連する統計情報を定期的に報告する仕組みを提供しています。定期統計の使用を有効にするには、設定セクションで説明されているように、設定ファイルで設定する必要があります。

統計情報レジストリには、同じ統計情報を持つ2つの辞書があります。各統計について、辞書の1つは履歴グローバル値を保持し、もう1つは最後の値報告 または 現在値 以降の値を格納します。

現在、統計ライブラリには次の値のみが格納されています :

  • deviceCreationRequests : API に到着したデバイス作成リクエストの数 (結果にかかわらず)
  • deviceRemovalRequests : API に到着した削除デバイスリクエストの数 (結果にかかわらず)
  • measureRequests : ngsiService.update() 関数が呼び出された回数 (結果にかかわらず)

将来、より多くの値がライブラリに追加されます。ライブラリを使用するアプリケーションは、次の関数を使用するだけで、統計情報レジストリに値を追加できます :

iotagentLib.statsRegistry.add('statName', statIncrementalValue, callback)

この関数が初めて呼び出されると、レジストリに新しい統計情報が追加されます。その後の呼び出しでは、現在の測定とグローバル測定の両方に指定された統計情報に値が追加されます。統計は通常どおり各間隔でクリアされます。

アラーム・モジュール

ライブラリには、IoTAgent で生成されたログ・アラームを追跡するために使用できるアラーム・モジュールが用意されています。このモジュールは次を提供します :

  • アラームを上げたり、解除したりする、2つの関数 (raise() および release()) : すべてのアラームは、名前と説明で識別されます。アラームが発生すると、テキスト Raising [%s] のエラーがログされます。アラームが解除されると、対応するテキスト Releasing [%s] がログされます。アラームが複数回発生すると、アラームは1回だけ記録されます。複数回リリースされた場合は、一度だけリリースされます。存在しないアラームを解除しても効果はありません。

  • すべてのアラームをリストし、すべてのアラーム(list() および clean())をクリーンする関数

  • 他の関数を計測する関数です。その関数の1つがエラーを返すとアラームが発生し、成功した場合はアラームが終了します(intercept())。

これらのすべての機能は、ライブラリの .alarms 属性を介してアクセスできます。 The library provide an alarm module that can be used to track through the logs alarms raised in the IoTAgent. This module

ログ

IoT Agent ライブラリは、Logops logging library を使用します。このライブラリは、すべてのモジュール間で共有される logger オブジェクトに必要です。ロギングが IoTAgent の異なるモジュールの間(つまり、IoTAgent ライブラリによって提供されるもの、および特定の IoTAgent 用に作成されるもの)で一貫しているために、logger オブジェクトはl ogModule ライブラリのプロパティにエクスポートされます。エージェントはこのモジュールをロギングに使用する必要があります。

また、IoT Agent ライブラリには、管理者がログ・レベルをリアルタイムで変更および管理できるようにする設定 API が用意されています。この API には、次の2つのアクションがあります :

新しいログ・レベルを設定 (PUT /admin/log)

この操作では、クエリ・パラメータ level を使用して新しいログ・レベルが取得されます。新しいレベルが Logops の有効なレベルである場合(つまり、配列 ['INFO', 'ERROR', 'FATAL', 'DEBUG', 'WARNING'] のいずれかの項目)、将来のログのために自動的に変更されます。

ログ・レベルを取得 (GET /admin/log)

単一の属性 level を持つ json ペイロード内の現在のログ・レベルを返します。

トランザクション

ライブラリは、ノース・バウンドとサウス・バウンドの両方からのリクエストを処理するときにライブラリが実行する実行フローに従うために、トランザクションの概念を実装します。

トランザクションに従うために、着信リクエストごとに新しいドメインが作成されます。ノース・バウンド・リクエストの場合、このドメインは Express ミドルウェアによって自動的に作成され、ユーザからのさらなるアクションは必要ありません。サウス・バウンド・リクエストの場合、ユーザは、ensureSouthboundDomain および finishSouthBoundTransaction を使用してトランザクションの停止を作成する責任があります。この場合、トランザクションは前者への呼び出しから、後者への呼び出しまで続きます。

トランザクション・コリレータは、複数のコンポーネント間のトランザクションのトレースに従うために、すべての IoT プラットフォームに沿って使用されます。これを行うには、プラットフォームの他のコンポーネントに送信されるすべての HTTP リクエストで 、リクエストを生成したトランザクションのコリレータを使用して、Fiware-Correlator という名前の付いたカスタム・ヘッダが送信されます。プラットフォームのコンポーネントがトランザクションを開始する、このヘッダを含むリクエストを受け取ると、コンポーネントは新しいものを作成するのではなく、受信したコリレータを使用してトランザクションを作成します。ヘッダが存在しない場合、またはトランザクションがコンポーネント内で発生した場合、このコンポーネントのトランザクション ID がコリレータとして使用されます。

トランザクションの期間中、コードによって作成されたすべてのログ・エントリは、実行中の操作の現在のトランザクション ID とコリレータを書き込みます。

ライブラリの概要

ライブラリを使用するには、package.json ファイルに次の依存関係を追加します :

"iotagent-node-lib": "*"

このライブラリを使用するには、まず以下を必要とします :

var iotagentLib = require('iotagent-node-lib');

ライブラリは、通信の各方向 (クライアント対サーバとサーバ対クライアント) の4つの機能グループをサポートします(クライアントとサーバの両方のフロー)。各機能セットは、以下のセクションで定義されています。

関数リファレンス

iotagentLib.activate()
シグネチャ
function activate(newConfig, callback)
説明

IoT Agent をアクティブにして、NGSI コール (コンテキスト・プロバイダとして機能する) のリッスンを開始します。また、deviceRegistry.type 設定オプションに基づいて、IoT Agent 用のデバイス・レジストリを作成します。

パラメータ
  • newConfig : コンテキスト・サーバの構成 (設定 セクションで説明)
iotagentLib.deactivate()
シグネチャ
function deactivate(callback)
説明

HTTP サーバを停止します。

パラメータ
iotagentLib.register()
シグネチャ
function registerDevice(deviceObj, callback)
説明

IoT Agent に新しいデバイスを登録します。この登録はまた、すべての遅延属性のために Context Broker にコンテキスト・プロバイダのレジストレーションをトリガーします。

device オブジェクトは、次の属性を持つことができます :

  • id : デバイスのデバイス ID
  • type : デバイスに割り当てる型
  • name : Context Broker のデバイスを表すエンティティに使用される名前
  • service : デバイスに関連付けられているサービスの名前
  • subservice : デバイスに関連付けられたサブ・サービスの名前
  • lazy : 遅延属性型のリスト
  • active : それらの型のアクティブな属性のリスト
  • staticAttributes : アップデート、クエリ、およびレジストレーションでデバイスのエンティティに "現状のまま" 追加する NGSI 属性のリスト
  • internalAttributes : 任意の IoT Agent がデバイス・レジストリ内のデバイスと共に情報を格納するための、フリーフォーマットのオプション・セクション。

デバイス id と型は、レジストレーションに必須のフィールドです。残りの属性はオプションですが、関数呼び出しの引数に存在しない場合は、その型を設定に登録する必要があります。これにより、サービスは設定済みの型からデフォルト値を推測できます。オプションの属性がパラメーター・リストに指定されておらず、指定された型のデフォルト構成がない場合は、TypeNotFound エラーが発生します。

デバイスが事前にプロビジョニングされている場合は、レジストレーションされたデバイスの値で欠落したデータが完成します。

パラメータ
  • deviceObj : レジストレーションするデバイスに関するすべての情報を含むオブジェクト (必須)
iotagentLib.unregister()
シグネチャ
function unregisterDevice(id, service, subservice, callback)
説明

Context Broker と内部レジストリからデバイスの登録を解除します。

パラメータ
  • id : 登録を解除するデバイスのデバイス ID
  • service : 登録を解除するデバイスのサービス
  • subservice : 登録を解除するデバイスのサービス内のサブ・サービス
iotagentLib.update()
シグネチャ
function update(entityName, attributes, typeInformation, token, callback)
説明

Context Broker 内のデバイスのエンティティで 'attributes' 配列に指定された値で更新を行います。この配列は、NGSIの属性形式に準拠する必要があります。

パラメータ
  • entityName : 登録するエンティティの名前
  • attributes : 更新する値を含む属性配列
  • typeInformation : デバイスの設定情報
  • token : PEP Proxies (オプション) を識別するユーザ・トークン
iotagentLib.setCommandResult()
シグネチャ
function setCommandResult(entityName, resource, apikey, commandName, commandResult, status, deviceInformation, callback)
説明

Context Broker 内のコマンドの結果を更新します。コマンドの結果には2つのコンポーネントがあります。コマンド自体の結果はエンティティ内の _result サフィックスで表され、ステータスは _info サフィックスの属性で更新されます。

パラメータ
  • entityName : コマンドを保持するエンティティの名前
  • resource : デバイスが呼び出しているエンド・ポイントのリソース名
  • apikey : デバイスが値を送信するために使用している Apikey。必要がない場合は空文字列にすることができます
  • commandName : 結果が更新されているコマンドの名前
  • commandResult : 文字列形式でのコマンドの結果
  • deviceInformation : セキュリティおよびサービス情報を含むデバイス情報。(オプション)
iotagentLib.listDevices()
シグネチャ
function listDevices(callback)
function listDevices(limit, offset, callback)
function listDevices(service, subservice, limit, offset, callback)
説明

指定されたサービスとサブ・サービスに登録されているすべてのデバイスのリストを返します。この関数は3つの異なる方法で呼び出すことができます:

  • ただ1つのパラメータ (callback)
  • 3つのパラメータ (service, subservice, callback)
  • または、5つのパラメータ (limit と offsetを含む)
パラメータ
  • service : デバイスが取り出されるサービス
  • subservice : デバイスが取り出されるサブ・サービス
  • limit : 取得する結果の最大数 (オプション)
  • offset : リストからスキップする結果の数 (オプション)
iotagentLib.setDataUpdateHandler()
シグネチャ
function setDataUpdateHandler(newHandler)
説明

エンティティの更新リクエストの新しいユーザ・ハンドラを設定します。このハンドラは、更新リクエストがパラメータ (id, type, service, subservice, attributes, callback) とともに到着するたびに呼び出されます。ハンドラは、デバイス内の対応する値を適切なプロトコルで更新する役割を担っています。

すべての更新が行われたら、更新されたコンテキスト要素を使用してコールバックを呼び出す必要があります。例えば:

    callback(null, {
        type: 'TheType',
        isPattern: false,
        id: 'EntityID',
        attributes: [
            {
                name: 'lumniscence',
                type: 'Lumens',
                value: '432'
            }
        ]
    });

複数のエンティティに影響を及ぼす NGSI リクエストの場合、このハンドラは複数回、各エンティティごとに1回呼び出され、すべての結果が1つのレスポンスに結合されます。

パラメータ
  • newHandler : 更新リクエストのためのユーザ・ハンドラ
iotagentLib.setDataQueryHandler()
シグネチャ
function setDataQueryHandler(newHandler)
説明

エンティティのクエリ・リクエストの新しいユーザ・ハンドラを設定します。このハンドラは、パラメータ (id, type, service, subservice, attributes, callback)でクエリ・リクエストが到着するたびに呼び出されます。ハンドラは、デバイスからすべての対応する情報を取得し、リクエストされた値を持つ NGSI エンティティを返す必要があります。

コールバックは、デバイスから取得した情報を使用して、更新されたコンテキスト要素を使用して呼び出さなければなりません。例えば:

    callback(null, {
        type: 'TheType',
        isPattern: false,
        id: 'EntityID',
        attributes: [
            {
                name: 'lumniscence',
                type: 'Lumens',
                value: '432'
            }
        ]
    });

複数のエンティティに影響を及ぼす NGSI リクエストの場合、このハンドラは複数回、各エンティティごとに1回呼び出され、すべての結果が1つのレスポンスに結合されます。

パラメータ
  • newHandler : クエリ・リクエストのユーザ・ハンドラ
iotagentLib.setNotificationHandler()
シグネチャ
function setNotificationHandler(newHandler)
説明

着信通知用の新しいハンドラを設定します。通知は、subscribe() 関数で作成された IOTA サブスクリプションに基づいて、Context Broker によって送信されます。

ハンドラは次のシグネチャに従わなければなりません:

function mockedHandler(device, data, callback)

device パラメータは、その変更が着信通知で通知されたエンティティに対応するデバイス・オブジェクトを含みます。1つの通知ごとに複数のエンティティを変更できることを考慮してください。これらのエンティティのそれぞれに対してハンドラが1回呼び出されます。

この data パラメータは、サブスクリプションでリクエストされたすべての属性とそれぞれの値を持つ配列です。

ハンドラはコールバックを一度呼び出す必要があります。パラメータを指定しないと、IOTA で予期しない動作が発生する可能性があります。

iotagentLib.setConfigurationHandler()
シグネチャ
function setConfigurationHandler(newHandler)
説明

設定更新のための新しいユーザ・ハンドラを設定します。このハンドラは、新しい設定が作成されるか、古い設定が更新されるたびに呼び出されます。

ハンドラは次のシグネチャに従わなければなりません :

function(newConfiguration, callback)

newConfiguration パラメータには、新しく作成された設定が含まれます。ハンドラはパラメータなしでコールバックを呼び出すことが期待されます。このハンドラは IoT Agent の再設定目的にのみ使用する必要があります。

複数の更新 (複数のデバイスグループを作成する単一のデバイス設定の POST) の場合、ハンドラは、作成と更新の両方の各設定に対して1回呼び出されます。

iotagentLib.getDevice()
シグネチャ
function getDevice(deviceId, service, subservice, callback)
説明

デバイスに関するすべての情報をデバイス・レジストリから取得します。

パラメータ
  • deviceId : 見つけられるデバイスの ID
  • service : リクエストされたデバイスのサービス
  • subservice : デバイスがリクエストされているサービス内のサブ・サービス
iotagentLib.getDeviceByName()
シグネチャ
function getDeviceByName(deviceName, service, subservice, callback)
説明

エンティティ名に基づいてレジストリからデバイスを取得します。

パラメータ
  • deviceName : デバイスに関連付けられたエンティティの名前
  • service : デバイスが属するサービス
  • subservice : サービス内のディビジョン
iotagentLib.getDevicesByAttribute()
シグネチャ
function getDevicesByAttribute(attributeName, attributeValue, service, subservice, callback)
説明

valuenameという名前の属性を持つすべてのデバイスを取得します。

パラメータ
  • name : 一致させる属性の名前
  • value : 属性で一致させる値
  • service : デバイスが属するサービス
  • subservice : サービス内のディビジョン
iotagentLib.retrieveDevice()
シグネチャ
function retrieveDevice(deviceId, apiKey, callback)
説明

指定された APIKey と DeviceID に基づいてデバイス・リポジトリからデバイスを取得し、指定されたデータが見つからない場合はデバイス ID を作成します。

パラメータ
  • deviceId : 取得または作成したいデバイスのデバイス ID
  • apiKey : デバイス・グループの APIKey またはデフォルトの APIKey
iotagentLib.mergeDeviceWithConfiguration()
シグネチャ
function mergeDeviceWithConfiguration(fields, defaults, deviceData, configuration, callback)
説明

デバイスの優先順位付きの設定グループ内の情報でデバイスの情報を完成させます。最初の引数は、どのフィールドがマージされるかを示します。

パラメータ
  • fields : マージされるフィールド
  • defaults : 各フィールドにデフォルト値が設定されます
  • deviceData : デバイスデータ
  • configuration : 設定データ
iotagentLib.getConfiguration()
シグネチャ
function getConfiguration(resource, apikey, callback)
説明

指定された (resource, apikey) ペアで識別されるデバイス・グループを取得します。

パラメータ
  • resource : プロトコルに依存する IoT Agent における設定の表現
  • apikey : 特定の設定に属していることを証明するためにデバイスが提示する特殊キー
iotagentLib.findConfiguration()
シグネチャ
function findConfiguration(service, subservice, callback)
説明

そのサービスとサブ・サービスに基づいてデバイス・グループを検索します。

パラメータ
  • service : 設定のサービス名
  • subservice : 設定のサブ・サービスの名前
iotagentLib.getEffectiveApiKey()
シグネチャ
function getEffectiveApiKey(service, subservice, type, callback)
説明

選択したサービスがある場合はその API キーを取得し、特定のサービス・キーが存在しない場合はデフォルトの API キーを取得します。

パラメータ
  • service : API キーを取得しているサービスの名前
  • subservice : 取得している API キーを持つサブ・サービスの名前
  • type : デバイスのタイプ
iotagentLib.subscribe()
シグネチャ
function subscribe(device, triggers, content, callback)
説明

選択したデバイスを表すエンティティへの IoTA のサブスクリプションを作成します。

パラメータ
  • device : 特定のデバイスに関するすべての情報を含むオブジェクト
  • トリガ : サブスクリプションをトリガする属性の名前を持つ配列
  • content : 通知で取り出す属性の名前を持つ配列
iotagentLib.unsubscribe()
シグネチャ
function unsubscribe(device, id, callback)
説明

選択したデバイスからその ID で識別される単一のサブスクリプションを削除します。

パラメータ
  • device : 特定のデバイスに関するすべての情報を含むオブジェクト
  • id : 削除するサブスクリプションの ID
iotagentLib.ensureSouthboundDomain()
シグネチャ
function ensureSouthboundTransaction(context, callback)
説明

適切なプラットフォームのロギングに必要なすべての情報、つまり開始日、トランザクション ID、およびコリレータが必要な場合に備えて、現在の操作がトランザクション内で実行されるようにします。関数が前のトランザクションのコンテキストで実行された場合、コンテキストのみが変更され、トランザクション ID と開始時刻が保持されます。

パラメータ
  • context : トランザクションの新しいコンテキスト・データ
iotagentLib.finishSouthBoundTransaction()
function finishSouthboundTransaction(callback)
説明

現行のトランザクションがあれば、そのトランザクションを終了してコンテキストをクリーンアップします。

Generic middlewares

ユーティリティ・ミドルウェアのこのコレクションは、IoTAgent ライブラリのノース・バウンド、および IoTA の他の HTTP ベースの API で使用されることを目指しています。すべてのミドルウェアは、(req, res, next) オブジェクトの Express コンベンションに従っているため、この情報はミドルウェア機能の説明では繰り返されません。すべてのミドルウェアは、標準の Express メカニズムを使用してサーバに追加できます。

iotagentLib.middlewares.handleError()
シグネチャ
function handleError(error, req, res, next)
説明

IoTAs のエラーを処理するための Express ミドルウェア。エラーコードが見つからなかった場合には、エラーを返すコード情報を抽出して 500 を返します。

iotagentLib.middlewares.traceRequest()
シグネチャ
function traceRequest(req, res, next)
説明

デバッグモードで IoTA に到着する完全なリクエストをトレースするための Express ミドルウェアです。

iotagentLib.middlewares.changeLogLevel()
シグネチャ
function changeLogLevel(req, res, next)
説明

ログ・レベルをリクエストで指定されたレベルに変更します。

iotagentLib.middlewares.ensureType()
シグネチャ
function ensureType(req, res, next)
説明

リクエスト・タイプがサポートされているタイプの1つであることを保証します。

iotagentLib.middlewares.validateJson()
シグネチャ
function validateJson(template)
説明

パラメータとして渡された JSON スキーマ・テンプレートに基づいて受信リクエストを検証するミドルウェアを生成します。

指定されたテンプレートでリクエストの検証に使用される Express ミドルウェアを返します。

パラメータ
  • template : リクエストを検証するための JSON キーマ・テンプレート
iotagentLib.middlewares.retrieveVersion()
シグネチャ
function retrieveVersion(req, res, next)
説明

モジュールに格納されているすべての IoTA 情報を返すミドルウェアです。

iotagentLib.middlewares.setIotaInformation()
シグネチャ
function setIotaInformation(newIoTAInfo)
説明

retrieveVersion() ミドルウェアでの使用のために IoTAgent に関する情報を格納します。

パラメータ
  • newIoTAInfo: すべての IoTA 情報を含むオブジェクト

Development documentation

コントリビューション

このプロジェクトへのコントリビューションはすべて歓迎します。コントリビューションすることを計画している開発者は、コントリビューション・ガイドラインにしたがってください。

プロジェクト・ビルド

プロジェクトは Grunt Task Runner を使用して管理されます。

使用可能なタスクのリストについては、次のように入力します :

grunt --help

次のセクションでは、使用可能なオプションについて詳しく説明します。

テスト

Mocha Test Runner + Chai Assertion Library + Sinon Spies, stubs.

テスト環境は、テストの実行中にグローバルに使用できる chai.expectchai.should() を使用して BDD テストスタイルを実行するように事前設定されています。また、Sinon-Chai プラグインも使用できます。

proxyquire でテスト中のモジュールのモックを行うことができます

テストを実行するには、次のように入力します :

grunt test

テストレポートは、TAP または XUnit プラグインを使用してプロジェクト品質メトリックを監視するため、Jenkins と一緒に使用することができます。report/test/unit_tests.tap で、TAP レポートを生成するには、次のように入力します :

grunt test-report

コード・ガイドライン

jshint, gjslint

提供された .jshintrc および .gjslintrc フラグ・ファイルを使用します。後者は Python を必要とし、grunt-init を使用してプロジェクト・スケルトンを作成する際にその使用を無効にすることができます。ソースコードのスタイルを確認するには、次のように入力します :

grunt lint

Checkstyle レポートは Checkstyle プラグインと Violations プラグインを使用してプロジェクト品質メトリックを監視するため、Jenkins と一緒に使用することができます。Checkstyle とJSLint のレポートを report/lint/ に生成するには、次のように入力します :

grunt lint-report

連続テスト (Continuous testing)

src ファイルまたはテストを変更して、継続的なテストをサポートします。連続テストの場合は、次のように入力します :

grunt watch

ソースコード・ドキュメンテーション

dox-foundation

HTML ドキュメントをsite/doc/ に生成します。DocLinks プラグインを使用して jenkins と一緒に使用できます。ソースコードのドキュメントをコンパイルするには、以下を入力します :

grunt doc

コード網羅率 (Code Coverage)

Istanbul

テストのコード・カバレッジを分析します。

HTML カバレッジレポートを site/coverage/ に生成し、サマリを出力するには、次のように入力します :

# Use git-bash on Windows
grunt coverage

Cobertura プラグインを使用して、Jenkinsと一緒にプロジェクト品質メトリクスを監視するために使用できる report/coverage/cobertura-coverage.xml で Cobertura レポートを生成するには、次のように入力します :

# Use git-bash on Windows
grunt coverage-report

循環的複雑度 (Code complexity)

Plato

Plato を使用してコードの複雑さを分析し、そのレポートを site/report/ に保存します。DocLinks プラグインを使用して jenkins と一緒に使用できます。複雑さのレポートでは、次のように入力します :

grunt complexity

PLC

プロジェクトのコントリビュータを更新します。

grunt contributors

開発環境

git フックで環境を初期化してください。

grunt init-dev-env

package.json に次の行を追加するだけなので、すべての開発者にこのタスクを自動的に実行することを強くお勧めします。

{
  "scripts": {
     "postinstall": "grunt init-dev-env"
  }
}

サイト生成

プロジェクトの GitHu bページを生成し、カバレッジ、複雑さ、および JSDocs のページを公開するという面倒な作業があります。GitHub ページを初期化するには、以下を使用します :

grunt init-pages

これにより、リポジトリのルートの下にサイト・フォルダも作成されます。このサイト・フォルダはリポジトリの履歴から切り離され、公開のために作成された gh-pages ブランチに関連付けられています。この初期化アクションは、プロジェクト履歴で一度だけ実行する必要があります。サイトが初期化されたら、次のコマンドで公開します :

grunt site

このコマンドは、開発者が init-dev-env を実行した後にのみ動作します。これは、分離サイトを作成することが目標です。

このコマンドは、カバレッジ、ドキュメント、および複雑なタスクも起動します。上記のセクションを参照してください。