Azure Automation で Runbook を開始する

[アーティクル]
06/01/2023

次の表は、特定のシナリオに最も適している、Azure Automation の Runbook を開始する方法を決定するときに役立ちます。この記事には、Azure ポータルと Windows PowerShell を使用して Runbook を開始する詳細情報が含まれます。他の方法の詳細情報については、以下のリンクからアクセスできる他のドキュメントに記されています。

方法	特性
Azure Portal	対話型ユーザーインターフェイスを使用する最も簡単な方法です。単純なパラメーター値を提供するフォームです。ジョブの状態を簡単に追跡できます。 Azure のサインインで認証されたアクセスです。
Windows PowerShell	Windows PowerShell コマンドレットを使用してコマンドラインから呼び出します。複数のステップで自動化された機能に含めることができます。証明書または OAuth ユーザープリンシパル/サービスプリンシパルで要求が認証されます。単純および複雑なパラメーター値を提供します。ジョブの状態を追跡できます。 PowerShell コマンドレットをサポートするために必要なクライアントです。
Azure Automation API	最も柔軟性の高い方法ですが、最も複雑でもあります。 HTTP 要求を発行することが可能なあらゆるカスタムコードから呼び出せます。証明書または OAuth ユーザープリンシパル/サービスプリンシパルでの認証を要求します。単純および複雑なパラメーター値を提供します。 API を使用して Python Runbook を呼び出している場合は、JSON ペイロードをシリアル化する必要があります。ジョブの状態を追跡できます。
Webhook	1 つの HTTP 要求で Runbook を開始します。 URL のセキュリティトークンを使用して認証します。クライアントは Webhook の作成時に指定されたパラメーター値をオーバーライドできません。 Runbook は、HTTP 要求の詳細が含まれる 1 つのパラメーターを定義できます。 Webhook URL でジョブの状態を追跡することはできません。
Azure アラートに応答する	Azure アラートに応答して Runbook を開始します。 runbook 用の Webhook とアラートへのリンクを構成します。 URL のセキュリティトークンを使用して認証します。
スケジュール	時間、日、週、または月単位のスケジュールで Runbook を自動的に開始できます。 Azure ポータル、PowerShell コマンドレット、または Azure API を使用してスケジュールを設定します。スケジュールで使用するパラメーター値を提供します。
別の Runbook から	別の Runbook の活動として Runbook を使用します。複数の Runbook で使用する機能に役立ちます。子 Runbook にパラメーター値を指定し、出力を親 Runbook で使用します。

次の図は、Runbook のライフサイクルにおけるプロセスをステップごとに詳細に示したものです。これには、Azure Automation で Runbook を開始するためのさまざまな方法、Hybrid Runbook Worker で Azure Automation Runbook を実行するために必要な各コンポーネント、異なるコンポーネント間でのやり取りなどが示されています。自社のデータセンターで Automation Runbook を実行する方法については、 Hybrid Runbook Worker

Runbook Architecture

Runbook のパラメーターを使用する

Azure Portal または Windows PowerShell から Runbook を開始する場合、命令は、Azure Automation Web サービスを通じて送信されます。このサービスでは、複雑なデータ型を持つパラメーターはサポートされていません。複合型のパラメーター値を指定する必要がある場合、「 Azure Automation での子 Runbook」で説明されているように別の Runbook からインラインで呼び出す必要があります。

Azure Automation Web サービスは、次のセクションで説明されているように特定のデータ型を使用してパラメーターに対して特殊な機能を提供します。

名前付きの値

パラメーターのデータ型が [object] の場合、 {Name1:'Value1', Name2:'Value2', Name3:'Value3'}という JSON 形式を使用して名前付きの値の一覧を送信できます。これらの値は単純型にする必要があります。 Runbook は、それぞれの名前付き値に対応するプロパティが設定された PSCustomObject としてパラメーターを受け取ります。

user というパラメーターを受け入れる次のテスト Runbook について考慮してください。

Workflow Test-Parameters
{
   param (
      [Parameter(Mandatory=$true)][object]$user
   )
    $userObject = $user | ConvertFrom-JSON
    if ($userObject.Show) {
        foreach ($i in 1..$userObject.RepeatCount) {
            $userObject.FirstName
            $userObject.LastName
        }
    }
}

user パラメーターに対して、次のテキストを使用できます。

{FirstName:'Joe',LastName:'Smith',RepeatCount:'2',Show:'True'}

次の出力が生成されます。

Joe
Smith
Joe
Smith

配列

パラメーターが [array] や [string[]] などの配列の場合、[Value1, Value2, Value3]という JSON 形式を使用して値の一覧を送信できます。これらの値は単純型にする必要があります。

userというパラメーターを受け入れる次のテスト Runbook について考慮してください。

Workflow Test-Parameters
{
   param (
      [Parameter(Mandatory=$true)][array]$user
   )
    if ($user[3]) {
        foreach ($i in 1..$user[2]) {
            $ user[0]
            $ user[1]
        }
    }
}

user パラメーターに対して、次のテキストを使用できます。

["Joe","Smith",2,true]

次の出力が生成されます。

Joe
Smith
Joe
Smith

資格情報

パラメーターのデータ型が PSCredential の場合、Azure Automation の資格情報資産の名前を指定できます。 Runbook は、指定した名前を持つ資格情報を取得します。次のテスト Runbook は、credential というパラメーターを受け入れます。

Workflow Test-Parameters
{
   param (
      [Parameter(Mandatory=$true)][PSCredential]$credential
   )
   $credential.UserName
}

My Credential という資格情報資産がある場合、次のテキストを user パラメーターに使用できます。

My Credential

資格情報のユーザー名が jsmith である場合、次の出力が表示されます。

jsmith

Azure portal で Runbook を開始する

Azure Portal で、[Automation] を選択し、次に Automation アカウントの名前を選択します。
左側のペインから、[Runbook] を選択します。
[Runbook] ページで Runbook を選択し、[開始] をクリックします。
Runbook にパラメーターがある場合は、各パラメーターのテキストボックスに値を指定するように求めるプロンプトが表示されます。パラメーターについて詳しくは、「Runbook のパラメーター」をご覧ください。
[ジョブ] ペインで、Runbook ジョブの状態を表示することができます。

PowerShell で Runbook を開始する

Start-AzAutomationRunbook を使用して、Windows PowerShell で Runbook を開始できます。次のサンプルコードは、Test-Runbook という Runbook を開始します。

Start-AzAutomationRunbook -AutomationAccountName "MyAutomationAccount" -Name "Test-Runbook" -ResourceGroupName "ResourceGroup01"

Start-AzAutomationRunbook は、Runbook の開始後に状態を追跡するために使用できるジョブオブジェクトを返します。次に、このジョブオブジェクトを Get-AzAutomationJob で使用してジョブの状態を判断し、Get-AzAutomationJobOutput で使用してその出力を取得できます。次の例は、Test-Runbook という Runbook を開始し、完了するまで待ってからその出力を表示します。

$runbookName = "Test-Runbook"
$ResourceGroup = "ResourceGroup01"
$AutomationAcct = "MyAutomationAccount"

$job = Start-AzAutomationRunbook -AutomationAccountName $AutomationAcct -Name $runbookName -ResourceGroupName $ResourceGroup

$doLoop = $true
While ($doLoop) {
   $job = Get-AzAutomationJob -AutomationAccountName $AutomationAcct -Id $job.JobId -ResourceGroupName $ResourceGroup
   $status = $job.Status
   $doLoop = (($status -ne "Completed") -and ($status -ne "Failed") -and ($status -ne "Suspended") -and ($status -ne "Stopped"))
}

Get-AzAutomationJobOutput -AutomationAccountName $AutomationAcct -Id $job.JobId -ResourceGroupName $ResourceGroup -Stream Output

Runbook にパラメーターが必要な場合は、ハッシュテーブルとして提供する必要があります。ハッシュテーブルのキーはパラメーター名と一致する必要があり、値はパラメーターの値です。次の例は、FirstName と LastName という 2 つの文字列パラメーターと、RepeatCount という名前の整数、および Show という名前のブール型パラメーターが含まれる Runbook を開始する方法を示します。パラメーターについて詳しくは、「Runbook のパラメーター」をご覧ください。

$params = @{"FirstName"="Joe";"LastName"="Smith";"RepeatCount"=2;"Show"=$true}
Start-AzAutomationRunbook -AutomationAccountName "MyAutomationAccount" -Name "Test-Runbook" -ResourceGroupName "ResourceGroup01" -Parameters $params

次のステップ

Runbook の管理の詳細については「Azure Automation で Runbook を管理する」を参照してください。
PowerShell の詳細については、PowerShell のドキュメントを参照してください。
Runbook の実行に関する問題のトラブルシューティングについては、Runbook の問題のトラブルシューティングに関するページを参照してください。