MacでのFinderのためのリモートアクションスクリプトの作成 (クラシック)

Nexthink FinderはWindows専用のデスクトップアプリケーションであり、その機能は現在Nexthinkのwebインターフェース内で利用可能です。 Nexthinkはブラウザから直接使用でき、大多数の機能は追加のデスクトップアプリケーションを必要としなくなりました。

macOSコンピュータ上のリモートアクションのペイロードは、従業員のデバイス上で実行されるBashスクリプトです。 Bashは、macOSのような多くのUNIX系オペレーティングシステムによってサポートされているコマンドラインシェルおよびスクリプト言語であり、タスクの自動化および構成管理に適しています。 Bashスクリプトは、デバイスからのオンデマンドデータの取得、自己修復タスクの実行、またはデバイスの構成の変更に理想的であり、これらはリモートアクションの典型的なユースケースです。

この記事では、読者がBashスクリプトに精通していることを前提としています。

詳細については、Remote actions group in Community を参照してください。

エンコーディング

自分のBashスクリプトをリモートアクションのために書くには：

スクリプトのテキストを含むファイルをUTF-8、BOMなしでエンコードします。
コードの各行をUNIXシステムで通常使用される文字：LFで終了させます。

スクリプトファイルに正しいエンコーディングを指定しないと、従業員のデバイス上でリモートアクションを実行することができません。

自分のスクリプトを署名しパッケージ化する

セキュリティ上の理由から、NexthinkではmacOS用のリモートアクションのBashスクリプトにcodesignツールでデジタル署名することを求めています。さらに、署名されたスクリプトをtar.gzファイルとしてパッケージ化し、その拡張属性を保持します。 Finderは、macOSをターゲットとしたリモートアクション用スクリプトのインポート時にtar.gz拡張子のファイルのみを受け入れます。

ステップバイステップガイドについては、Signing remote action scripts on Mac (classic) ドキュメントを参照してください。

汎用スクリプトを書く

特定のユースケースに適応させるためにスクリプトを汎用的に書くことができます。スクリプトを汎用化するには、Bashスクリプトの最初に形式的なパラメータを宣言します。スクリプトを含むリモートアクションを編集する際、Finderでパラメータに実際の値を指定します。

汎用化は、カスタマイズを必要とするデジタル署名済みスクリプトに特に有用です。スクリプトが署名された場合、テキスト内容のいかなる修正も署名を無効にします。署名済みスクリプトを汎用化することで、パラメータを通じたカスタマイズが可能になります。テキストは変更されずにパラメータによってカスタマイズされ、デジタル署名は有効なまま維持されます。リモートアクションからスクリプトに渡されるパラメータの値がスクリプトの実際の動作を決定します。

Bash位置パラメータのためのスクリプト開始時にパラメータを宣言し、次のように特殊なコメントでそれらを囲みます。

# NXT_PARAMETERS_BEGIN
Parameter1=$1
Parameter2=$2
Parameter3=$3
# NXT_PARAMETERS_END

リモートアクション設定中にスクリプトをアップロードすると、システムはBashスクリプト内の特殊なNexthinkコメント間にあるパラメータを認識し、それらをスクリプトテキスト下のParametersセクションに一覧表示します。各パラメータ名の右に表示されるテキスト入力ボックスにパラメータの実際の値を提供します。

実際の値は常にテキストとしてスクリプトに渡されます。スクリプトがstring以外の型でパラメータを宣言している場合、スクリプトが期待する型への変換が可能な値を提供してください。

出力変数

スクリプトの実行により、オンデマンドデータとして保存したい出力を生成することがあります。そのために、Nexthinkは従業員のデバイスにCollectorと同時にインストールされるBashスクリプト（nxt_ra_script_output.sh）を提供しています。このスクリプトには、Engineに結果を書き込むための関数が含まれています。

Nexthinkスクリプトのリモートアクション出力用関数を使用するには、次のヘッダーをBashスクリプトの先頭に追加します。

#!/bin/bash
. "${NEXTHINK}"/bash/nxt_ra_script_output.sh

すべての書き込みメソッドは、出力名と書き込みたい値の2つの引数を受け取ります。例えば、ディレクトリ内のファイル数をEngineに返したいとし、スクリプト内の変数nfilesにその数が保持されているとします。 nfilesの値をFileNumberという名前でEngineに出力として書き込むために、符号なし整数を書く関数を呼び出すには：

nxt_write_output_uint32 'FileNumber' $nfiles

リモートアクションのエディタはスクリプト内の出力を書き込む呼び出しを認識し、スクリプトテキスト下のOutputsセクションに出力変数をリストします。出力ラベルを設定し、調査およびメトリクスでそれをどのように参照するかを示します。

各writeメソッドの末尾が出力の型を示しています。 Bashは緩やかに型付けされた言語であるため、出力型はコンテキストによって解釈されます。下記の表で利用可能なメソッドを確認してください。

nxt 書き込みメソッド

制約

nxt_write_output_string

0 - 1024文字（出力は大きい場合は切り捨て）

nxt_write_output_bool

true / false

nxt_write_output_uint32

最小: 0
最大: 4 294 967 295

nxt_write_output_float

最小: -3.4E+38
最大: 3.4E+38

nxt_write_output_size

最小: 0
最大: 3.4E+38

nxt_write_output_ratio

nxt_write_output_bitrate

nxt_write_output_duration

最小: 0 ms
最大: 49日
ミリ秒単位の精度

nxt_write_output_date_time

DD.MM.YYYY@HH:MM

nxt_write_output_string_list

0 - 1024文字（出力は大きい場合は切り捨て）

自己ヘルプシナリオで従業員と対話する

キャンペーンのUIDを取得する

リモートアクションからキャンペーンを実行する方法には、引数としてUIDキャンペーン識別子を渡す必要があります。

このUIDをリモートアクションに渡すには、リモートアクションのスクリプト内でそれぞれのキャンペーンに必要なパラメータを宣言します。リモートアクションを編集するときにパラメータに実際の値としてUIDを使用します。

キャンペーンのUIDを取得し、リモートアクションのパラメータとして渡すには：

キャンペーンおよびリモートアクションを編集する権限を持つユーザーとしてFinderにログインします。
左側のメニューのCampaignsセクションで、リモートアクションから起動したいキャンペーンの名前を右クリックします。
エクスポート > Campaign Uid to clipboard を選択して、キャンペーンのUIDをコピーします。
左側のメニューのRemote actionsセクションで、キャンペーンを実行するべきリモートアクションの名前をダブルクリックして編集します。リモートアクションはキャンペーンのUIDを収納するためのパラメータを宣言するスクリプトを含むべきです。
スクリプトの下にあるParametersセクションで、キャンペーンのUIDを保持するパラメータを選択します。
Ctrl+Vを押してキャンペーンのUIDを実際に貼り付け、対応するパラメータに割り当てます。

リモートアクションのスクリプトからキャンペーンを実行する

以下の関数はリモートアクションのスクリプト能力を拡張します。

nxt_run_campaign( id )

この関数はパラメータとして渡されたUIDにマッチするキャンペーンを実行し、回答を内部に保存します。

キャンペーンのステータスを受け取った場合、この関数は0を返します。
その他のケースではこの関数は1を返し、エラーがログに記録されます。

この関数を呼び出すことで、従業員がキャンペーンを完了するか、キャンペーンを未表示にするまでリモートアクションの実行が一時停止します。

nxt_run_campaign_with_timeout (id timeout)

この関数は秒単位のタイムアウト(0 < T < 1週間)をパラメータとして渡し、UIDにマッチするキャンペーンを実行し、回答を内部に保存します。

キャンペーンのステータスを受け取った場合、この関数は0を返します。
その他のケースではこの関数は1を返し、エラーがログに記録されます。

この関数を呼び出すことで、従業員がキャンペーンを完了するか、キャンペーンを見逃すか、またはタイムアウトまでにキャンペーンを完了できない場合に、リモートアクションの実行が一時停止します。

nxt_run_standalone_campaign( id )

この関数はパラメータとして渡されたUIDにマッチするキャンペーンを実行し、回答を内部に保存します。

キャンペーンのステータスを受け取った場合、この関数は0を返します。
その他のケースではこの関数は1を返し、エラーがログに記録されます。

この関数を呼び出すとキャンペーンが開始され、リモートアクションの実行が従業員の回答を待たずに続行します。

nxt_get_campaign_status( res_var )

この関数は最後のキャンペーンのステータスを返します。

fully: 従業員がキャンペーンの質問に完全に答えた。
timeout: ユーザーが回答を終える前にキャンペーンのタイムアウトが発生した。
postponed: 従業員がキャンペーンに参加することに同意した。
declined: 従業員がキャンペーンへの参加を辞退した。
connectionfailed: スクリプトがCampaign通知を制御するCollectorコンポーネントに接続できなかった。
notificationfailed: 次のいずれかの理由でキャンペーンの表示に失敗した。
- プラットフォームからキャンペーン定義を取得できなかったため、キャンペーンが存在しないか公開されていない。
- 別のキャンペーンがすでに従業員に表示されている。
- Collectorのフォーカス保護または邪魔しないルールにより非緊急のキャンペーンが表示されない。詳細については、キャンペーン受信率の制限ドキュメントを参照してください。
最後のキャンペーンが失敗した場合には空。

nxt_get_response_answer( res_var question_key)

文字列パラメータquery_keyを使用して、質問ラベルを基に最後のキャンペーンをクエリします。この関数は、回答を文字列値として抽出し、指定された変数res_varに保存します。

キャンペーンのステータスを受け取った場合には0を返します。
それ以外の場合には1を返します。

コード例

キャンペーンの呼び出し

 # これはキャンペーンの基本呼び出しを示す簡単な例です

if nxt_run_campaign "11111111-aaaa-2222-bbbb-333333333333"; then
    nxt_get_campaign_status status
 if [[ status == "fully" ]]; then
        echo "Campaign succeeded"
 else
        echo "Status is $status"
    fi
else
    echo "Campaign failed"
fi

回答へのアクセス

# 応答データへの簡単なアクセス
 
nxt_get_campaign_status status
echo "The response status is $status"
nxt_get_response_answer answersArray key1
echo ${answersArray[1]}

# 注意 - Bashは0からn-1を使用し、Zshは1からnを使用します。

タイムアウト付きキャンペーンの実行

# タイムアウト付きキャンペーンの実行
# タイムアウトは秒単位 (100sまたは00:01:40)

if nxt_run_campaign_with_timeout "11111111-aaaa-2222-bbbb-333333333333" 100; then
    nxt_get_campaign_status status
 if [[ status == "fully" ]]; then
        echo "Campaign succeeded"
 else
        echo "Status is $status"
    fi
else
    echo "Campaign failed"
fi

非ブロッキングキャンペーンの実行

# 非ブロッキングキャンペーンの実行
 
if nxt_run_standalone_campaign "11111111-aaaa-2222-bbbb-333333333333"; then
    nxt_get_campaign_status status
 if [[ status == "fully" ]]; then
        echo "Campaign succeeded"
 else
        echo "Status is $status"
    fi
else
    echo "Campaign failed"
fi

スクリプトの終了とタイムアウト

リモートアクションスクリプトからサブプロセスを起動し、リモートアクションスクリプトが終了またはタイムアウトした場合、Collectorはサブプロセスを自動的に終了します。リモートアクションが終了した後もサブプロセスが実行を続ける場合、スクリプトが&文字を使用してサブプロセスをデタッチにすることを確認してください。例：

some_script.sh -arg1 -arg2 &

Zshコマンドインタープリタ

Collectorバージョン6.27.2以降、Zsh Unixシェル用に書かれたスクリプトを実行できます。シェルスクリプトの冒頭に次のコード行を追加する必要があります：

#!/bin/zsh

これはシェバンとして知られる文字列シーケンスです（シェバン）（外部リンク）。

Macでリモートアクションがトリガーされると、Collectorは最初のコード行をチェックし、指定されたインタープリターを使用して残りの指示を実行します。シェバンのないスクリプトは、Bashコマンドインタープリタを使用して実行されます。

Nexthinkは、シェルスクリプトに常にシェバンを使用し、標準のインタープリタに従うことを推奨します。

この記事で説明されている操作は、NexthinkエンジニアまたはNexthink認定パートナーによってのみ実行される必要があります。

サポートや支援が必要な場合は、Nexthink認定パートナーにお問い合わせください。