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権限について」を参照してください。

処理イメージ

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

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

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

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

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

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要素の内容(シークレットキー・パスワード)を暗号化することができます。 <起動設定ファイル>に、シークレットキー・パスワードが平文の起動設定ファイル(secretkey要素・password要素のencrypt属性が[false]、またはencrypt属性がない)を指定します。
<暗号化後のファイル名>に指定したファイル名で、シークレットキー・パスワードが暗号化された起動設定ファイルが新規作成されます。
lightbulb「起動設定ファイルのシークレットキー・パスワード暗号化」実行はDataSpiderServerの起動状態に依存しません。

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

プロパティファイルのAWS_SECRET_KEY要素を暗号化することができます。 プロパティファイルがシークレットキーが暗号化されていない状態で-epオプションを指定して実行します。
プロパティファイルに記述されたシークレットキーが暗号化されます。
暗号化前のプロパティファイルは「scriptrunnersqs.properties.bak」に保存されます。
lightbulb「プロパティファイルのシークレットキー暗号化」実行はDataSpiderServerの起動状態に依存しません。
lightbulb-epオプションでは、引数による暗号化対象ファイル名や暗号化後のファイル名の指定はできません。

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

仕様制限

注意事項