事前および事後スクリプトを管理するManage pre and post scripts

事前および事後スクリプトを使用すると、更新プログラムの展開の前 (事前タスク) と後 (事後タスク) に Automation アカウントで PowerShell Runbook を実行できます。Pre and post scripts let you run PowerShell runbooks in your Automation Account before (pre-task) and after (post-task) an update deployment. 事前および事後スクリプトはローカルではなく、Azure コンテキストで実行されます。Pre and post scripts run in the Azure context and not locally. 事前スクリプトは、更新プログラムのデプロイの開始時に実行されます。Pre-scripts run at the beginning of the update deployment. 事後スクリプトは、展開の最後、構成されているすべての再起動の後で実行されます。Post scripts run at the end of the deployment and after any reboots that are configured.

Runbook の要件Runbook requirements

Runbook が事前または事後スクリプトとして使用されるようにするには、その Runbook をオートメーション アカウントにインポートして発行する必要があります。For a runbook to be used as a pre or post script, the runbook needs to be imported into your automation account and published. このプロセスの詳細については、「Runbook の発行」を参照してください。To learn more about this process, see Publishing a runbook.

事前および事後スクリプトの使用Using a pre/post script

更新プログラムの展開で事前または事後スクリプトを使用するには、更新プログラムの展開の作成から始めます。To use a pre and or post script in an Update Deployment, start by creating an Update Deployment. [Pre-scripts + Post Scripts](事前スクリプト + 事後スクリプト) を選択します。Select Pre-scripts + Post Scripts. この操作で、 [Select Pre-scripts + Post-scripts] (事前スクリプト + 事後スクリプトの選択) ページが開きます。This action opens the Select Pre-scripts + Post-scripts page.

スクリプトを選択する

使用するスクリプトを選択します。この例では、UpdateManagement-TurnOnVms Runbook を使用しました。Select the script you want to use, in this example, you used the UpdateManagement-TurnOnVms runbook. Runbook を選択すると、 [スクリプトの構成] ページが開くので、 [事前スクリプト] を選択します。When you select the runbook the Configure Script page opens, choose Pre-Script. 完了したら、 [OK] をクリックします。Click OK when done.

UpdateManagement-TurnOffVms スクリプトについて、このプロセスを繰り返します。Repeat this process for the UpdateManagement-TurnOffVms script. ただし、 [スクリプトの種類] を選択するときに、 [Post-Script] (事後スクリプト) を選択します。But when choosing the Script type, choose Post-Script.

[Selected items] (選択された項目) セクションに、選択した両方のスクリプトが表示されるようになります。1 つは事前スクリプトであり、もう一方は事後スクリプトです。The Selected items section now shows both your scripts selected and on is a pre-script and the other is a post-script.

[Selected items] (選択された項目)

更新プログラムの展開の構成を完了します。Finish configuring your Update Deployment.

更新プログラムの展開が完了したら、 [Update deployments] (更新プログラムの展開) に移動して結果を表示できます。When your Update Deployment is complete, you can go to Update deployments to view the results. 見てわかるように、事前スクリプトと事後スクリプトの状態が表示されます。As you can see, the status of the pre-script and post-script are provided.

更新プログラムの結果

更新プログラムの展開の実行をクリックすると、事前および事後スクリプトの追加の詳細が表示されます。By clicking into the update deployment run, you're provided additional details to the pre and post scripts. 実行の時点でのスクリプト ソースへのリンクが表示されます。A link to the script source at the time of the run is provided.

展開の実行の結果

パラメーターを渡すPassing parameters

事前および事後スクリプトを構成する場合、Runbook のスケジュール設定のように、パラメーターを渡すことができます。When you configure pre and post scripts, you can pass in parameters just like scheduling a runbook. パラメーターは、更新プログラムの展開の作成の時点で定義されます。Parameters are defined at the time of update deployment creation. 事前および事後スクリプトでは次の型がサポートされます。Pre and Post scripts support the following types:

  • [char][char]
  • [byte][byte]
  • [int][int]
  • [long][long]
  • [decimal][decimal]
  • [single][single]
  • [double][double]
  • [DateTime][DateTime]
  • [string][string]

別のオブジェクト型が必要な場合は、Runbook 内の独自のロジックで別の方にキャストできます。If you need another object type, you can cast it to another type with your own logic in the runbook.

標準の Runbook パラメーターに加えて、追加のパラメーターが表示されます。In addition to your standard runbook parameters, an additional parameter is provided. このパラメーターは SoftwareUpdateConfigurationRunContext です。This parameter is SoftwareUpdateConfigurationRunContext. このパラメーターは JSON 文字列であるため、事前または事後スクリプトで定義すると、このパラメーターは更新プログラムの展開によって自動的に渡されます。This parameter is a JSON string, and if you define the parameter in your pre or post script, it is automatically passed in by the update deployment. このパラメーターには、更新プログラムの展開に関する情報が含まれています。これは、SoftwareUpdateconfigurations API によって返される情報のサブセットです。次の表に、この変数で提供されるプロパティを示します。The parameter contains information about the update deployment, which is a subset of information returned by the SoftwareUpdateconfigurations API The following table shows you the properties that are provided in the variable:

デプロイの停止Stopping a deployment

事前スクリプトに基づくデプロイを停止する場合は、例外をスローする必要があります。If you want to stop a deployment based on a Pre script you must throw an exception. 例外をスローしないと、デプロイと事後スクリプトが引き続き実行されます。If you do not throw an exception, the deployment and Post script will still run. ギャラリー内の Runbook の例に、その方法が示されています。The example runbook in the gallery shows how you can do this. その Runbook からのスニペットを次に示します。The following is a snippet from that runbook.

#In this case, we want to terminate the patch job if any run fails.
#This logic might not hold for all cases - you might want to allow success as long as at least 1 run succeeds
foreach($summary in $finalStatus)
{
    if ($summary.Type -eq "Error")
    {
        #We must throw in order to fail the patch deployment.  
        throw $summary.Summary
    }
}

SoftwareUpdateConfigurationRunContext プロパティSoftwareUpdateConfigurationRunContext properties

プロパティProperty 説明Description
SoftwareUpdateConfigurationNameSoftwareUpdateConfigurationName ソフトウェア更新構成の名前The name of the Software Update Configuration
SoftwareUpdateConfigurationRunIdSoftwareUpdateConfigurationRunId 実行の一意の ID。The unique id for the run.
SoftwareUpdateConfigurationSettingsSoftwareUpdateConfigurationSettings ソフトウェア更新構成に関連したプロパティのコレクションA collection of properties related to the Software Update Configuration
SoftwareUpdateConfigurationSettings.operatingSystemSoftwareUpdateConfigurationSettings.operatingSystem 更新プログラムの展開の対象となるオペレーティング システムThe operating systems targeted for the update deployment
SoftwareUpdateConfigurationSettings.durationSoftwareUpdateConfigurationSettings.duration ISO8601 に従った PT[n]H[n]M[n]S 形式の更新プログラムの展開の実行の最大期間、"メンテナンス期間" とも呼ばれるThe maximum duration of the update deployment run as PT[n]H[n]M[n]S as per ISO8601, also called the "maintenance window"
SoftwareUpdateConfigurationSettings.WindowsSoftwareUpdateConfigurationSettings.Windows Windows コンピューターに関連したプロパティのコレクションA collection of properties related to Windows computers
SoftwareUpdateConfigurationSettings.Windows.excludedKbNumbersSoftwareUpdateConfigurationSettings.Windows.excludedKbNumbers 更新プログラムの展開から除外される KB の一覧A list of KBs that are excluded from the update deployment
SoftwareUpdateConfigurationSettings.Windows.includedUpdateClassificationsSoftwareUpdateConfigurationSettings.Windows.includedUpdateClassifications 更新プログラムの展開のために選択された更新プログラムの分類Update classifications selected for the update deployment
SoftwareUpdateConfigurationSettings.Windows.rebootSettingSoftwareUpdateConfigurationSettings.Windows.rebootSetting 更新プログラムの展開のための再起動設定Reboot settings for the update deployment
azureVirtualMachinesazureVirtualMachines 更新プログラムの展開での Azure VM の resourceId の一覧A list of resourceIds for the Azure VMs in the update deployment
nonAzureComputerNamesnonAzureComputerNames 更新プログラムの展開での Azure 以外のコンピューターの FQDN の一覧A list of the Non-Azure computers FQDNs in the update deployment

次の例は、SoftwareUpdateConfigurationRunContext パラメーターに渡される JSON 文字列です。The following example is a JSON string passed in to the SoftwareUpdateConfigurationRunContext parameter:

"SoftwareUpdateConfigurationRunContext":{
      "SoftwareUpdateConfigurationName":"sampleConfiguration",
      "SoftwareUpdateConfigurationRunId":"00000000-0000-0000-0000-000000000000",
      "SoftwareUpdateConfigurationSettings":{
         "operatingSystem":"Windows",
         "duration":"PT2H0M",
         "windows":{
            "excludedKbNumbers":[
               "168934",
               "168973"
            ],
            "includedUpdateClassifications":"Critical",
            "rebootSetting":"IfRequired"
         },
         "azureVirtualMachines":[
            "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresources/providers/Microsoft.Compute/virtualMachines/vm-01",
            "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresources/providers/Microsoft.Compute/virtualMachines/vm-02",
            "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myresources/providers/Microsoft.Compute/virtualMachines/vm-03"
         ], 
         "nonAzureComputerNames":[
            "box1.contoso.com",
            "box2.contoso.com"
         ]
      }
   }

すべてのプロパティの完全な例は、ソフトウェア更新構成 (名前で取得) に関するページにありますA full example with all properties can be found at: Software Update Configurations - Get By Name

注意

SoftwareUpdateConfigurationRunContext オブジェクトには、マシン用の重複するエントリを含めることができます。The SoftwareUpdateConfigurationRunContext object can contain duplicate entries for machines. これにより、同じマシン上で事前および事後スクリプトを複数回使用できます。This can cause Pre and Post scripts to run multiple times on the same machine. この動作を回避するには、Sort-Object -Unique を使用して、スクリプト内の一意の VM 名だけを選択します。To workaround this behavior, use Sort-Object -Unique to select only unique VM names in your script.

サンプルSamples

事前および事後スクリプトのサンプルは Script Center Gallery にあります。または、Azure Portal 経由でインポートされます。Samples for pre and post scripts can be found in the Script Center Gallery, or imported through the Azure portal. ポータル経由でインポートするには、Automation アカウントで、 [プロセス オートメーション][Runbook ギャラリー] を選択します。To import them through the portal, in your Automation Account, under Process Automation, select Runbooks Gallery. フィルターに [更新管理] を使用します。Use Update Management for the filter.

ギャラリーの一覧

または、次の一覧に示すように、スクリプト名で検索できます。Or you can search for them by their script name as seen in the following list:

  • 更新管理 - VM 有効Update Management - Turn On VMs
  • 更新管理 - VM 無効Update Management - Turn Off VMs
  • 更新管理 - スクリプトをローカルで実行するUpdate Management - Run Script Locally
  • 更新管理 - 事前および事後スクリプトのテンプレートUpdate Management - Template for Pre/Post Scripts
  • 更新管理 - スクリプトを実行コマンドで実行するUpdate Management - Run Script with Run Command

重要

Runbook をインポートした後、使用できるようにするには、それらを発行する必要があります。After you import the runbooks, you must Publish them before they can be used. それを行うには、Automation アカウントで Runbook を見つけ、 [編集] を選択して [発行] をクリックします。To do that find the runbook in your Automation Account, select Edit, and click Publish.

これらのサンプルはすべて、次の例で定義されている基本的なテンプレートに基づいています。The samples are all based on the basic template that is defined in the following example. このテンプレートを使用すると、事前および事後スクリプトで使用する独自の Runbook を作成できます。This template can be used to create your own runbook to use with pre and post scripts. Azure に対して認証したり、SoftwareUpdateConfigurationRunContext パラメーターを処理したりするために必要なロジックが含まれています。The necessary logic for authenticating with Azure and handling the SoftwareUpdateConfigurationRunContext parameter are included.

<# 
.SYNOPSIS 
 Barebones script for Update Management Pre/Post 
 
.DESCRIPTION 
  This script is intended to be run as a part of Update Management Pre/Post scripts.  
  It requires a RunAs account. 
 
.PARAMETER SoftwareUpdateConfigurationRunContext 
  This is a system variable which is automatically passed in by Update Management during a deployment. 
#> 
 
param( 
    [string]$SoftwareUpdateConfigurationRunContext 
) 
#region BoilerplateAuthentication 
#This requires a RunAs account 
$ServicePrincipalConnection = Get-AutomationConnection -Name 'AzureRunAsConnection' 
 
Add-AzureRmAccount ` 
    -ServicePrincipal ` 
    -TenantId $ServicePrincipalConnection.TenantId ` 
    -ApplicationId $ServicePrincipalConnection.ApplicationId ` 
    -CertificateThumbprint $ServicePrincipalConnection.CertificateThumbprint 
 
$AzureContext = Select-AzureRmSubscription -SubscriptionId $ServicePrincipalConnection.SubscriptionID 
#endregion BoilerplateAuthentication 
 
#If you wish to use the run context, it must be converted from JSON 
$context = ConvertFrom-Json  $SoftwareUpdateConfigurationRunContext 
#Access the properties of the SoftwareUpdateConfigurationRunContext 
$vmIds = $context.SoftwareUpdateConfigurationSettings.AzureVirtualMachines | Sort-Object -Unique
$runId = $context.SoftwareUpdateConfigurationRunId 
 
Write-Output $context 
 
#Example: How to create and write to a variable using the pre-script: 
<# 
#Create variable named after this run so it can be retrieved 
New-AzureRmAutomationVariable -ResourceGroupName $ResourceGroup –AutomationAccountName $AutomationAccount –Name $runId -Value "" –Encrypted $false 
#Set value of variable  
Set-AutomationVariable –Name $runId -Value $vmIds 
#> 
 
#Example: How to retrieve information from a variable set during the pre-script 
<# 
$variable = Get-AutomationVariable -Name $runId 
#>      

マシンの操作Interacting with machines

事前タスクと事後タスクは、デプロイ内のマシンで直接実行されるのではなく、ご利用の Automation アカウント内で Runbook として実行されます。Pre and post tasks run as a runbook in your Automation Account and not directly on the machines in your deployment. また、事前および事後タスクは Azure コンテキストで実行されるため、Azure 以外のマシンにはアクセスできません。Pre and post tasks also run in the Azure context and don't have access to Non-Azure machines. 以降のセクションでは、Azure VM であるか Azure 以外のマシンであるかにかかわらず、それらのマシンと直接対話する方法について説明します。The following sections show how you can interact with the machines directly whether they are an Azure VM or a Non-Azure machine:

Azure マシンとの対話Interacting with Azure machines

事前タスクと事後タスクは、Runbook として実行されます。デプロイ内の Azure VM でネイティブに実行されるわけではありません。Pre and post tasks are ran as runbooks and do not natively run on your Azure VMs in your deployment. Azure VM と対話するには、次のものが必要です。To interact with your Azure VMs, you must have the following items:

  • 実行アカウントA Run As account
  • 実行する RunbookA runbook you want to run

Azure マシンと対話するには、Invoke-AzureRmVMRunCommand コマンドレットを使用して、目的の Azure VM と対話する必要があります。To interact with Azure machines, you should use the Invoke-AzureRmVMRunCommand cmdlet to interact with your Azure VMs. その方法を紹介した Runbook の例については、「Update Management - Run Script with Run Command (更新管理 - スクリプトを実行コマンドで実行する)」を参照してください。For an example of how to do this, see the runbook example Update Management - Run Script with Run Command.

Azure 以外のコンピューターとの対話Interacting with Non-Azure machines

事前および事後タスクは Azure コンテキストで実行されるため、Azure 以外のコンピューターにはアクセスできません。Pre and post tasks run in the Azure context and don't have access to Non-Azure machines. Azure 以外のコンピューターと対話するには、次のものが必要です。To interact with the Non-Azure machines, you must have the following items:

  • 実行アカウントA Run As account
  • コンピューターにインストールされた Hybrid Runbook WorkerHybrid Runbook Worker installed on the machine
  • ローカルで実行する RunbookA runbook you want to run locally
  • 親 RunbookParent runbook

Azure 以外のコンピューターと対話するために、親 Runbook が Azure コンテキストで実行されます。To interact with Non-Azure machines, a parent runbook is run in the Azure context. この Runbook は、Start-AzureRmAutomationRunbook コマンドレットを使用して子 Runbook を呼び出します。This runbook calls a child runbook with the Start-AzureRmAutomationRunbook cmdlet. -RunOn パラメーターを指定し、スクリプトを実行する Hybrid Runbook Worker の名前を指定する必要があります。You must specify the -RunOn parameter and provide the name of the Hybrid Runbook Worker for the script to run on. その方法を紹介した Runbook の例については、「Update Management - Run Script Locally (更新管理 - スクリプトをローカルで実行する)」を参照してください。For an example of how to do this, see the runbook example Update Management - Run Script Locally.

修正プログラムのデプロイを中止するAbort patch deployment

ご利用の事前スクリプトからエラーが返された場合、デプロイを中止したい場合があります。If your pre script returns an error, you may want to abort your deployment. それを行うには、障害を引き起こしているロジックに対してご利用のスクリプト内でエラーをスローする必要があります。To do this, you must throw an error in your script for any logic that would constitute a failure.

if (<My custom error logic>)
{
    #Throw an error to fail the patch deployment.  
    throw "There was an error, abort deployment"
}

既知の問題Known issues

  • 事前および事後スクリプトを使用している場合は、パラメーターにオブジェクトまたは配列を渡すことができません。You can't pass objects or arrays to parameters when using pre and post scripts. その Runbook が失敗します。The runbook will fail.

次の手順Next steps

使用している Windows 仮想マシンの更新プログラムの管理方法を学習するためのチュートリアルに進みます。Continue to the tutorial to learn how to manage updates for your Windows virtual machines.