View Categories

3.7 ユーザースクリプトとNx Witnessの連携

0:00 6:01

3.7 ユーザースクリプトとNx Witnessの連携 #

対象機種: AX30 / AX11 / AX21 / AG10 / AG20

この章では、「ユーザースクリプト」を、エッジゲートウェイ上でユーザーが作成・配置するスクリプトとして定義します。これらのスクリプトは、Nx Witnessのイベントアクションに応じて実行され、柔軟な処理や外部システムとの連携を可能にします。

エッジゲートウェイには、イベント発生時にユーザースクリプトを実行するためのアプリケーション amnimo-nx-http-handler があらかじめインストールされています。

Nx Witnessとユーザースクリプトを組み合わせることで、標準機能では対応できない高度な処理や通知、ログ出力などを実現できます。

note 補足: 本機能はエッジゲートウェイのファームウェアのバージョンがV3.4.0以降より使用できます。

3.7.1 amnimo-nx-http-handlerの設定 #

Nx Witnessのイベントアクションとしてユーザースクリプトを実行するための設定を行います。

設定方法については『3.5.1 amnimo-nx-http-handlerの設定』を参照ください。

3.7.2 ユーザースクリプトの仕様 #

ユーザースクリプトの連携方法

Nx Witnessと連携させたいユーザースクリプトは、以下のディレクトリに配置してください：

/etc/amnimo/nx-http-handler.d/

引数の内容

ユーザースクリプトには、2つの引数(ファイルパス)を受け取って実行されます。

  1. 第1引数：クエリ情報ファイル
    Nx Witnessの「HTTP(S) リクエスト送信」機能で設定した「HTTP(S) URL」に含まれるクエリパラメータが格納されたファイルです。
    例えば、URLに「?para1=a1&para2=b2」というクエリが含まれている場合、ファイルの内容は以下のようになります。
para1=a1
para2=b2
  1. 第2引数：HTTPコンテンツファイル
    Nx Witnessの「HTTP(S) リクエスト送信」機能で設定した「HTTP(S) コンテンツ」の文字列が格納されています。リクエストメソッドがGETの場合は空のファイルが渡されます。

実行に関する注意点

  • 引数として渡されるファイルは、スクリプトの実行後に自動的に削除されます。
  • スクリプトの実行は逐次的に行われます。1つのスクリプトが完了するまで、次のスクリプトは実行されません。完了に時間がかかる処理を含むスクリプトを実行する場合は、バックグラウンドでの処理を行うよう設計することを推奨します（例：nohupや&を使用）。
  • スクリプトは root権限 で実行されますので、必要に応じて適切な権限管理を行ってください。

3.7.3 ユーザースクリプトの作成例 #

以下に、syslog_logger_sample.sh というユーザースクリプトの作成例を示します。このスクリプトは、受け取ったクエリとコンテンツをsyslogに出力する簡単な例です。

実行環境: エッジゲートウェイ

admin@amnimo:~$ cd /etc/amnimo/nx-http-handler.d/
admin@amnimo:/etc/amnimo/nx-http-handler.d$ sudo vi syslog_logger_sample.sh
syslog_logger_sample.sh
#!/bin/bash

log_file() {
  local prefix="$1"
  local file="$2"
  while IFS= read -r line || [ -n "$line" ]; do
    logger -t syslog_logger_sample.sh -p user.info "[$prefix] $line"
  done < "$file"
}

log_file "query" "$1"
log_file "body" "$2"

実行権の付与

作成したユーザースクリプトに実行権を付与します。

実行環境: エッジゲートウェイ

admin@amnimo:/etc/amnimo/nx-http-handler.d$ sudo chmod +x syslog_logger_sample.sh

archive.listへの追加

作成したユーザースクリプトのファイルパスを、以下のファイルに追記します：

/etc/amnimo/archive.list

この設定により、「設定ファイルの保存」機能を使用した際に、ユーザースクリプトも含めて保存されるようになります。

実行環境: エッジゲートウェイ

admin@amnimo:/etc/amnimo/nx-http-handler.d$ cd /etc/amnimo/
admin@amnimo:/etc/amnimo $ sudo vi archive.list
/etc/amnimo/archive.list
/etc/amnimo/config.yaml
: 途中省略
/etc/amnimo/nx-http-handler.d/syslog_logger_sample.sh ←作成したユーザースクリプトのパスをファイル終端に追加する。

設定ファイルの保存

amsh コマンドを使用して、作成したユーザースクリプトをエッジゲートウェイの設定ファイルに書き込みます。

この操作を行うことで、以下のような状況でもユーザースクリプトが保持されます：

  1. firmware area update コマンドによるファームウェアの全体更新時
  2. 冗長領域側で起動した場合（現在起動していない領域）

実行モード: 管理者モード（amnimo#）／設定モード（amnimo(cfg)#）

実行環境: エッジゲートウェイ

amnimo# config file save startup-config

3.7.4 Nx Witnessのイベント設定 #

任意のNx Witnessイベントに対して、ユーザースクリプトを実行するように設定することが可能です。これにより、特定のイベント発生時に、エッジゲートウェイ上のスクリプトを自動的に呼び出すことができます。

イベントルールの設定は、「ユーザー管理」グループが「管理者」または「パワーユーザー」に属するユーザーのみが行えます。

warning 注意: スクリプトの内容や引数が意図せず変更されることを防ぐため、アカウントの権限設定には十分ご注意ください。特に、スクリプトの編集やイベントルールの変更が可能なユーザーの管理は重要です。

Nx Witnessクライアントアプリの操作

PCからNx Witnessクライアントアプリを起動し、イベントを設定します。エッジゲートウェイ接続後、画面左上の image34 をクリックし、[システムアドミニストレーション] -> [イベントルール]の順にクリックし、イベントルール設定画面を表示します。本画面で以下の設定を行います。

① [追加]ボタンを押し、新たにイベントを作成します。

② [トリガー]に任意のイベントを設定します。

image41

[アクション]に[HTTP(S) リクエストを実行]を選択し、操作したいユーザースクリプトを設定します。

[アクション]の設定内容
項目設定値
動作HTTP(S) リクエストを実行
実行間隔任意の周期（チェックを外した場合は即時実行となります）
HTTP(S) URLhttp://127.0.0.1:8002/api/v1/scripts/<スクリプト名>/<クエリパラメータ>
<スクリプト名>に実行したいスクリプトを記載します。
例) syslog_logger_sample.shを実行する場合
http://127.0.0.1:8002/api/v1/scripts/**syslog_logger_sample.sh/
指定できるスクリプトは /etc/amnimo/nx-http-handler.d/ 以下に作成したユーザースクリプトのみです。
<クエリパラメータ>にスクリプトに渡したいクエリパラメータを記載します。
クエリは&で連結することで複数設定することが可能です。
例) sample.shに「para1=a1、para2=b2」というクエリを設定する場合
http://127.0.0.1:8002/api/v1/scripts/sample.sh/**?para1=a1&para2=b2
※クエリ名は自由に設定することが可能ですが、__script_name__は内部処理
用の予約語の為使用することはできません。
HTTP(S) コンテンツ実行するスクリプトの引数として渡したい文字列を記述します。
リクエストメソッドがGETの場合は設定できません。
一部のイベントでは特定の文字列がイベント情報に置き換えられます。
分析イベントの場合
※1を参照
汎用イベントの場合
※2を参照
詳細については下記URLを参照ください。
How to use a Do HTTP(S) Request action – Network Optix
コンテンツタイプtext/plain または application/json
認証タイプBasic
リクエストメソッドGET または POST
※GETの場合はHTTP(S) コンテンツは設定できません。
ログインnx-http-handler.confに設定したHTTP_IDの値
パスワードnx-http-handler.confに設定したHTTP_PASSWORDの値
※1
{event.source}「Source contains」フィールドの内容に置き換えられます。
{event.caption}「Caption contains」フィールドの内容に置き換えられます。
{event.cameraId}トリガーを発生させたカメラのIDに置き換えられます。
{event.cameraName}トリガーを発生させたカメラの名前に置き換えられます。
{event.eventType}「Event Type」の横にあるドロップダウンリストで選択されたイベントタイプに置き換えられます。
{event.eventName}オブジェクトまたはラインの名前に置き換えられます。
{event.description}「Description contains」フィールドの内容に置き換えられます。
※2
{event.source}「Source contains」フィールドの内容に置き換えられます。
{event.caption}「Caption contains」フィールドの内容に置き換えられます。
{event.description}「Description contains」フィールドの内容に置き換えられます。

3.7.5 カメラからのHTTPリクエストを受け取る #

amnimo-nx-http-handler は、もともと Nx Witness のイベントアクションに応じてスクリプトを実行するための仕組みですが、カメラからエッジゲートウェイに対してHTTPリクエストを送信し、スクリプトを実行させることも可能です。

amnimo-nx-http-handler設定ファイルの変更

/etc/amnimo/nx-http-handler.confファイルを開き、HTTP_ADDRESSを0.0.0.0に書き換えます。これにより、127.0.0.1からのみではなく、外部からの要求にも応答できるようになります。

warning 注意: amnimo-nx-http-handler は HTTP（平文）と Basic 認証で要求を受け付け、ユーザースクリプトを root 権限で実行します。HTTP_ADDRESS を 0.0.0.0 にすると、ID とパスワードが暗号化されずにネットワークを流れます。カメラを接続する LAN 側だけから接続できるように、パケットフィルターで 8002 番ポートへの接続元を制限してください。HTTP_ID と HTTP_PASSWORD には、推測されにくい値を設定してください。

実行環境: エッジゲートウェイ

admin@amnimo:~$ sudo vi /etc/amnimo/nx-http-handler.conf
HTTP_ID=ID                ←任意のIDを設定します。
HTTP_PASSWORD=PASSWORD   ←任意のパスワードを設定します。
HTTP_ADDRESS=0.0.0.0      ←0.0.0.0に書き換えます。
HTTP_PORT=8002
admin@amnimo:~$ sudo systemctl restart amnimo-nx-http-handler    ←サービスの再起動

カメラからのHTTPリクエストを仲介してNx Witnessに汎用イベントを送信する

一部のカメラでは、Nx Witnessに対して直接汎用イベントを送信できない場合があります。Nx Witnessでは、以下の形式で汎用イベントを受け付けています：

  1. GETメソッド + クエリパラメータ
  2. POSTメソッド + JSONファイル

しかし、カメラのHTTPリクエスト機能がこれらの形式に対応していない場合、直接の送信はできません。

代替手段：amnimo-nx-http-handlerの活用

例えば、カメラがPOSTメソッドのみ対応しており、JSONファイルの添付ができない場合は、以下の方法で対応可能です：

  1. カメラから amnimo-nx-http-handler に対して、POSTメソッド + クエリ形式でREST APIを送信します。
  2. amnimo-nx-http-handler が、ユーザースクリプト create_event.sh を呼び出します。
  3. スクリプトがNx Witnessに対して、間接的に汎用イベントを送信します。

この方法により、カメラの制限を回避しつつ、Nx Witnessとの連携を実現できます。

カメラからのHTTPリクエスト例

カメラからは、以下の形式でHTTPリクエストを送信してください。IPアドレスには、カメラからアクセス可能なエッジゲートウェイのIPアドレスを指定します。ID および PASSWORD には、/etc/amnimo/nx-http-handler.conf に設定されている認証情報を使用してください。

http://ID:PASSWORD@192.168.0.254:8002/api/v1/scripts/create_event.sh/?caption=test_caption&source=test_source&description=test_description&metadata={"cameraRefs":["<カメラID>"]}

note 補足: <カメラID> には対象となるカメラのカメラIDを設定してください。カメラID はNx Witnessクライアントアプリから、対象カメラの [カメラ設定] -> [一般]の 詳細情報 から取得できます。

カメラによっては一部の記号を次のようにURLエンコードする必要があります。
” ⇒ %22 、{ ⇒ %7B 、} ⇒ %7D 、[ ⇒ %5B 、] ⇒ %5D

create_event.sh

スクリプトには Nx Witness のユーザー名とパスワードを書きます。作成した後に sudo chmod 700 /etc/amnimo/nx-http-handler.d/create_event.sh を実行し、root 以外が読めないようにしてください。

#!/bin/bash

USER=NX_USER                # Nx WitnessのUSERを設定します。
PASSWORD=NX_PASSWORD        # Nx Witnessのパスワードを設定します。

URL=https://localhost:7001  # https://<server_ip>:<sever_port>

# The first argument is the parameter file path.
PARAM_FILE="$1"
# The second argument is the JSON file path.
JSON_FILE="$2"

# If the first file is not empty, convert its contents to JSON format.
if [ -s "$PARAM_FILE" ]; then
    # Convert key=value to JSON; handle cameraid specially for metadata.
    json_data=$(awk -F= '{
        if ($1 == "cameraid") {
            printf "\"metadata\":{\"cameraRefs\":[\"%s\"]},", $2
        } else if ($2 ~ /^\{/) {
            printf "\"%s\":%s,", $1, $2
        } else {
            printf "\"%s\":\"%s\",", $1, $2
        }
    }' "$PARAM_FILE" | sed 's/,$//')
    json_data="{$json_data}"
else
    # If the first file is empty, use the contents of the second file as JSON data.
    json_data=$(cat "$JSON_FILE")
fi

# API operations.
# Open a session.
result=$(curl -s -k -X POST "${URL}/rest/v1/login/sessions" \
  -H "accept: application/json" -H "Content-Type: application/json" \
  -d "{\"username\":\"${USER}\",\"password\":\"${PASSWORD}\",\"setCookie\":false}")
token=$(echo $result | jq -r '.token')

# Send createEvent.
curl -s -k -X POST "${URL}/api/createEvent" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${token}" \
  -d "${json_data}" > /dev/null 2>&1

# Close the session.
curl -s -k -X DELETE \
  "${URL}/rest/v1/login/sessions/${token}?setCookie=false&_local=true" \
  -H "accept: */*" \
  -H "Authorization: Bearer ${token}"

一部のカメラではURLエンコードしても "{}[] などの記号を送信できない場合があります。その場合、クエリパラメータに cameraid=<カメラID> を設定することで、metadata={"cameraRefs":["<カメラID>"]} 相当の変換を行います。

ユーザースクリプトの登録方法については『3.7.3 ユーザースクリプトの作成例』を参照ください。

3.7.6 ユーザースクリプト活用例 #

この章では、エッジゲートウェイ上で動作するユーザースクリプトの具体的な活用例を紹介します。

ユーザースクリプトの作成や応用に役立つヒントとして、ぜひご活用ください。

ユーザースクリプトの登録方法については『3.7.3 ユーザースクリプトの作成例』を参照ください。

Nx Witnessの設定を保存するボタン

Nx Witnessクライアントアプリ上でカメラ設定やサーバー設定を変更した場合は、エッジゲートウェイ側にも設定を保存する必要があります。このスクリプトを使用することで、Nx Witnessクライアントアプリから簡単に設定内容をエッジゲートウェイに保存できるようになります。

note 補足: CLIまたはGUIにてNx Witnessパスワードの設定が済んでいる必要があります。

Nx Witnessパスワード設定については、『エッジゲートウェイシリーズCLIユーザーズマニュアル』もしくは『エッジゲートウェイシリーズGUIユーザーズマニュアル』をご確認ください。

amcfgnx_save.sh
#!/bin/bash

amcfgnx save

以下のようにイベントルールを設定します。image42

カメラ画像の右下部分に「設定保存」ボタンが表示されるようになります。このボタンをクリックすることで設定内容がエッジゲートウェイに保存されます。

image43
What are your Feelings
上部へスクロール