Runbook の出力とメッセージ

  • [アーティクル]

重要

このバージョンの Service Management Automation (SMA) がサポート終了に達しました。 SMA 2022 にアップグレードすることをお勧めします。

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

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

ストリーム 説明 公開済み テスト
出力 他の Runbook によって使用されることを目的とするオブジェクト。 ジョブ履歴に書き込まれます。 [テスト出力] ウィンドウに表示されます。
警告 ユーザー向けの警告メッセージ。 ジョブ履歴に書き込まれます。 [テスト出力] ウィンドウに表示されます。
エラー ユーザー向けのエラー メッセージ 例外とは異なり、既定では Runbook はエラー メッセージ発行後に実行を継続します。 ジョブ履歴に書き込まれます。 [テスト出力] ウィンドウに表示されます。
"詳細" 一般情報やトラブルシューティング情報を提供するメッセージ。 Runbook の詳細ログが有効な場合のみ、ジョブ履歴に書き込まれます。 Runbook で $VerbosePreference が Continue に設定されている場合にのみ、[テスト出力] ペインに表示されます。
進行状況 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 で使用できるユーザー設定変数と、それらの有効値と既定値を示しています。

注意

この表には、Runbook で有効な値のみが含まれています。 Windows PowerShell を Service Management Automation の外部で使用する場合は、ユーザー設定変数で有効なその他の値があります。

変数 Default value 有効な値
WarningPreference Continue Stop
Continue
SilentlyContinue
ErrorActionPreference Continue Stop
Continue
SilentlyContinue
VerbosePreference SilentlyContinue Stop
Continue
SilentlyContinue

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

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

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

管理ポータル

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

Windows PowerShell

Windows powershell では、 Get SmaJobOutput コマンドレットを使用して、Runbook から出力とメッセージを取得できます。 このコマンドレットにはジョブの ID が必要であり、返すストリームを指定するストリームと呼ばれるパラメーターがあります。 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 を作成します。