ScriptRunner for Amazon SQS

ScriptRunner for Amazon SQSとは

ScriptRunner for Amazon SQSとは、サーバに登録されたサービスのスクリプトをAmazon SQSを経由して実行するためのインターフェースです。 ScriptRunner for Amazon SQSは、スクリプトの実行要求を送信する「ScriptRunner for Amazon SQSクライアント」とスクリプトの実行要求を受信してスクリプトを実行する「ScriptRunner for Amazon SQSマネージャ」で構成されます。

スクリプトの実行要求の受信設定については、コントロールパネルの「ScriptRunner for Amazon SQS設定」を参照してください。

ScriptRunner for Amazon SQSで使用するキューについては、「スクリプト実行要求格納キュー・スクリプト実行結果格納キューについて」を参照してください。

ScriptRunner for Amazon SQSが必要とするIAM権限については、「ScriptRunner for Amazon SQSが必要とするIAM権限について」を参照してください。

処理イメージ

ScriptRunner for Amazon SQSクライアントを起動して、Amazon SQS上のスクリプト実行要求格納キューにスクリプトの実行要求を送信します。
- スクリプトの実行要求を送信後、スクリプト実行結果格納キューを監視し、スクリプトの実行結果を受信するまで待機します。
サーバ側でScriptRunner for Amazon SQSマネージャがAmazon SQS上のスクリプト実行要求格納キューを監視し、スクリプト実行要求を受信します。

ScriptRunner for Amazon SQSマネージャがスクリプトを実行し、終了ステータスやメッセージを取得します。

ScriptRunner for Amazon SQSマネージャがスクリプトの実行結果を、Amazon SQS上のスクリプト実行結果格納キューに応答します。

ScriptRunner for Amazon SQSクライアントがスクリプトの実行結果を受信します。
- ScriptRunner for Amazon SQSクライアントが終了します。

ScriptRunner for Amazon SQSクライアントの起動

Windows版
$DATASPIDER_HOME\<server|client>\binフォルダにある、ScriptRunnerSQS.exeを実行します。

> ScriptRunnerSQS.exe <起動設定ファイル> <第一引数> <第二引数>・・

UNIX/Linux版
$DATASPIDER_HOME/<server|client>/binディレクトリにある、ScriptRunnerSQSを実行します。

> ScriptRunnerSQS <起動設定ファイル> <第一引数> <第二引数>・・

ScriptRunner for Amazon SQSクライアントの起動時に、ScriptRunnerSQS.exeやScriptRunnerSQSの後続に指定する文字列を「コマンドライン引数」と呼びます。
コマンドライン引数では、起動設定ファイルやそのほかの情報を指定します。
コマンドライン引数で指定した値は、起動設定ファイル内で定義された変数に渡されます。

変数の定義方法については、こちらを参照してください。

ScriptRunner for Amazon SQSクライアントが参照する起動設定ファイルに必須のパラメータが定義されていない場合、プロパティファイルの値が参照されます。

プロパティファイルについては、「プロパティファイルによる起動設定の記述」を参照してください。

起動設定ファイル

起動したいスクリプトをこの設定ファイルで指定します。ScriptRunner for Amazon SQSクライアントの第一引数で指定します。

起動設定ファイルの例

<?xml version="1.0" encoding="Shift_JIS"?>
<scriptrunner>
  <connection>
    <credential>
      <accesskey>AKIAIDWXMMTS4L4IXXXXX</accesskey>
      <secretkey>eukotvrxG/7KTT79yAb+Ya0SBVnILxxxxxxxxxx</secretkey>
    </credential>
    <region>ap-northeast-1</region>
    <requestqueuename>runner_sqs_ixxxxx_req</requestqueuename>
    <receivequeuename>runner_sqs_ixxxxx_recv</receivequeuename>
    <description>ScriptRunner for Amazon SQSから実行します。</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 for Amazon SQSでは、params内に指定できるparam要素は一つだけです。

要素

属性

必須/省略可

説明

備考

scriptrunner

必須

connection

必須

接続情報を記述します。scriptrunner要素に一つ記述します。

credential

必須

Amazon Web Servicesのクレデンシャル情報を記述します。scriptrunner要素に一つ記述します。

accesskey

必須

Amazon Web Servicesのアクセスキーを記述します。credential要素に一つ記述します。

secretkey

必須

Amazon Web Servicesのシークレットキーを記述します。credential要素に一つ記述します。

encrypt

省略可

secretkey要素の内容(シークレットキー)が暗号化されているかどうかを表します。

[true]:
シークレットキーは暗号化されているとみなします。
[false]:(デフォルト)
シークレットキーは暗号化されていないとみなします。

encrypt属性の内容が[true]以外、または省略した場合、[false]を設定します。

encrypt設定に関わらずAmazon Web Servicesとの通信は復号後のシークレットキーを用いますが、Amazon Web Servicesとの通信全体がHTTPSによって暗号化されます。

平文で指定されているシークレットキーを暗号化する方法については、「起動設定ファイルのシークレットキー、パスワード暗号化」を参照してください。

requestqueuename

必須

スクリプト実行要求格納キューのキュー名を指定します。connection要素に一つ記述します。

receivequeuename

必須

スクリプト実行結果格納キューのキュー名を指定します。connection要素に一つ記述します。

region

必須

requestqueuename・receivequeuenameで指定したキューが所属するリージョンを記述します。connection要素に一つ記述します。
指定できるリージョンは以下の通りです。

リージョン	リージョン名
ap-northeast-1	Asia Pacific (Tokyo)
ap-southeast-1	Asia Pacific (Singapore)
ap-southeast-2	Asia Pacific (Sydney)
us-east-1	US East (N. Virginia)
us-west-1	US West (N. California)
us-west-2	US West (Oregon)
eu-west-1	EU (Ireland)
sa-east-1	South America (Sao Paulo)

receivetimeout

省略可

スクリプトの実行結果の受信を待機する時間(秒)を指定します。省略した場合、3600(1時間)を設定します。

description

省略可

このScriptRunner for Amazon SQSで実行した際のセッションの情報を指定します。ここで指定した情報はコントロールパネルの「タスクマネージャ」の[セッション]タブの[説明]項目に表示される内容です。

user

必須

スクリプトを実行するユーザ

password

必須

スクリプトを実行するユーザのパスワード

encrypt

省略可

password要素の内容(パスワード)が暗号化されているかどうかを表します。

[true]:
パスワードは暗号化されているとみなします。
[false]:(デフォルト)
パスワードは暗号化されていないとみなします。

encrypt属性の内容が[true]以外、または省略した場合、[false]を設定します。

encrypt設定に関わらずAmazon Web Servicesとの通信は復号後のパスワードを用いますが、Amazon Web Servicesとの通信全体がHTTPSによって暗号化されます。

平文で指定されているパスワードを暗号化する方法については、「起動設定ファイルのシークレットキー、パスワード暗号化」を参照してください。

params

必須

param

必須

起動スクリプトの設定をします。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>
    <credential>
      <accesskey>%{1}</accesskey>
      <secretkey>%{2}</secretkey>
    </credential>
    <region>ap-northeast-1</region>
    <requestqueuename>runner_sqs_ixxxxx_req</requestqueuename>
    <receivequeuename>runner_sqs_ixxxxx_recv</receivequeuename>
    <description>ScriptRunner for Amazon SQSから実行します。</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>

コマンドの実行例

> ScriptRunnerSQS.exe <起動設定ファイル> AKIAIDWXMMTS4L4IXX eukotvrxG/7KTT79yAb+Ya0SBVnILxx スクリプト入力変数値

上記例では、「アクセスキー」・「シークレットキー」・「スクリプト名」・「スクリプト入力変数varの値」が、ScriptRunner for Amazon SQSクライアントのコマンドライン引数から値が渡されます。

コマンドライン引数が存在しない場合には空文字が設定されます。

終了ステータス

ScriptRunner for Amazon SQSの終了ステータスは実行スクリプトのend処理の戻り値に設定した場合にはその値が、設定していない場合にはシステムが自動的に設定した戻り値が返されます。

詳細については、「終了ステータス」を参照してください。

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

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

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

> echo %errorlevel%

bash系(UNIX/Linux)の場合

$ echo $?

csh系(UNIX/Linux)の場合

% echo $status

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

スクリプトから終了ステータスが返ってくるまでの待ち時間(タイムアウト時間)を設定することができます。タイムアウトを設定しない場合(デフォルト)の待ち時間は一時間です。
タイムアウトの設定は、起動設定ファイルの「receivetimeout」要素またはプロパティファイルの「RECEIVE_TIMEOUT」要素で行います。

スクリプトが終了する時間よりも起動設定ファイルに指定した時間が短い場合、スクリプトが終了する前にタイムアウトします。このときにスクリプトが強制終了されることはありません。

プロパティファイルによる起動設定の記述

起動設定ファイルに定義するパラメータのうち、「接続情報」のパラメータの一部は、プロパティファイルで指定することも可能です。
プロパティファイルは「$DATASPIDER_HOME/<server|client>/bin/scriptrunnersqs.properties」です。
起動設定ファイルとプロパティファイルの両方に設定値が記述された場合は、起動設定ファイルの記述が優先的に適用されます。

ScriptRunner for Amazon SQSのプロパティ

ScriptRunner for Amazon SQSのプロパティファイルに記述可能なパラメータです。

キー	説明	備考
AWS_ACCESS_KEY	Amazon Web Servicesのアクセスキーです。	起動設定ファイルのaccesskey要素に相当します。
AWS_SECRET_KEY	Amazon Web Servicesのシークレットキーです。	起動設定ファイルのsecretkey要素に相当します。
REQUEST_QUEUE_NAME	スクリプト実行要求格納キューのキュー名です。	起動設定ファイルのrequestqueuename要素に相当します。
RECEIVE_QUEUE_NAME	スクリプト実行結果格納キューのキュー名を指定します。	起動設定ファイルのreceivequeuename要素に相当します。
AWS_REGION	REQUEST_QUEUE_NAMEー・RECEIVE_QUEUE_NAMEで指定したキューが所属するリージョンです。	起動設定ファイルのregion要素に相当します。
RECEIVE_TIMEOUT	スクリプトの実行結果の受信を待機する時間(秒)です。	起動設定ファイルのreceivetimeout要素に相当します。
ENCRYPTED	AWS_SECRET_KEYが暗号化されて保存されている場合に[true]が設定されます。

プロパティファイルの例

AWS_ACCESS_KEY=AKIAIDWXMMTS4xxxxxxx
AWS_SECRET_KEY=eukotvrxG/7KTT79yAb+Ya0SBVnILxxxxxxx
AWS_REGION=ap-northeast-1
REQUEST_QUEUE_NAME=runner_on_demand_ixxxxx_req
RECEIVE_QUEUE_NAME=runner_on_demand_ixxxxx_recv
RECEIVE_TIMEOUT=3600

起動設定ファイルのシークレットキー・パスワード暗号化

起動設定ファイルのsecretkey要素・password要素の内容(シークレットキー・パスワード)を暗号化することができます。

Windows版での実行方法
$DATASPIDER_HOME\<server|client>\binフォルダにあるScriptRunnerSQS.exeを、-eオプションを指定して実行します。

> ScriptRunnerSQS.exe -e <起動設定ファイル> <暗号化後のファイル名>

UNIX/Linux版での実行方法
$DATASPIDER_HOME/<server|client>/binディレクトリにあるScriptRunnerSQSを、-eオプションを指定して実行します。

> ScriptRunnerSQS -e <起動設定ファイル> <暗号化後のファイル名>

<起動設定ファイル>に、シークレットキー・パスワードが平文の起動設定ファイル(secretkey要素・password要素のencrypt属性が[false]、またはencrypt属性がない)を指定します。
<暗号化後のファイル名>に指定したファイル名で、シークレットキー・パスワードが暗号化された起動設定ファイルが新規作成されます。
lightbulb

「起動設定ファイルのシークレットキー・パスワード暗号化」実行はDataSpiderServerの起動状態に依存しません。
lightbulb

シークレットキー・パスワードが暗号化された起動設定ファイルは、暗号化を実行したScriptRunnerSQSでのみ復号できます。

シークレットキー・パスワードが暗号化された起動設定ファイルを別の環境で使用する場合は、以下の手順で再設定が必要となります。

起動設定ファイルを開き、secretkey要素およびpassword要素の値を平文のシークレットキー・パスワードに置き換えます。
secretkey要素およびpassword要素のencrypt属性を [false] にする、または属性を削除します。
使用する環境のScriptRunnerSQSで、起動設定ファイルのシークレットキー・パスワードを暗号化します。

プロパティファイルのシークレットキー暗号化

プロパティファイルのAWS_SECRET_KEY要素を暗号化することができます。

Windows版での実行方法
$DATASPIDER_HOME\<server|client>\binフォルダにあるScriptRunnerSQS.exeを、-epオプションを指定して実行します。

> ScriptRunnerSQS.exe -ep

UNIX/Linux版での実行方法
$DATASPIDER_HOME/<server|client>/binディレクトリにあるScriptRunnerSQSを、-epオプションを指定して実行します。

> ScriptRunnerSQS -ep

プロパティファイルがシークレットキーが暗号化されていない状態で-epオプションを指定して実行します。
プロパティファイルに記述されたシークレットキーが暗号化されます。
暗号化前のプロパティファイルは「scriptrunnersqs.properties.bak」に保存されます。
lightbulb

「プロパティファイルのシークレットキー暗号化」実行はDataSpiderServerの起動状態に依存しません。
lightbulb

-epオプションでは、引数による暗号化対象ファイル名や暗号化後のファイル名の指定はできません。
lightbulb

シークレットキーが暗号化されたプロパティファイルは、暗号化を実行したScriptRunnerSQSでのみ復号できます。

シークレットキーが暗号化されたプロパティファイルを別の環境で使用する場合は、以下の手順で再設定が必要となります。

プロパティファイルを開き、AWS_SECRET_KEYキーの値を平文のシークレットキーに置き換えます。
ENCRYPTEDキーの値を[false]にする、またはENCRYPTEDキーを削除します。
使用する環境のScriptRunnerSQSで、プロパティファイルのシークレットキーを暗号化します。

スクリプト実行要求格納キュー・スクリプト実行結果格納キューについて

スクリプト実行要求格納キュー・スクリプト実行結果格納キューは、ロングポーリングを使用することを推奨します。
- ロングポーリングの設定は、Amazon SQSの「Receive Message Wait Time」で可能です。
- ロングポーリングタイムアウトの推奨値は20秒です。
ScriptRunner for Amazon SQSを経由しないアクセス(メッセージの送信、受信、削除など)は行わないでください。

複数のクライアント環境からScriptRunner for Amazon SQSを実行する場合は、環境ごとに異なるスクリプト実行結果格納キュー(receivequeuename)を設定してください。

仕様制限

バイナリ型の引数をスクリプトに渡すことはできません。

一回の要求で実行できるスクリプトは一つです。

UNIX/Linux環境では終了ステータスは0～255となっている場合があります。そのような環境では終了ステータスは下位8bitの値(符号なし)として出力されます。

コマンドライン引数に空文字や半角スペースのみのデータ、または先頭に半角スペースを含むデータを指定する場合は、「\"」(半角バックスラッシュ+半角ダブルクォーテーション)で囲んでください。
設定例:

> ScriptRunnerSQS.exe scriptrunnersqs.xml \" \"

注意事項

サーバに登録したスクリプトのみ呼び出すことが可能です。

日付/時間型の引数でサポートされている日付フォーマットは「データ型」を参照してください。