Hantera förskript och efterskript

Artikel
10/24/2023

Förskript och efterskript är runbooks som körs på ditt Azure Automation-konto före (före uppgift) och efter (efter uppgift) en uppdateringsdistribution. Förskript och efterskript körs i Azure-kontexten, inte lokalt. Förskript körs i början av uppdateringsdistributionen. I Windows körs efterskripten i slutet av distributionen och efter alla omstarter som har konfigurerats. I Linux körs efterskripten efter distributionens slut, inte efter att datorn har startats om.

Krav för förskript och efterskript

För att en runbook ska användas som ett förskript eller efterskript måste du importera den till ditt Automation-konto och publicera runbooken.

För närvarande stöds endast PowerShell 5.1- och Python 2-runbooks som Pre/Post-skript. Andra runbook-typer som Python 3, Grafiskt, PowerShell-arbetsflöde och grafiskt PowerShell-arbetsflöde stöds för närvarande inte som För-/Post-skript.

Parametrar för förskript och efterskript

När du konfigurerar förskript och efterskript kan du skicka in parametrar precis som när du schemalägger en runbook. Parametrar definieras när uppdateringsdistributionen skapas. Förskript och efterskript stöder följande typer:

[tecken]
[byte]
[int]
[lång]
[decimal]
[enkel]
[dubbel]
[DateTime]
[sträng]

Runbookparametrar före skript och efter skript stöder inte booleska, objekt- eller matristyper. Dessa värden gör att runbooks misslyckas.

Om du behöver en annan objekttyp kan du omvandla den till en annan typ med din egen logik i runbooken.

Utöver dina standard runbook-parametrar tillhandahålls parametern SoftwareUpdateConfigurationRunContext (typ JSON-sträng). Om du definierar parametern i din runbook för skript eller efter skript skickas den automatiskt in av uppdateringsdistributionen. Parametern innehåller information om uppdateringsdistributionen, som är en delmängd av information som returneras av API:et SoftwareUpdateconfigurations. Avsnitten nedan definierar de associerade egenskaperna.

SoftwareUpdateConfigurationRunContext-egenskaper

Egenskap	Type	Description
SoftwareUpdateConfigurationName	String	Namnet på programuppdateringskonfigurationen.
SoftwareUpdateConfigurationRunId	GUID	Det unika ID:t för körningen.
SoftwareUpdateConfiguration Inställningar		En samling egenskaper som är relaterade till programuppdateringskonfigurationen.
SoftwareUpdateConfiguration Inställningar. OperatingSystem	Int	De operativsystem som är avsedda för uppdateringsdistributionen. `1` = Windows och `2` = Linux
SoftwareUpdateConfiguration Inställningar. Varaktighet	Tidsintervall (HH:MM:SS)	Den maximala varaktigheten för uppdateringsdistributionen körs `PT[n]H[n]M[n]S` enligt ISO8601, även kallat underhållsfönstret. Exempel: 02:00:00
SoftwareUpdateConfiguration Inställningar. WindowsConfiguration		En samling egenskaper som är relaterade till Windows-datorer.
SoftwareUpdateConfiguration Inställningar. WindowsConfiguration.excludedKbNumbers	String	En blankstegsavgränsad lista över KB:er som undantas från uppdateringsdistributionen.
SoftwareUpdateConfiguration Inställningar. WindowsConfiguration.includedKbNumbers	String	En blankstegsavgränsad lista över KB:er som ingår i uppdateringsdistributionen.
SoftwareUpdateConfiguration Inställningar. WindowsConfiguration.UpdateCategories	Integer	1 = "Kritisk"; 2 = "Säkerhet" 4 = "UpdateRollUp" 8 = "FeaturePack" 16 = "ServicePack" 32 = "Definition" 64 = "Verktyg" 128 = "Uppdateringar"
SoftwareUpdateConfiguration Inställningar. WindowsConfiguration.rebootSetting	String	Omstartsinställningar för uppdateringsdistributionen. Värdena är `IfRequired`, `Never`, `Always`
SoftwareUpdateConfiguration Inställningar. LinuxConfiguration		En samling egenskaper som är relaterade till Linux-datorer.
SoftwareUpdateConfiguration Inställningar. LinuxConfiguration.IncludedPackageClassifications	Integer	0 = "Oklassificerad" 1 = "Kritisk" 2 = "Säkerhet" 4 = "Övrigt"
SoftwareUpdateConfiguration Inställningar. LinuxConfiguration.IncludedPackageNameMasks	String	En blankstegsavgränsad lista med paketnamn som ingår i uppdateringsdistributionen.
SoftwareUpdateConfiguration Inställningar. LinuxConfiguration.ExcludedPackageNameMasks	String	En blankstegsavgränsad lista med paketnamn som undantas från uppdateringsdistributionen.
SoftwareUpdateConfiguration Inställningar. LinuxConfiguration.RebootSetting	String	Omstartsinställningar för uppdateringsdistributionen. Värdena är `IfRequired`, `Never`, `Always`
SoftwareUpdateConfiguation Inställningar. AzureVirtualMachines	Strängmatris	En lista över resourceIds för de virtuella Azure-datorerna i uppdateringsdistributionen.
SoftwareUpdateConfiguration Inställningar. NonAzureComputerNames	Strängmatris	En lista över FQDN för icke-Azure-datorer i uppdateringsdistributionen.

Följande exempel är en JSON-sträng som skickas till egenskaperna SoftwareUpdateConfiguration Inställningar för en Linux-dator:

"SoftwareUpdateConfigurationSettings": {
     "OperatingSystem": 2,
     "WindowsConfiguration": null,
     "LinuxConfiguration": {
         "IncludedPackageClassifications": 7,
         "ExcludedPackageNameMasks": "fgh xyz",
         "IncludedPackageNameMasks": "abc bin*",
         "RebootSetting": "IfRequired"
     },
     "Targets": {
         "azureQueries": null,
         "nonAzureQueries": ""
     },
     "NonAzureComputerNames": [
        "box1.contoso.com",
        "box2.contoso.com"
     ],
     "AzureVirtualMachines": [
        "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/resourceGroupName/providers/Microsoft.Compute/virtualMachines/vm-01"
     ],
     "Duration": "02:00:00",
     "PSComputerName": "localhost",
     "PSShowComputerName": true,
     "PSSourceJobInstanceId": "2477a37b-5262-4f4f-b636-3a70152901e9"
 }

Följande exempel är en JSON-sträng som skickas till egenskaperna SoftwareUpdateConfiguration Inställningar för en Windows-dator:

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

Ett fullständigt exempel med alla egenskaper finns på: Hämta programuppdateringskonfiguration efter namn.

Kommentar

Objektet SoftwareUpdateConfigurationRunContext kan innehålla dubbletter av poster för datorer. Detta kan göra att förskript och efterskript körs flera gånger på samma dator. Om du vill kringgå det här beteendet använder du Sort-Object -Unique för att bara välja unika namn på virtuella datorer.

Använda ett förskript eller efterskript i en distribution

Om du vill använda ett förskript eller efterskript i en uppdateringsdistribution börjar du med att skapa en uppdateringsdistribution. Välj Förskript + Post-Scripts. Den här åtgärden öppnar sidan Välj förskript + Efterskript .

Select scripts

Välj det skript som du vill använda. I det här exemplet använder vi Runbooken UpdateManagement-TurnOnVms . När du väljer runbook öppnas sidan Konfigurera skript . Välj Förskript och välj sedan OK.

Upprepa den här processen för skriptet UpdateManagement-TurnOffVms . Men när du väljer Typ av skript väljer du Post-Script.

Avsnittet Markerade objekt visar nu båda dina skript valda. Det ena är ett förskript och det andra är ett efterskript:

Selected items

Slutför konfigurationen av uppdateringsdistributionen.

När uppdateringsdistributionen är klar kan du gå till Uppdatera distributioner för att visa resultatet. Som du ser anges statusen för förskriptet och efterskriptet:

Update results

Genom att välja uppdateringsdistributionskörningen visas ytterligare information om förskript och efterskript. En länk till skriptkällan vid tidpunkten för körningen tillhandahålls.

Deployment run results

Stoppa en distribution

Om du vill stoppa en distribution baserat på ett förskript måste du utlösa ett undantag. Om du inte gör det fortsätter distributionen och efterskriptet att köras. Följande kodfragment visar hur du utlöser ett undantag med hjälp av PowerShell.

#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
    }
}

I Python 2 hanteras undantagshantering i ett försöksblock .

Interagera med datorer

Förskript och efterskript körs som runbooks på ditt Automation-konto och inte direkt på datorerna i distributionen. Föruppgifter och efteruppgifter körs också i Azure-kontexten och de har inte åtkomst till datorer som inte är Azure-datorer. I följande avsnitt visas hur du kan interagera direkt med datorerna, oavsett om de är virtuella Azure-datorer eller datorer som inte är Azure-datorer.

Interagera med Azure-datorer

Föruppgifter och efteraktiviteter körs som runbooks och körs inte internt på dina virtuella Azure-datorer i distributionen. Om du vill interagera med dina virtuella Azure-datorer måste du ha följande:

En hanterad identitet eller ett Kör som-konto
En runbook som du vill köra

Om du vill interagera med Azure-datorer bör du använda cmdleten Invoke-AzVMRunCommand för att interagera med dina virtuella Azure-datorer. Ett exempel på hur du gör detta finns i runbook-exemplet Uppdateringshantering – kör skript med kommandot Kör.

Interagera med datorer som inte är Azure-datorer

Föruppgifter och efteraktiviteter körs i Azure-kontexten och har inte åtkomst till datorer som inte är Azure-datorer. Om du vill interagera med datorer som inte kommer från Azure måste du ha följande:

En hanterad identitet eller ett Kör som-konto
Hybrid Runbook Worker installerat på datorn
En runbook som du vill köra lokalt
En överordnad runbook

För att kunna interagera med datorer som inte är Azure-datorer körs en överordnad runbook i Azure-kontexten. Runbooken anropar en underordnad runbook med cmdleten Start-AzAutomationRunbook. Du måste ange parametern RunOn och ange namnet på Hybrid Runbook Worker som skriptet ska köras på. Se runbook-exemplet Uppdateringshantering – kör skript lokalt.

Avbryt korrigeringsdistribution

Om förskriptet returnerar ett fel kanske du vill avbryta distributionen. För att göra det måste du utlösa ett fel i skriptet för all logik som skulle utgöra ett fel.

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

Om du vill utlösa ett fel när ett visst villkor inträffar i Python 2 använder du en raise-instruktion .

If (<My custom error logic>)
   raise Exception('Something happened.')

Exempel

Exempel för förskript och efterskript finns i Azure Automation GitHub-organisationen och PowerShell-galleriet, eller så kan du importera dem via Azure-portalen. Om du vill göra det går du till Automation-kontot och väljer Runbooks Gallery under Process Automation. Använd Uppdateringshantering för filtret.

Gallery list

Eller så kan du söka efter dem efter deras skriptnamn, som du ser i följande lista:

Uppdateringshantering – Aktivera virtuella datorer
Uppdateringshantering – Inaktivera virtuella datorer
Uppdateringshantering – Kör skript lokalt
Uppdateringshantering – mall för för-/efterskript
Uppdateringshantering – Kör skript med körkommando

Viktigt!

När du har importerat runbooks måste du publicera dem innan de kan användas. Det gör du genom att leta upp runbooken i ditt Automation-konto, välja Redigera och sedan publicera.

Exemplen baseras alla på den grundläggande mall som definieras i följande exempel. Den här mallen kan användas för att skapa en egen runbook som ska användas med förskript och efterskript. Den nödvändiga logiken för att autentisera med Azure och hantera parametern SoftwareUpdateConfigurationRunContext ingår.

<#
.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 the Automation account's system-assigned managed identity.

.PARAMETER SoftwareUpdateConfigurationRunContext
  This is a system variable which is automatically passed in by Update Management during a deployment.
#>

param(
    [string]$SoftwareUpdateConfigurationRunContext
)

#region BoilerplateAuthentication
# Ensures you do not inherit an AzContext in your runbook
Disable-AzContextAutosave -Scope Process

# Connect to Azure with system-assigned managed identity
$AzureContext = (Connect-AzAccount -Identity).context

# set and store context
$AzureContext = Set-AzContext -SubscriptionName $AzureContext.Subscription -DefaultProfile $AzureContext
#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-AzAutomationVariable -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
#>

Om du vill att runbooken ska köras med den systemtilldelade hanterade identiteten lämnar du koden som den är. Om du föredrar att använda en användartilldelad hanterad identitet:

Från rad 22 tar du bort $AzureContext = (Connect-AzAccount -Identity).context,
Ersätt den med $AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context, och
Ange klient-ID:t.