ScriptRunner

ScriptRunnerとは

ScriptRunnerとは、サーバに登録されたサービスのスクリプトを外部から実行するためのインターフェースです。スクリプトの実行が完了すると、ScriptRunnerは終了します。

ScriptRunnerの起動

ScriptRunnerは、$DATASPIDER_HOME/<server|client>/binフォルダにある実行ファイルから起動します。 ScriptRunnerの起動時に、実行ファイルの後続に指定する文字列を「コマンドライン引数」と呼びます。
コマンドライン引数では、起動設定ファイルやそのほかの情報を指定します。
起動設定ファイルおよびコマンドライン引数を省略した場合、起動設定ファイルに「$DATASPIDER_HOME/<server|client>/bin/scriptrunner.xml」が適用されます。

コマンドライン引数で指定した値は、起動設定ファイル内で定義された変数に渡されます。
変数の定義方法については、こちらを参照してください。

起動設定ファイル

起動したいスクリプトをこの設定ファイルで指定します。
起動時のファイルの指定方法については、こちらを参照してください。

起動設定ファイルの例

<?xml version="1.0" encoding="Shift_JIS"?>
<scriptrunner>
  <connection>
    <host>localhost</host>
    <port>7700</port>
    <ssl>false</ssl>
    <description>ScriptRunnerから実行します。</description>
    <user>root</user>
    <password>password</password>
  </connection>
  <params>
    <param project="root@project" script="script">
      <input key="var">value</input>
      <option key="TYPE">production</option>
      <option key="ENABLE_TYPE_SWITCH">false</option>
      <option key="ENABLE_XML_LOG">true</option>
      <option key="LOG_LEVEL">FINFO</option>
    </param>
  </params>
</scriptrunner>
TYPEを指定する<option>要素は省略可能です。その場合は、「デフォルト」の種別として実行します。

要素・属性の説明

起動設定ファイルで指定する要素と属性の説明です。

要素 属性 必須/省略可 説明 備考
scriptrunner - 必須    
connection - 必須 接続情報を記述します。scriptrunner要素に一つ記述します。  
host - 省略可 DataSpiderServerホスト名/IPを指定します。省略した場合、127.0.0.1を設定します。  
port - 省略可 DataSpiderServerポート番号を指定します。省略した場合、7700を設定します。
ssl要素の内容が[true]の場合、[コントロールパネル]-[DataSpiderServerの設定]-[セキュリティ]タブで設定されているHTTPSのポート番号を指定してください。		  
ssl - 省略可 DataSpiderServerとHTTPS接続を行うかどうかを指定します。
  • [true]:
    DataSpiderServerとHTTPSで接続します。
    [コントロールパネル]-[DataSpiderServerの設定]-[セキュリティ]タブの[HTTPSを有効にする]にチェックが入っている必要があります。
  • [false]:(デフォルト)
    DataSpiderServerとHTTPで接続します。
    [コントロールパネル]-[DataSpiderServerの設定]-[セキュリティ]タブの[HTTPSを有効にする]にチェックが入っている場合、HTTPSのポートにリダイレクトされます。
ssl要素の内容が[true]以外、または省略した場合、[false]を設定します。 		 
description - 省略可 このScriptRunnerで実行した際のセッションの情報を指定します。ここで指定した情報はコントロールパネルの「タスクマネージャ」の[セッション]タブの[説明]項目に表示される内容です。  
user - 必須 スクリプトを実行するユーザ  
password - 必須 スクリプトを実行するユーザのパスワード  
encrypt 省略可 password要素の内容(パスワード)が暗号化されているかどうかを表します。
  • [true]:
    パスワードは暗号化されているとみなします。
    DataSpiderServerとの通信は復号後の平文のパスワードを用いて行われます。DataSpiderServerとの通信を暗号化したい場合、HTTPS接続を行うようにしてください。
  • [false]:(デフォルト)
    パスワードは暗号化されていないとみなします。
encrypt属性の内容が[true]以外、または省略した場合、[false]を設定します。
平文で指定されているパスワードを暗号化する方法については、「起動設定ファイルのパスワード暗号化」を参照してください。 		 
params - 必須    
param - 必須 起動スクリプトの設定をします。param1つが1つのスクリプトの起動に対応します。params要素に複数のparamを記述できます。  
project 必須 サービス名を指定します。デフォルトのサービス名の形式は<作成者>@<プロジェクト名>となります。  
script 必須 スクリプト名を指定します。  
input - 省略可 スクリプトに渡す引数を設定します。param要素に複数のinputを指定できます。  
key 必須 スクリプトに渡す引数の名前です。スクリプトで設定した引数名と同一である必要があります。  
option - 省略可 スクリプトに渡すオプションです。param要素に複数のoptionを指定できます。
オプションについては、「オプション」を参照してください。		  
key 必須 オプションのキーです。  

input要素のデフォルト値

<input key="var"></input>のように、input要素にkey属性を指定した上で空要素にした場合、key属性に指定したスクリプト変数にそのスクリプト変数の型に応じたデフォルト値を設定します。
lightbulbデザイナで設定したスクリプト変数の初期値を使用したい場合は、その変数をinput要素のkey属性に指定しないようにします。

スクリプト変数の型 デフォルト値 備考
文字列型 空文字  
整数型 0 整数以外の値を指定した場合も「0」が設定されます。(例:文字列)
10進数型 0 10進数以外の値を指定した場合も「0」が設定されます。(例:文字列)
日付/時間型 1970-01-01T09:00:00.000+0900  
真偽値型 false  
バイナリ型 null  
XML型 空文字  

オプション

[option]要素の説明です。

キー 値 説明 備考
TYPE - 実行時の種別を指定します。  
default 「デフォルト」種別で実行します。
TYPEが指定されなかった場合も「デフォルト」で実行します		  
test 「テスト用」種別で実行します。  
production 「本番用」種別で実行します。  
<ユーザ指定種別> サービス登録時、グローバルリソース作成時にユーザが任意で指定した種別で実行します。  
ENABLE_TYPE_SWITCH - 指定した種別のグローバルリソースが存在しなかった場合、種別を切り替えて再検索するかどうかのON/OFFを設定します。  
true 指定した種別のグローバルリソースが存在しなかった場合、「デフォルト」の種別で再検索します。  
false 指定した種別のグローバルリソースが存在しなかった場合、エラーとします。
ENABLE_TYPE_SWITCHが省略された場合は「false」として動作します。		  
ENABLE_XML_LOG - XMLログのON/OFFを設定します。  
true XMLログを出力します  
false XMLログを出力しません(既定値)  
LOG_LEVEL - ログレベルを設定します。  
NOTICE 重要なログのみを出力するログレベル(既定値)  
INFO 運用時推奨のログレベル  
FINFO 開発時推奨のログレベル  
FINEST より詳細にログを出力するログレベル  
DEBUG 非常に詳細なログを出力するログレベル  

変数の定義方法

すべての要素のテキスト値・project属性値・script属性値はコマンドライン引数から値を受け取ることができます。
コマンドライン引数を受け取るためには、起動設定ファイルに%{1}、%{2}、・・・という形式で変数を記述します。

変数を定義した起動設定ファイルの例

<?xml version="1.0" encoding="Shift_JIS"?>
<scriptrunner>
  <connection>
    <host>%{1}</host>
    <port>%{2}</port>
    <ssl>false</ssl>
    <description>ScriptRunnerから実行します。</description>
    <user>root</user>
    <password>password</password>
  </connection>
  <params>
    <param project="root@project" script="%{3}">
      <input key="var">%{4}</input>
      <option key="TYPE">production</option>
      <option key="ENABLE_TYPE_SWITCH">false</option>
      <option key="ENABLE_XML_LOG">true</option>
      <option key="LOG_LEVEL">FINFO</option>
    </param>
  </params>
</scriptrunner>

コマンドの実行例

> ScriptRunner.exe <起動設定ファイル> localhost 7700 スクリプト 入力変数値

上記例では、「ホスト名」・「ポート番号」・「スクリプト名」・「スクリプト入力変数varの値」が、コマンドライン引数から渡されます。
コマンドライン引数が存在しない場合には空文字が設定されます。

ScriptRunner停止に伴うスクリプトプロセスの停止要求

ScriptRunnerが停止した際に、DataSpiderServerがスクリプトプロセスの停止要求を行うように設定できます。

本機能は以下の流れで実行されます。
  1. ScriptRunnerは、定期的に生存報告(自身のプロセスが実行中であること)の通信をDataSpiderServerに行います。
  2. DataSpiderServerは、ScriptRunnerからの生存報告が一定時間ない場合、ScriptRunnerから実行されたスクリプトプロセスの停止要求を行います。
  3. 停止要求の結果、スクリプトプロセスが強制終了されると、XMLログに「InterruptedException」が出力されます。
ScriptRunnerが停止してからスクリプトプロセスの停止要求が行われるまでの時間(上記2.の「一定時間」に該当)は、設定によって調整できます。設定およびデフォルト値については、「ScriptRunnerの停止を検出するためのプロパティ」を参照してください。
ScriptRunnerは、JVMのプロセスを起動します。本機能では、このJVMのプロセスを終了させる必要があります。それによりDataSpiderServerはScriptRunnerの停止を検出し、ScriptRunnerから実行されたスクリプトプロセスの停止要求を行います。
たとえばWindows環境では、ScriptRunnerはJVMのプロセス以外に、実行ファイルなど複数のプロセスを起動します。この場合、JVMのプロセスのみを終了させればスクリプトプロセスの停止要求が行われます。
ScriptRunnerとDataSpiderServer間の通信で障害が発生した場合などでも、ScriptRunnerの停止と検知されることがあります。

ScriptRunnerの停止を検出するためのプロパティ

ScriptRunnerのプロパティファイルに記述可能なパラメータです。
プロパティファイルは「$DATASPIDER_HOME/<server|client>/bin/scriptrunner.properties」です。

キー 説明 備考
cancel.script.on.heartbeat.stop ScriptRunner停止に伴うスクリプトプロセスの停止要求の機能を有効にする場合には「true」を指定します。
  • デフォルト値は「false」です。
  • 「true」の場合、「$DATASPIDER_HOME/<server|client>/bin/ScriptRunner.lax」の「sun.net.client.defaultReadTimeout」の値は無視されます。
heartbeat.period ScriptRunnerからDataSpiderServerに行う生存報告の間隔を指定します。
  • 「cancel.script.on.heartbeat.stop」が「true」の場合、有効になります。
  • デフォルト値は「1000」です。
  • 単位はミリ秒です。
heartbeat.retry.max.count ScriptRunnerからDataSpiderServerへの生存報告が失敗した場合、リトライする回数を指定します。
  • 「cancel.script.on.heartbeat.stop」が「true」の場合、有効になります。
  • デフォルト値は「5」です。
connection.timeout ScriptRunnerからDataSpiderServerへの接続を確立するまでの待ち時間(通信における接続タイムアウト)を指定します。
  • 「cancel.script.on.heartbeat.stop」が「true」の場合、有効になります。
  • デフォルト値は「1000」です。
  • 単位はミリ秒です。
read.timeout ScriptRunnerからDataSpiderServerへ接続した際の応答を受け取るまでの待ち時間(通信における読み取りタイムアウト)を指定します。
  • 「cancel.script.on.heartbeat.stop」が「true」の場合、有効になります。
  • デフォルト値は「3000」です。
  • 単位はミリ秒です。

上記パラメータのデフォルトの動作は、以下の通りです。 通信障害が原因でScriptRunnerが停止したとDataSpiderServerが判断することを避けたい場合などは、環境に合わせて上記パラメータを変更してください。

プロパティファイルの例

cancel.script.on.heartbeat.stop=true
heartbeat.period=1000
connection.timeout=1000
read.timeout=3000
heartbeat.retry.max.count=5

終了ステータス

ScriptRunnerの終了ステータスは実行スクリプトのend処理の戻り値に設定した場合にはその値が、設定していない場合にはシステムが自動的に設定した戻り値が返されます。
詳細については、「終了ステータス」を参照してください。

シェルやコマンドプロンプトから終了ステータスを取得する方法

ScriptRunnerの終了ステータスを取得する方法は、ScriptRunnerを起動したツール(シェルやコマンドプロンプト)によって異なります。

コマンドプロンプト(Windows)の場合

> echo %errorlevel%

bash系(UNIX/Linux)の場合

$ echo $?

csh系(UNIX/Linux)の場合

% echo $status

スクリプト実行のタイムアウト

スクリプトから終了ステータスが返ってくるまでの待ち時間(タイムアウト時間)を設定することができます。タイムアウトを設定しない場合(デフォルト)の待ち時間は無制限です。

タイムアウトの設定は、ScriptRunner.laxで行います。詳細については、「プロパティリファレンス」を参照してください。
スクリプトが終了する時間よりもプロパティに指定した時間が短い場合、スクリプトが終了する前にタイムアウトします。このときにスクリプトが強制終了されることはありません。

起動設定ファイルのパスワード暗号化

最初のコマンドライン引数に-eを指定すると、起動設定ファイルのpassword要素の内容(パスワード)を暗号化することができます。
lightbulb「起動設定ファイルのパスワード暗号化」の実行はDataSpiderServerの起動状態に依存しません。
lightbulbパスワードが暗号化された起動設定ファイルは、暗号化を実行した環境でのみ復号できます。
パスワードが暗号化された起動設定ファイルを別の環境で使用する場合は、再設定が必要となります。

コマンドライン引数

起動設定ファイルのパスワードを暗号化する際に指定するコマンドライン引数の説明です。

使用方法ScriptRunner -e [ -f ] [ -p | -P <パスワード> ] [ <起動設定ファイル> [ <暗号化後のファイル名> ] ]

コマンドライン引数 説明 備考
-e <起動設定ファイル>で指定した起動設定ファイルのpassword要素の内容を暗号化します。
  • 起動設定ファイルのパスワードを暗号化する場合は必須です。
-f <暗号化後のファイル名>で指定したファイルが存在していた場合に上書きします。
  • <暗号化後のファイル名>を省略した場合、<起動設定ファイル>で指定したファイルを上書きします。
-p <起動設定ファイル>で指定したファイルのpassword要素の内容を無視して、プロンプトに標準入力されたパスワードを暗号化します。
  • -pと-Pは同時に指定できません。
-P <パスワード> <起動設定ファイル>で指定したファイルのpassword要素の内容を無視して、コマンドライン引数に指定されたパスワードを暗号化します。
  • -pと-Pは同時に指定できません。
<起動設定ファイル> パスワードを暗号化したい起動設定ファイルを指定します。
  • 省略した場合、「$DATASPIDER_HOME/<server|client>/bin/scriptrunner.xml」が適用されます。
<暗号化後のファイル名> パスワードが暗号化された起動設定ファイルの出力先を指定します。
  • -fを指定した場合、省略できます。

コマンドの実行例

> ScriptRunner.exe -e <起動設定ファイル> <暗号化後のファイル名>
-e のみを指定した場合、<起動設定ファイル>で指定したファイルのパスワードを暗号化して、<暗号化後のファイル名>で指定した出力先に出力します。
パスワードは平文(password要素のencrypt属性が[false]、またはencrypt属性がない)である必要があります。

> ScriptRunner.exe -e -f <起動設定ファイル> <暗号化後のファイル名>
-fと<暗号化後のファイル名>を指定する場合、<暗号化後のファイル名>で指定したファイルを上書きします。

> ScriptRunner.exe -e -f <起動設定ファイル>
-fを指定して<暗号化後のファイル名>を指定しない場合、<起動設定ファイル>で指定したファイルを上書きします。

> ScriptRunner.exe -e -p <起動設定ファイル> <暗号化後のファイル名>
Password: <パスワード>
-pを指定してコマンドを実行するとプロンプトが表示されます。
<パスワード>を入力すると、入力した文字列を暗号化して<暗号化後のファイル名>に出力します。

> ScriptRunner.exe -e -P <パスワード> <起動設定ファイル> <暗号化後のファイル名>
-Pと<パスワード>を指定してコマンドを実行すると、<パスワード>で指定した文字列を暗号化して<暗号化後のファイル名>に出力します。

> ScriptRunner.exe -efp <起動設定ファイル>
Password: <パスワード>
パスワードの暗号化に使用するオプションは、-eを先頭にしてまとめて指定できます。

仕様制限

注意事項