Runbook の出力とメッセージ

  • [アーティクル]

ほとんどの Automation Runbook には、ユーザーへのエラー メッセージや、別のワークフローで使用されることを意図した複雑なオブジェクトなど、何らかの形式の出力があります。 Windows PowerShell は、 複数のストリーム を使用してワークフローから出力を送信します。 Service Management Automation は、これらの各ストリームで異なる方法で動作するため、Runbook を作成するときに各ストリームを使用する方法のベスト プラクティスに従う必要があります。

次の表では、公開済みの Runbook を実行する場合と Runbook をテストする場合の、管理ポータルでの各ストリームの簡単な説明とその動作を示しています。 各ストリームの詳細については、以降のセクションで説明します。

ストリーム 説明 公開 テスト
出力 他の Runbook によって使用されることを目的とするオブジェクト。 ジョブ履歴に書き込まれます。 [テスト出力] ウィンドウに表示されます。
警告 ユーザー向けの警告メッセージ。 ジョブ履歴に書き込まれます。 [テスト出力] ウィンドウに表示されます。
エラー ユーザー向けのエラー メッセージ 例外とは異なり、既定では Runbook はエラー メッセージ発行後に実行を継続します。 ジョブ履歴に書き込まれます。 [テスト出力] ウィンドウに表示されます。
詳細 一般情報やトラブルシューティング情報を提供するメッセージ。 Runbook の詳細ログが有効な場合のみ、ジョブ履歴に書き込まれます。 $VerbosePreference が Runbook で [続行] に設定されている場合のみ、テスト出力ウィンドウに表示されます。
進行状況 Runbook の各アクティビティの前後に自動的に生成されるレコード。 Runbook は対話型ユーザーを対象としているため、独自の進行状況レコードの作成を試みるべきではありません。 Runbook の進行状況ログが有効な場合のみ、ジョブ履歴に書き込まれます。 [テスト出力] ウィンドウには表示されません。
デバッグ 対話型ユーザー向けのメッセージ。 Runbook では使用しないでください。 ジョブ履歴には書き込まれません。 [テスト出力] ペインには書き込まれません。

出力ストリーム

出力ストリームは、ワークフローが正常に実行されたときに作成されるオブジェクトの出力を目的としています。 Automation では、このストリームは主に、現在の Runbook を呼び出す 親 Runbook によって使用されることを意図したオブジェクトに使用されます。 親 Runbook から Runbook をインラインで呼び出すと、出力ストリームのデータが親に返されます。 ユーザーに一般情報を返すときは、その Runbook が別の Runbook から呼び出されないことがわかっている場合にのみ、出力ストリームを使用してください。 ただし通常は、ベストプラクティスとして、 詳細ストリーム を使用してユーザーに一般情報を伝えてください。

出力ストリームへのデータの書き込みは、 Write-Output を使用するか、Runbook の行にオブジェクトを配置することで実行できます。

#The following lines both write an object to the output stream.
Write-Object -InputObject $object
$object

関数からの出力

Runbook に含まれている関数から出力ストリームに書き込むと、出力は Runbook に戻されます。 Runbook がその出力を変数に割り当てる場合、出力ストリームには書き込まれません。 関数内から他のストリームへの書き込みは、Runbook の対応するストリームに書き込まれます。

次のサンプル Runbook で考えてみましょう。

Workflow Test-Runbook
{
   Write-Verbose "Verbose outside of function"
   Write-Output "Output outside of function"
   $functionOutput = Test-Function

   Function Test-Function
   {
      Write-Verbose "Verbose inside of function"
      Write-Output "Output inside of function"
   }
}

Runbook ジョブの出力ストリームは次のようになります。

Output outside of function

Runbook ジョブの詳細ストリームは次のようになります。

Verbose outside of function
Verbose inside of function

$FunctionOutput 変数に値を指定します。

Output inside of function

出力のデータ型の宣言

ワークフローでは、 OutputType 属性を使用して、その出力のデータ型を指定できます。 この属性は実行時に影響はありませんが、設計時にRunbook 作成者に対して Runbook の予想される出力を通知します。 Runbook 用のツールセットは進化し続けるため、設計時に出力のデータ型を宣言することの重要性は高まり続けます。 その結果、ベスト プラクティスは、作成するすべての Runbook にこの宣言を含めることです。

次のサンプル Runbook は、文字列オブジェクトを出力し、その出力の型宣言が含まれています。 Runbook が特定の型の配列を出力する場合でも、型の配列ではなく、型を指定してください。

Workflow Test-Runbook
{
   [OutputType([string])]

   $output = "This is some string output."
   Write-Output $output
}

メッセージ ストリーム

出力ストリームとは異なり、メッセージ ストリームはユーザーに情報を伝えるためのものです。 さまざまな種類の情報に対して複数のメッセージ ストリームがあり、それぞれが Automation によって異なる方法で処理されます。

これらのメッセージ ストリームの詳細を確認するには、必要なタブを選択します。

警告およびエラー ストリームは、Runbook で発生する問題をログ記録するためのものです。 これらは、Runbook の実行時にジョブ履歴に書き込まれ、Runbook のテスト時に管理ポータルの [テスト出力] ウィンドウに含まれます。 既定では、Runbook は警告またはエラーの後も引き続き実行されます。 警告またはエラー時に Runbook を中断するように指定することができます。これを行うには、メッセージを作成する前に、Runbook のユーザー設定変数を設定します。 たとえば、Runbook を例外の場合と同様、エラーで中断するようにするには、$ErrorActionPreference を Stop に設定します。

警告またはエラー メッセージを作成するには、Write-Warning または Write-Error コマンドレットを使用します。 アクティビティによってストリームに書き込むことができる場合もあります。

#The following lines create a warning message and then an error message that will suspend the runbook.

$ErrorActionPreference = "Stop"
Write-Warning -Message "This is a warning message."
Write-Error -Message "This is an error message that will stop the runbook because of the preference variable."

進捗状況レコード

進行状況レコードを記録するように Runbook を構成した場合 (管理ポータルの Runbook の [構成] タブで)、レコードは各アクティビティが実行された前後にジョブ履歴に書き込まれます。 ほとんどの場合、パフォーマンスを最大化するために、進行状況レコードを記録しないという Runbook の既定の設定を保持する必要があります。 このオプションを有効にするのは、Runbook のトラブルシューティングやデバッグをする場合のみです。 Runbook をテストする場合、進行状況レコードをログに記録するように Runbook が構成されている場合でも、進行状況メッセージは表示されません。

Write-Progress コマンドレットは、対話型ユーザーでの使用を目的としているため、Runbook では有効ではありません。

ユーザー設定変数

Windows PowerShell では ユーザー設定変数 を使用して、異なる出力ストリームに送信されるデータへの応答方法を決定します。 これらの変数を Runbook で設定することで、異なるストリームに送信されるデータへの応答方法を制御できます。

次の表は、Runbook で使用できるユーザー設定変数と、それらの有効値と既定値を示しています。

Note

この表には、Runbook で有効な値のみが含まれています。 追加の値は、Service Management Automation の外部の Windows PowerShell で使用する場合、基本設定変数に対して有効です。

変数 Default Value 有効な値
WarningPreference 続行 阻止
Continue<\br>
\SilentlyContinue
ErrorActionPreference 続行 Stop
続行
SilentlyContinue
VerbosePreference SilentlyContinue Stop
続行
SilentlyContinue

次の表では、Runbook で有効なユーザー設定変数値の動作を一覧表示します。

Value 動作
続行 メッセージを記録し、Runbook の実行を続けます。
SilentlyContinue メッセージを記録せずに Runbook の実行を続けます。 これはメッセージを無視する効果があります。
阻止 メッセージを記録し、Runbook を中断します。

Runbook の出力とメッセージを取得する

管理ポータル

Runbook の [ジョブ] タブから、管理ポータルで Runbook ジョブの詳細を表示できます。 ジョブの 概要 には、入力パラメーターと Output Stream に加え、ジョブと例外 (発生した場合) に関する全般情報が表示されます。 詳細レコードおよび進捗状況レコードを記録するように Runbook が構成されている場合は、[履歴] に、詳細ストリームと進捗状況レコードだけでなく、出力ストリームと警告およびエラー ストリームからのメッセージも含まれます。

Windows PowerShell

Windows powershell では、 Get SmaJobOutput コマンドレットを使用して、Runbook から出力とメッセージを取得できます。 このコマンドレットはジョブの ID を要求し、返すストリームを指定する Stream というパラメーターを持っています。 [Any] を指定して、ジョブのすべてのストリームを返すことができます。

次の例は、サンプル Runbook を開始し、完了するまで待機します。 完了すると、その出力ストリームがジョブから収集されます。

$webServer = 'https://MyServer'
$port = 9090
$runbookName = "Test-Runbook"
$job = Start-SmaRunbook -WebServiceEndpoint $webServer -Port $port -Name $runbookName

$doLoop = $true
While ($doLoop) {
   $job = Get-SmaJob -WebServiceEndpoint $webServer -Port $port -Id $job.Id
   $status = $job.Status
   $doLoop = (($status -ne "Completed") -and ($status -ne "Failed") -and ($status -ne "Suspended") -and ($status -ne "Stopped")
}

Get-SmaJobOutput -WebServiceEndpoint $webServer -Port $port -Id $job.Id -Stream Output

次のステップ

Automation Runbook を作成する。