4.2.9　ターミナルコマンド実行部品

機能

ターミナル接続部品で接続した操作対象の機器で，指定したコマンドを実行できます。

ターミナルコマンド実行部品に指定したコマンドは，ターミナル接続部品で認証したユーザーの権限で実行されます。コマンドを管理者権限で実行したい場合は，ターミナルコマンド実行部品で管理者権限に昇格するコマンドを実行してください。

実行時の前提条件

JP1/AOサーバとの通信に使用できるプロトコルは，ターミナル接続部品のプロパティ「protocol」で指定されたプロトコルとなります。詳細については，「4.2.8　ターミナル接続部品」のプロパティ「protocol」の説明を参照してください。
エージェントレス接続先として使用できる操作対象の機器については，「付録A.1(3)　エージェントレス接続先として使用できる操作対象の機器」を参照してください。
ターミナル接続部品を実行して，操作対象の機器と接続している必要があります。

注意事項

プロパティ「readWaitTime」に指定した時間だけ，標準出力が出力されるのを待ちます。標準出力の出力が中断してから，プロパティ「readWaitTime」に指定した時間を経過すると，部品の実行がエラー終了します。そのため，プロパティ「readWaitTime」の値は，事前に確認してから設定してください。また，標準出力の出力が中断してから，プロパティ「readWaitTime」に指定した時間を経過した場合，それ以降に出力された内容は破棄されます。
標準出力の値が，プロパティ「promptPattern」に指定した正規表現パターンと合致した場合は，その時点で部品は終了します。
コマンドの出力結果がページ単位で表示されると，標準出力が中断したと見なされます。そのため，プロパティ「readWaitTime」に指定した時間を経過すると，部品の実行がエラー終了します。ターミナルコマンド実行部品を使用して実行するコマンドについて，事前にコマンドの出力結果がページ単位で表示されないよう設定してください。
エコーバックされるコマンドラインも標準出力として出力されます。そのため，必要に応じてエコーバックされない設定にしてください。
部品の実行中にタスクを実行停止した場合は，ターミナルコマンド実行部品の処理が完了してからタスクの状態が「失敗」または「正常終了」になります。その後，セッションおよびトークンは破棄されます。部品の実行が終了したときのステップおよびタスクの状態は，ステップの戻り値および後続ステップ実行条件によって決まります。後続ステップ実行条件は，［ステップ作成］ダイアログボックスまたは［ステップ編集］ダイアログボックスで設定できます。
部品の実行中にタスクを強制停止した場合は，標準出力の読み込みおよびプロンプトの検出処理が中断され，タスクの状態が「失敗」になります。その後，セッションおよびトークンは破棄されます。なお，［タスク］画面の［フロー］エリアに表示されるステップの戻り値は，80になります。タスクログに出力される戻り値は，強制停止したタイミングによって異なります。
部品の実行中にタスクを強制停止した場合，プロパティ「commandLine」で指定したコマンドまたはスクリプトの実行結果については製品サポートの対象外となります。
ターミナル接続部品の後続ステップの状態が「失敗」の場合，Telnet接続またはSSH接続が切断されます。そのため，［失敗したステップからリトライ］または［失敗した次のステップからリトライ］でタスクをリトライすると，ターミナルコマンド実行部品の処理は失敗します。ただし，繰り返し実行部品の配下に部品がある場合で，繰り返し実行部品からリトライするときは対象外です。
ターミナルコマンド実行部品の標準出力および標準エラー出力は，JP1/AOのステップの標準出力として出力されます。標準出力および標準エラー出力のサイズは，JP1/AOが受信したバイト数の合計になります。TelnetサーバまたはSSHサーバの設定によって，改行文字LFがCR+LFに置き換わる場合は，改行文字を2バイトとして計算してください。標準出力および標準エラー出力の合計が100KBを超えた場合の処理の実行結果については，製品サポートの対象外となります。事前に，標準出力および標準エラー出力の合計が100KBを超えていないことを確認してください。
操作対象の機器のOSがUNIXで，プロパティ「commandLine」にASCII文字以外を指定したい場合は，「付録A.4　UNIXでASCII文字以外の文字を含むコマンドラインを実行するための前提条件」を参照してください。
ユーザーに入力を求める対話式コマンドおよびスクリプト，GUI表示などにより自動的に終了しないコマンドは実行できません。
操作対象の機器のOS仕様により，プロパティ「commandLine」にコンソールの幅を超えるようなコマンドラインを指定した場合，コマンドラインの文字列を分割して入力する場合があります。このとき，コマンドの実行が完了する前にプロンプトが表示されるため，部品が正しく終了しない場合があります。この場合，コンソールの幅を拡張することで回避することができます。操作対象の機器がLinuxの場合は，以下のコマンドを実行することで，コンソールの幅を拡張することができます。
```
stty cols [コンソール幅]
```
[コンソール幅]には，「プロンプト文字数＋コマンドライン文字数＋10」以上の値を目安として指定してください。拡張したコンソールの幅は，ターミナル切断部品で操作対象の機器との接続を切断するか，セッションおよびトークンが破棄されるまで有効となります。

バージョン

02.00.00

タグ

Terminal

戻り値

戻り値	説明
0〜63	標準出力および標準エラー出力がプロパティ「returnCodePattern」に指定した正規表現パターンと合致した場合は，プロパティ「returnCode」に指定した戻り値を返す。ただし，標準出力および標準エラー出力がプロパティ「returnCodePattern」に指定した正規表現パターンと合致しなかった場合は，プロパティ「defaultReturnCode」に指定した戻り値を返す。そのため，戻り値の意味は，この部品を使用するサービステンプレートごとに異なる。
65	JP1/AOサーバとの接続に失敗した。例えば，部品実行中にJP1/AOサーバが停止された場合が該当する。
66	次のユーザーがJP1ユーザーにマッピングされている。 Administrators グループに所属しないユーザーである。 Administrators グループに所属するビルトイン Administrator以外のユーザーで，UACが有効である。
68	対象のジョブ実行IDに関する情報がない。
69	タスク処理エンジンの環境変数の取得に失敗した。
70	操作対象の機器との接続が切断した。
80	タスクの実行を停止した。
81	部品が不正な状態で呼び出された。
82	タスク処理エンジンからの要求メッセージを正しくパースできない。
83	JP1/AOサーバの環境が壊れている。
84	指定された部品の情報が取得できない。
86	指定したプロパティ値に誤りがある。または，入力プロパティのトークンが不正である。
87	標準出力および標準エラー出力のタイムアウトが発生した。
88	標準出力および標準エラー出力の合計が100KBを超えた。
127	そのほかのエラーが発生した。

プロパティ一覧

プロパティを次の表に示します。

プロパティキー	プロパティ名	説明	デフォルト値	入出力種別	必須区分
token	トークン	ターミナル接続部品のプロパティ「token」の値を指定します。	−	入力	○
commandLine	コマンドライン	操作対象の機器で実行したいコマンドまたはスクリプトの絶対パスを1,024文字以内で指定します。コマンドラインには，JP1/AOサーバのOSと操作対象の機器のOSの両方のコマンドに入力できる文字を指定してください。コマンドラインに環境変数を表す特殊文字などが含まれる場合でも，エスケープされません。特殊文字を文字列として扱いたい場合，操作対象の機器のOSがWindowsのときは「%」で，操作対象の機器のOSがUNIXのときは「¥」でエスケープした文字を設定してください。管理者に昇格する場合など，コマンドラインにスーパーユーザーのパスワードを入力する場合は，予約プロパティ「reserved.terminal.suPassword」を指定します。予約プロパティ「reserved.terminal.account」，「reserved.terminal.password」，および「reserved.terminal.suPassword」は，トークンに関連した認証情報を参照します。トークンに関連した認証情報は，ターミナル接続部品に設定された情報です。認証情報の参照先は，ターミナル接続部品のプロパティ「credentialType」の設定値によって変わります。プロパティ「credentialType」で「destination」を指定している場合予約プロパティの参照先は，エージェントレス接続先に定義された認証情報です。プロパティ「credentialType」で「property」を指定している場合ターミナル接続部品のプロパティ「credentialType」で指定された認証情報です。	−	入力	△
charSet^※1	文字セット	操作対象の機器への標準入力の書き込みと，標準出力および標準エラー出力の読み込みに使用する文字セットを指定します。操作対象の機器にログインするユーザーに設定されている文字セットと，同一の文字セットを指定してください。大文字と小文字は区別されません。指定できる文字セットを次に示します。 EUC-JP eucjp ibm-943C ISO-8859-1 MS932 PCK Shift_JIS UTF-8 windows-31j	−	入力	△
lineEnd	行端文字	プロパティ「commandLine」で設定した値に付加する行端文字を指定します。指定できる行端文字を次に示します。 CR LF CRLF 付加する行端文字が，0x0Dの場合は「CR」，0x0Aの場合は「LF」，0x0D0Aの場合は「CRLF」を指定します。	CR	入力	△
promptPattern	プロンプトパターン	標準出力および標準エラー出力に，プロンプト文字列が出力されたことを検出するための正規表現パターンを1,024文字以内で指定します。このプロパティは，操作対象の機器でコマンドを実行したあと，次のコマンドが実行できる状態であることを判定するために使用します。正規表現パターンはPCREに従って指定してください。指定した正規表現と合致した場合は，その時点で終了します。正規表現パターンと合致しない場合，標準出力および標準エラー出力の出力後，プロパティ「readWaitTime」に設定した時間が経過すると，部品実行がエラー終了します。	−	入力	○
readWaitTime	標準出力待ち時間	コマンドを実行する際に，実行時の標準出力または標準エラー出力が出力されたあとから，次の標準出力または標準エラー出力が出力されるまでのタイムアウト時間を，1〜86,400,000の範囲で指定します。値はミリ秒単位で指定してください。	60000	入力	△
stdoutPattern1	標準出力パターン1	プロパティ「stdoutProperty1」に出力する標準出力および標準エラー出力の正規表現パターンを1,024 文字以内で指定します。正規表現パターンはPCRE に従って指定してください。^※3 設定できる文字列は1,024 文字までです。1,025 文字以降は切り捨てられます。	−	入力	△
stdoutProperty1	標準出力プロパティ1	プロパティ「stdoutPattern1」で切り出した文字列が出力されます。	−	出力	△
stdoutPattern2	標準出力パターン2	プロパティ「stdoutProperty2」に出力する標準出力および標準エラー出力の正規表現パターンを1,024 文字以内で指定します。正規表現パターンはPCRE に従って指定してください。^※3 設定できる文字列は1,024 文字までです。1,025 文字以降は切り捨てられます。	−	入力	△
stdoutProperty2	標準出力プロパティ2	プロパティ「stdoutPattern2」で切り出した文字列が出力されます。	−	出力	△
stdoutPattern3	標準出力パターン3	プロパティ「stdoutProperty3」に出力する標準出力および標準エラー出力の正規表現パターンを1,024 文字以内で指定します。正規表現パターンはPCRE に従って指定してください。^※3 設定できる文字列は1,024 文字までです。1,025 文字以降は切り捨てられます。	−	入力	△
stdoutProperty3	標準出力プロパティ3	プロパティ「stdoutPattern3」で切り出した文字列が出力されます。	−	出力	△
defaultReturnCode	デフォルト戻り値	標準出力および標準エラー出力がプロパティ「returnCodePattern」に指定した正規表現パターンに合致しなかった場合に，部品の戻り値として返される値を指定します。 0〜63の範囲で指定します。	0	入力	△
outputCondition^※2	標準出力プロパティ出力条件	プロパティ「stdoutProperty1〜3」に値を出力する条件を指定します。指定できる値を次に示します。 always 常に「stdoutProperty1〜3」に値を出力します。プロパティ「stdoutPattern1〜3」に合致しなかった場合は空文字を出力します。 patternMatch プロパティ「stdoutPattern1〜3」に合致した場合にプロパティ「stdoutProperty1〜3」に値を出力します。合致しなかった場合は値を出力しません。この場合，プロパティ「stdoutProperty1〜3」にサービスプロパティがマッピングされているときでも値は更新されません。	always	入力	○
returnCodePattern	戻り値判定パターン	標準出力および標準エラー出力の正規表現パターンを1,024 文字以内で指定します。正規表現パターンはPCRE に従って指定してください。指定した値が標準出力および標準エラー出力と合致した場合は，プロパティ「returnCode」に指定した戻り値が返されます。	−	入力	△
returnCode	戻り値	標準出力および標準エラー出力がプロパティ「returnCodePattern」に指定した正規表現パターンに合致した場合に，部品の戻り値として返される値を指定します。0〜63の範囲で指定します。このプロパティを指定しない場合は，プロパティ「defaultReturnCode」に指定した値が返されます。	−	入力	△

注※1

文字セットは，接続先プロパティファイル（接続先名.properties）のterminal.charsetでも設定できます。プロパティ「charSet」および接続先プロパティファイル（接続先名.properties）のterminal.charsetの両方で設定した場合は，プロパティ「charSet」に設定した値が適用されます。どちらにも値が設定されていない場合は，「UTF-8」が設定されます。

注※2

部品のバージョンが02.00.00未満の場合，このプロパティは実装されていませんが，「patternMatch」を指定した場合と同じ動作になります。最新の部品にバージョンアップした場合，このプロパティのデフォルト値に「always」が指定されて動作が変わるので，必要に応じて値を設定し直してください。

注※3

正規表現により抽出されるのは，括弧でグループ化された部分です。
正規表現に複数のグループを指定した場合，最初のグループに該当する範囲だけが部品の出力プロパティに格納されます。
正規表現に複数の範囲が該当する場合，最初に該当する範囲だけが部品の出力プロパティに格納されます。複数の範囲を格納することはできません。
任意のコマンドの実行結果など改行を含む文字列から抽出する場合，改行までの文字列を抽出するには，「(.*)」と指定してください。

プロパティ「stdoutPattern1〜3」および「stdoutProperty1〜3」の使用例

標準出力および標準エラー出力をプロパティ「stdoutPattern1〜3」の値と照合した結果を，プロパティ「stdoutProperty1〜3」にそれぞれ格納できるようになります。次の図に，「stdoutPattern1」に「aaabbb(.*)」を指定した場合のデータの流れを示します。

図4‒4　プロパティ「stdoutPattern」および「stdoutProperty」の使用例

標準出力「aaabbbccc」に対して，「stdoutPattern1」で定義しているように，標準出力の「aaabbb」より後ろの値（ccc）が抽出されます。抽出された値は，プロパティ「stdoutProperty1」に格納されます。

プロパティ「stdoutPattern1〜3」で指定した正規表現が標準出力と合致せず値を抽出できなかった場合に，プロパティ「stdoutProperty1〜3」に値を格納するかどうかは，プロパティ「outputCondition」で指定できます。

関連トピック

〈この項の構成〉

(1)　ターミナルコマンド実行部品の使用例

(1)　ターミナルコマンド実行部品の使用例

標準出力にエラーが出力された場合，ターミナルコマンド実行部品をエラー終了とするときの例

標準出力の内容について，エラーを示す内容を取得し，ターミナルコマンド実行部品をエラー終了したい場合を例に説明します。部品のプロパティに次のような値を設定してください。

プロパティキー	指定値の例	指定値の意味
commandLine	configServer arg0 arg1 arg2	指定したコマンドまたはスクリプトを実行する。
promptPattern	^¥[prompt¥]	標準出力の内容が，「[prompt]」と合致した場合に部品を終了し，戻り値を判定する。
stdoutPattern1	^Message:(.*)	標準出力の内容で，「Message:」より後ろの文字列をプロパティ「stdoutProperty1」に格納する。
stdoutPattern2	^Error:(.*)	標準出力の内容で，「Error:」より後ろの文字列をプロパティ「stdoutProperty2」に格納する。
stdoutPattern3	^ReturnCode:(.*)	標準出力の内容で，「ReturnCode:」より後ろの文字列をプロパティ「stdoutProperty3」に格納する。
defaultReturnCode	0	標準出力の内容が，プロパティ「returnCodePattern」に指定した値と合致しなかった場合に，戻り値0を返す。
returnCodePattern	^Error:	標準出力の内容が，「Error:」と合致した場合，プロパティ「returnCode」で指定した値を返す。
returnCode	1	標準出力の内容が，プロパティ「returnCodePattern」に指定した値と合致した場合に，戻り値1を返す。

このように部品のプロパティを指定している場合，標準出力が次に示す内容だったときの動作について説明します。

[図データ]

標準出力の内容がプロパティ「promptPattern」に指定した値と合致するため，ターミナルコマンド実行部品の戻り値を判定します。このとき，プロパティ「returnCodePattern」に指定した値と合致するため，部品の戻り値は，プロパティ「returnCode」に指定した値（1）になります。

また，プロパティ「stdoutPattern1〜3」で切り出された文字列は，次のとおり，プロパティ「stdoutProperty1〜3」に格納されます。

stdoutProperty1：command failed
stdoutProperty2：Permission Denied
stdoutProperty3：128

HTTPサーバにGetリクエストする場合の例

次のようなリクエストをして，HTTPサーバのレスポンスを確認する場合を例に説明します。

[図データ]

HTTPサーバにGetリクエストする場合，リクエストメソッドとリクエストヘッダーを1行ごとに，ターミナルコマンド実行部品のプロパティ「commandLine」を指定して実行してください。

また，最後に空行を挿入する必要があるため，ターミナルコマンド実行部品を5回実行する必要があります。実行回数ごとにプロパティに設定する値の例を，次の表に示します。

実行回数	commandLineの指定値	lineEndの指定値^※1	promptPatternの指定値
1回目	GET /index.html HTTP/1.1	CRLF	.*^※2
2回目	Host: ServerA	CRLF	.*^※2
3回目	User-Agent: JP1/AO	CRLF	.*^※2
4回目	Accept-Charset: UTF-8	CRLF	.*^※2
5回目	−	CRLF	</HTML>^※3

（凡例）: −：空行を挿入するため，値を指定しない。

注※1: HTTPサーバのリクエストは，[CR]+[LF]を区切り文字とするため，「CRLF」を指定する。

注※2: 1回目〜4回目のターミナルコマンド実行部品のプロパティ「promptPattern」には，空文字でも合致するような正規表現パターンを指定する。

注※3: ターミナルコマンド実行部品の実行後は，標準出力が出力されるため，標準出力の末尾を検出するための正規表現パターンをプロパティ「promptPattern」に指定する。

標準出力の内容が次の場合の動作を説明します。

[図データ]

標準出力の内容がプロパティ「promptPattern」に指定した値と合致するため，ターミナルコマンド実行部品の戻り値を判定します。

プロパティ「returnCodePattern」に指定した値と合致する場合は，プロパティ「returnCode」に指定した値が，部品の戻り値として返されます。

プロパティ「returnCodePattern」に指定した値と合致しない場合は，プロパティ「defaultReturnCode」に指定した値が，部品の戻り値として返されます。

ページの先頭へ

4.2.9 ターミナルコマンド実行部品

(1) ターミナルコマンド実行部品の使用例

4.2.9　ターミナルコマンド実行部品

(1)　ターミナルコマンド実行部品の使用例