2.1. Backend 接続用ノード¶

2.1.1. ice backend in¶

バックエンドからエッジサーバに向けて送信されたアクチュエーションメッセージ(オペレーション)をNode-REDのフローに伝達するための入力ノードです。

ice backend inはノードの設定で指定された接続先からのオペレーションのみを受信します。ICE Coreの cloud_config.json で定義した接続先をice backend inから利用できます。

2.1.1.1. 設定項目¶

ice backend inには以下の設定項目があります。

Destination: 接続先のdestination名を設定します。ノード設定上で接続先設定を追加し、追加した接続先設定を選択します。必須項目です。
Routing Rules: バックエンドから受信したメッセージのルーティング規則を設定します。device-config で定義したデバイス設定を使用します。
Name: ノードの名称を設定することができます。

同じdevice-configを重複してRouting Rulesに設定することはできません。その場合、デプロイ時にエラーとなります。

接続先設定の内容に誤りがあり、正常にバックエンドと接続できなかった場合、ノードの起動処理に失敗します。

以下にice backend inの設定例を記載します。

Destination: adm

この例では、admを接続先設定として使用します。

cloud_config.jsonで定義済みのadmを使用した場合、ICE Coreのデフォルト設定では、Backend APIからのオペレーションを受信できるようになります。

Destinationの接続先設定方法については、 Destination を参照してください。

2.1.1.2. ルーティング規則¶

Routing Rulesの項目にルール追加するごとに、ルールに対応したメッセージ出力が追加されます。ルールに設定したdevice-configでメタデータ登録しているデバイスにメッセージが届くように、後続のノードを結線してください。

バックエンドからメッセージ受信すると、Routing Rulesに定義されたルールに従って、メッセージ出力先を決定します。 ice backend inは、メッセージに含まれるobject_idとdevice-config管理下のデバイスのobject_idを比較します。object_idが一致するデバイスが見つかれば、そのデバイスを管理しているdevice-configに対応するメッセージ出力先にメッセージ転送します。

ルールはRouting Rulesの記載順に評価され、一致するルールが見つかれば、残りのルールは無視します。

ice device outを出力ノードとしてデバイスアダプタにメッセージ転送する場合は、ルールの値に”otherwise”を設定してください。 “otherwise”のルールが存在する場合、他ルールに一致しなかったメッセージは全て、そのルールに対応するメッセージ出力先に転送します。

注釈

device-configを使用したルーティングを行うために、ice device adapterノードであらかじめメタデータの登録を行われている必要があります。

2.1.1.3. メッセージ構造¶

ICE CoreとNode-REDのメッセージのマッピングは以下の図のようになります。

msgcloudin

ICE CoreのメッセージはDestinationで設定した接続先から受信したメッセージです。

ICE Coreのメッセージに含まれるpayloadがそのままNode-REDのmsg.payloadに格納されます。payload以外の制御用フィールドはmsg.ice_params配下に格納されます。指定したエッジIDを持つエッジサーバ上で動作するすべてのice backend inに同じメッセージが届きます。

必要に応じてfunctionノード等を利用して、フローごとにメッセージのフィルタリングを行ってください。

mqttの場合、ice_params.adapter.topic_nameにメッセージを受信したトピック名が格納されています。

{
    "ice_params": {
        "adapter": {
            "topic_name": "..."
        }
    }
    "payload": {
    }
}

aws iotのmessageイベントを受信した場合、ice_params.adapterフィールドには以下のような情報が格納されます。

{
    "ice_params": {
        "adapter": {
            "topic_name": "..."
        }
    }
    "payload": {
    }
}

aws iotのdelta/status/foreignStateChangeイベントを受信した場合、ice_params.adapterフィールドには以下のような情報が格納されます。

{
    "ice_params": {
        "adapter": {
            "thing_name": "...",
            "event": "..."
        }
    }
    "payload": {
    }
}

2.1.1.4. Backend APIとの対応¶

ice backend inにオペレーションを送信するためには、以下のBackend APIを実行します。 ※ Destinationにadmを設定した場合に有効です。

PUT /edge/{edge_id}/device/{object_id}?op_type=actuate

  {edge_id}：対象のノードが動作するエッジサーバのエッジID
  {object_id}：メッセージのフィルタリングに使用する任意のID

2.1.2. ice backend out¶

Node-REDのフローからバックエンドにイベントデータを送信するための出力ノードです。

ice backend outはノードの設定で指定された接続先へイベントデータを送信します。ICE Coreの cloud_config.json で定義した接続先をice backend outから利用できます。

2.1.2.1. 設定項目¶

ice backend outには以下の設定項目があります。

Destination: 接続先のdestination名を設定します。ノード設定上で接続先設定を追加し、追加した接続先設定を選択します。必須項目です。
Data Type: バックエンドに送信するイベントデータのデータタイプを指定します。必須項目です。
Overwrite: msg.ice_params.data_typeに値が格納されているとき、Data Typeの値で上書きするかどうかをチェックボックスで指定します。
Name: ノードの名称を設定することができます。

接続先設定の内容に誤りがあり、正常にバックエンドと接続できなかった場合、ノードの起動処理に失敗します。

以下にice backend inの設定例を記載します。

Destination: app
Data Type: nodered
Overwrite: true(チェックボックスオン)

この例では、appを接続先設定として使用します。 cloud_config.jsonで定義済みのappを使用した場合、ICE Coreのデフォルト設定ではICE Backendにイベントデータを送信できるようになります。msg.data_typeの有無にかかわらず、msg.data_typeにnoderedを設定します。

Destinationの接続先設定方法については、 Destination を参照してください。

2.1.2.2. メッセージ構造¶

ICE CoreとNode-REDのメッセージのマッピングは以下の図のようになります。

msgcloudout

ICE CoreのメッセージはDestinationで設定した接続先に送信されるメッセージとなります。

Node-RED側のmsg.payloadは、ICE Coreのメッセージのpayloadに格納します。msg.payloadの型がobjectではない場合のみ、{value: msg.payload}の形式でobject型に変換してpayloadに格納します。

msg.ice_paramsに以下のフィールドが存在していれば、ICE Coreのメッセージに値を渡します。

data_type
object_id
source_id

data_typeはノード設定のData Typeの値で上書きすることも可能です。typeの値はevent_data固定となります。

mqttの場合、ice_params.adapterにトピック名やqosを指定することで、動的にトピック名やqosを変更することが可能です。

{
    "ice_params": {
        "adapter": {
            "qos": 1
            "topic_name": "..."
        }
    }
    "payload": {
    }
}

aws_iotの場合、ice_params.adapterにメソッド名を指定することで、動的に実行するメソッドを変更することが可能です。publishを実行する場合、mqtt同様にqos、topic_nameの指定も可能です。

{
    "ice_params": {
        "adapter": {
            "method": "...",
            "qos": "...",
            "topic_name": "..."
        }
    }
    "payload": {
    }
}

2.1.2.3. Backend APIとの対応¶

ice backend outからICE Backendにデータ送信すると、以下のBackend APIでデータを参照することができます。 ※ Destinationにappを設定した場合に有効です。

GET /backend/event_data/
GET /backend/event_data/{data_type}

  {data_type}:ノード設定したData Typeの値

2.1.3. ノード共通設定¶

2.1.3.1. Destination¶

Destinationで選択する接続先設定の追加方法について説明します。

追加した接続先設定はice backend inとice backend outの間で共有されます。

Destinationの設定には、Mustacheテンプレートを使用することができます。テンプレートの埋め込みは文字列にのみ有効です。

{{edge_id}}

core_config.jsonのedge_idの値を埋め込みます。
{{groups.*}}

core_config.jsonのgroupsの値を埋め込みます。groupsは配列になっているため、配列のインデックスとあわせて、番目の要素をgroups.として指定してください。
{{任意のプロパティ}}

コンテキストに定義した任意プロパティの値を埋め込みます。edge_idやgroups.*をコンテキストに定義している場合、コンテキストの値が優先されます。

2.1.3.1.1. ICEのcloud_config.jsonを利用する場合¶

Use ICE configurationをチェックし、cloud_config.jsonに定義済みの接続先設定のdestination名をDestination Nameに記入してください。

Type以降の設定は不要です。

2.1.3.1.2. ノードの接続先設定を利用する場合¶

Use ICE configurationのチェックを外し、詳細な接続先設定を行います。

2.1.3.1.3. 設定項目一覧¶

接続先設定の設定項目は以下の通りです。

Use ICE configuration: Destinationの設定にICEのcloud_config.jsonを使用するかどうかをチェックボックスで選択します。既定値はfalse。
Destination Name: 接続先設定の名称を指定します。ノード設定のDestinationの表示名となります。cloud_config.jsonで定義済みのdestination名を使用することはできません。必須項目です。
Direction: 通信方向を指定します。ice backend inで使用する場合inputを、ice backend outで使用する場合outputを指定します。
Type: 接続先設定のタイプを選択します。「mqtt」、「http」、「aws_iot」のいずれかを選択可能です。タイプにより、他の設定項目は異なります。

mqttの場合

URL: 接続するMQTTブローカのURLを指定します。SSL/TLS設定を行う場合は、スキームを mqtts:// に変更してください。必須項目です。
Enable SSL/TLS: チェックすると、SSL/TLS用の設定が有効になります。
CA Certificate: MQTTS通信時に使用する{ICE_HOME}/core/confに配置されたCAファイルを指定します。複数指定する場合、[“cacert1.pem”,”cacert2.pem”] のように配列で指定します。
Certificate: MQTTS通信時に使用するクライアント認証用の{ICE_HOME}/core/confに配置された証明書ファイルを指定します。
Private Key: MQTTS通信時に使用するクライアント認証用の{ICE_HOME}/core/confに配置された秘密鍵ファイルを指定します。
Topic Name: メッセージ送受信するトピック名を指定します。必須項目です。ice backend inで使用する場合、複数のトピック名を配列で指定可能です。(例：[“topic_1”,”topic_2”,”topic_3”])
Username: 接続時に使用するユーザ名です。
Password: 接続時に使用するパスワードです。
Timeout: MQTTクライアントのconnect実行時のタイムアウト時間を設定します。Abort if timeoutの設定により、タイムアウト発生時の挙動は異なります。必須項目です。
Abort if timeout: 本設定をチェックしている場合、タイムアウト発生時にICE Coreを終了させます。チェックしない場合、警告ログのみ出力します。
Options: 通信時のオプションをJSON形式で設定します。設定可能な値は mqtt.js をご覧ください。username、passwordについては、Username、Passwordの設定項目の値が優先されます。

httpの場合

URL: 接続するHTTPサーバのURLを指定します。SSL/TLS設定を行う場合は、スキームを https:// に変更してください。須項目です。
Method: HTTPメソッドを指定します。必須項目です。
Enable SSL/TLS: チェックすると、SSL/TLS用の設定が有効になります。
CA Certificate: HTTPS通信時に使用する{ICE_HOME}/core/confに配置されたCAファイルを指定します。複数指定する場合、[“cacert1.pem”,”cacert2.pem”] のように配列で指定します。
Certificate: HTTPS通信時に使用するクライアント認証用の{ICE_HOME}/core/confに配置された証明書ファイルを指定します。
Private Key: HTTPS通信時に使用するクライアント認証用の{ICE_HOME}/core/confに配置された秘密鍵ファイルを指定します。
Enable authentication: チェックすると、認証を行います。認証用の設定が有効になります。
Auth Method: 認証方法を指定します。”nebula”を指定すると、Nebulaのセッショントークン認証を行います。必須項目です。
Login URL: Nebulaのセッショントークン認証の際のログインURLを指定します。必須項目です。
Username: ユーザ名を指定します。E-mail Addressとどちらか一方は必須です。両方を設定している場合、Usernameの値が優先されます。
E-mail Address: メールアドレスを指定します。Usernameとどちらか一方は必須です。両方を設定している場合、Usernameの値が優先されます。
Password: パスワードを指定します。必須項目です。
Request Interval: HTTPリクエスト成功時の次のリクエストまでの間隔をミリ秒で指定します。ice backend inの場合のみ有効です。既定値は10です。
Timeout Interval: HTTPリクエストのタイムアウト発生時の次のリクエストまでの間隔をミリ秒で指定します。ice backend inの場合のみ有効です。既定値は100です。
Error Interval: HTTPリクエストのエラー発生時の次のリクエストまでの間隔をミリ秒で指定します。ice backend inの場合のみ有効です。既定値は1000です。
Max Connections: HTTPクライアントの最大コネクション数を指定します。既定値は128です。0の場合は既定値(128)が設定され、-1の場合は無制限になります。ice backend outの場合のみ有効です。
Request Timeout: HTTPリクエストのタイムアウト時間をミリ秒で指定します。既定値は0(タイムアウトしない)です。
Enable socket keepalive: チェックすると、ソケットのキープアライブを有効にします。
Keepalive Delay: 最後にソケットを使用してからキープアライブ実行するまでの時間をミリ秒で指定します。既定値は0(実行環境の設定に従う)です。
Set http agent ptions: チェックすると、HTTPのエージェントオプションを設定可能になります。
Agent Options: HTTPのエージェントに渡すオプションを指定します。設定可能なプロパティについては、https://nodejs.org/docs/latest-v8.x/api/http.html#http_class_http_agent を参照してください。
Options: 通信時のオプションをJSON形式で指定します。HTTPヘッダを追加する場合、headersフィールドに“ヘッダ名”:”値”を列挙してください。
Use proxy server: チェックすると、プロキシサーバの設定が有効になります。
Proxy Server: プロキシサーバの設定を追加・選択します。必須項目です。

aws_iotの場合

Topic Name: メッセージ送受信するトピック名を指定します。Directionがinputの場合、複数のトピック名を配列で指定可能です。(例：[“topic_1”,”topic_2”,”topic_3”])
QoS: メッセージ送受信時のQoSを指定します。publishメソッド実行時と、messageイベント受信時に有効な設定です。既定値は1です。
Event: AWS IoTクライアントから受信したいイベント名を指定します。Directionがinputの場合のみ設定可能です。allを指定すると、すべてのイベントを受信します。message以外のイベントは、AWS IoT ConfigurationのClient TypeにThing Shadowを指定した場合のみ発生します。
Method: AWS IoTクライアントで実行するメソッドを指定します。Directionがoutputの場合のみ設定可能です。メッセージのice_params.adapter.methodの指定が優先されます。
Publish only payload: publishメソッド実行時に、payloadのみを実行するかどうかを指定します。Directionがoutputの場合のみ設定可能です。チェックした場合、ice_paramsに含まれるedge_id等のICE内部制御用フィールドはAWS IoTに送信されず、payloadの内容のみを送信します。既定値はtrueです。
AWS IoT Configuration: AWS IoTクライアントの設定を追加・選択します。必須項目です。

2.1.3.1.4. プロキシサーバの設定項目¶

DestinationのTypeがhttpの場合に設定可能です。

URL: プロキシサーバのURLを指定します。必須項目です。
Enable SSL/TLS: チェックすると、SSL/TLS用の設定が有効になります。
CA Certificate: プロキシサーバとのHTTPS通信時に使用する{ICE_HOME}/core/confに配置されたCAファイルを指定します。複数指定する場合、[“cacert1.pem”,”cacert2.pem”] のように配列で指定します。
Certificate: プロキシサーバとのHTTPS通信時に使用するクライアント認証用の{ICE_HOME}/core/confに配置された証明書ファイルを指定します。
Private Key: プロキシサーバとのHTTPS通信時に使用するクライアント認証用の{ICE_HOME}/core/confに配置された秘密鍵ファイルを指定します。
Options: プロキシサーバとの通信時のオプションをJSON形式で指定します。HTTPヘッダを追加する場合、headersフィールドに“ヘッダ名”:”値”を列挙してください。

2.1.3.1.5. AWS IoTクライアントの設定項目¶

DestinationのTypeがaws_iotの場合に設定可能です。
ICEではmqttsプロトコルのみをサポートしています。
本設定を作成するごとにAWS IoTクライアントが作成されるので、Client TypeでThing Shadowを指定する場合、通常はThing１つにつき本設定を１つ作成します。１つのThingに対して複数の設定を作成した場合、AWS IoTのThingRegistryで正しく管理されない可能性があります。

Name: AWS IoTクライアント設定の名称です。他の設定と重複しないユニークな名前を設定する必要があります。必須項目です。
Endpoint: 接続先AWS IoTのエンドポイントURLを指定します。必須項目です。
Port: 接続先AWS IoTのポート番号を指定します。既定値は8883です。
Client Type: AWS IoTクライアントのタイプを指定します。”Device”もしくは”Thing Shadow”が選択可能で、”Thing Shadow”を選択した場合はThingShadowとしてregisterを行い、ThingShadowの各種機能(get/update/deleteメソッドやdelta/status/foreignStateChangeイベント)が有効になります。
Thing Name: Thing Shadowの名前を指定します。Client Typeが”Thing Shadow”の場合に設定可能です。既定値は”{{edge_id}}”です。必須項目です。
Thing Shadow Options: Thing Shadowの動作オプションを指定します。Client Typeが”Thing Shadow”の場合に設定可能です。
Thing Shadow RegisterOptions: Thing Shadowのregister時のオプションを指定します。Client Typeが”Thing Shadow”の場合に設定可能です。
Client ID: AWS IoTクライアントのクライアントIDを指定します。既定値は”{{edge_id}}”です。
CA Certificate: AWS IoTとの通信時に使用するCAファイルを指定します。{ICE_HOME}/core/confからの相対パスか、絶対パスで指定可能です。
Certificate: AWS IoTとの通信時に使用するクライアント認証用の証明書ファイルを指定します。{ICE_HOME}/core/confからの相対パスか、絶対パスで指定可能です。
Private Key: AWS IoTとの通信時に使用するクライアント認証用の秘密鍵ファイルを指定します。{ICE_HOME}/core/confからの相対パスか、絶対パスで指定可能です。
Device Options: AWS IoT接続時のオプション設定を指定します。