Skapa modulära runbooks i Automation

Det är en bra idé Azure Automation att skriva återanvändbara, modulära runbooks med en diskret funktion som andra runbooks anropar. En överordnad runbook anropar ofta en eller flera underordnade runbooks för att utföra nödvändiga funktioner.

Det finns två sätt att anropa en underordnad runbook: infogade eller via en cmdlet. I följande tabell sammanfattas skillnaderna för att hjälpa dig att avgöra vilket sätt som är bäst för dina scenarier.

Anropa en underordnad runbook med hjälp av infogade körningar

Om du vill anropa en infogade runbook från en annan runbook använder du namnet på runbooken och anger värden för dess parametrar, precis som du använder en aktivitet eller en cmdlet. Alla runbooks i samma Automation-konto är tillgängliga för alla andra som kan användas på det här sättet. Den överordnade runbooken väntar på att den underordnade runbooken ska slutföras innan den flyttas till nästa rad, och alla utdata returneras direkt till den överordnade.

När du anropar en infogade runbook körs den i samma jobb som den överordnade runbooken. Det finns ingen indikation i jobbhistoriken för den underordnade runbooken. Eventuella undantag och eventuella strömutdata från den underordnade runbooken är associerade med den överordnade runbooken. Det här beteendet resulterar i färre jobb och gör dem enklare att spåra och felsöka.

När en runbook publiceras måste alla underordnade runbooks som anropas redan ha publicerats. Anledningen är att Azure Automation skapar en association med eventuella underordnade runbooks när den kompilerar en runbook. Om de underordnade runbooks inte redan har publicerats verkar den överordnade runbooken publicera korrekt, men genererar ett undantag när den startas.

Om du får ett undantag kan du publicera om den överordnade runbooken för att korrekt referera till underordnade runbooks. Du behöver inte publicera om den överordnade runbooken om någon underordnad runbook ändras eftersom associationen redan har skapats.

Parametrarna för en underordnad runbook med namnet infogade kan vara av valfri datatyp, inklusive komplexa objekt. Det finns ingen JSON-serialisering,eftersom det finns när du startar runbooken med hjälp av Azure Portal eller med hjälp av cmdleten Start-AzAutomationRunbook.

Runbook-typer

För närvarande stöds PowerShell 5.1 och 7.1 (förhandsversion) och endast vissa runbook-typer kan anropa varandra:

• En PowerShell-runbook och en grafisk runbook kan anropa varandra infogade, eftersom båda är PowerShell-baserade.
• En PowerShell Workflow-runbook och en grafisk PowerShell Workflow-runbook kan anropa varandra infogade, eftersom båda är PowerShell-arbetsflödesbaserade.
• PowerShell-typerna och PowerShell-arbetsflödestyperna kan inte anropa varandra infogade. De måste använda Start-AzAutomationRunbook .

Publiceringsordningen för runbooks är endast viktig för PowerShell Workflow och grafiska PowerShell Workflow-runbooks.

När din runbook anropar en grafisk runbook eller en underordnad PowerShell Workflow-runbook med hjälp av infogade körningar används namnet på runbooken. Namnet måste börja med .\\ för att ange att skriptet finns i den lokala katalogen.

Exempel

I följande exempel startas en underordnad test-runbook som accepterar ett komplext objekt, ett heltalsvärde och ett booleskt värde. Resultatet av den underordnade runbooken tilldelas till en variabel. I det här fallet är den underordnade runbooken en PowerShell Workflow-runbook.

$vm = Get-AzVM -ResourceGroupName "LabRG" -Name "MyVM"
$output = PSWF-ChildRunbook -VM $vm -RepeatCount 2 -Restart $true

Här är samma exempel men med en PowerShell-runbook som underordnad.

$vm = Get-AzVM -ResourceGroupName "LabRG" -Name "MyVM"
$output = .\PS-ChildRunbook.ps1 -VM $vm -RepeatCount 2 -Restart $true

Starta en underordnad runbook med hjälp av en cmdlet

Du kan använda Start-AzAutomationRunbook för att starta en runbook enligt beskrivningen i Starta en runbook med Windows PowerShell. Det finns två användningslägen för denna cmdlet:

• Cmdleten returnerar jobb-ID:t när jobbet skapas för den underordnade runbooken.
• Cmdleten väntar tills det underordnade jobbet har avslutats och returnerar utdata från den underordnade runbooken. Skriptet aktiverar det här läget genom att ange Wait parametern .

Jobbet från en underordnad runbook som startats med en cmdlet körs separat från det överordnade runbook-jobbet. Det här beteendet resulterar i fler jobb än att starta den infogade runbooken och gör jobben svårare att spåra. Den överordnade runbooken kan starta mer än en underordnad runbook asynkront utan att vänta på att varje ska slutföras. För den här parallella körningen som anropar underordnade runbooks måste den överordnade runbooken använda det parallella nyckelordet.

Underordnade runbook-utdata återgår inte till den överordnade runbooken på ett tillförlitligt sätt på grund av tidsinställningen. Dessutom kan $VerbosePreference det hända att , och andra variabler inte sprids till underordnade $WarningPreference runbooks. För att undvika dessa problem kan du starta underordnade runbooks som separata Automation-jobb med hjälp Start-AzAutomationRunbook av med Wait parametern . Den här tekniken blockerar den överordnade runbooken tills den underordnade runbooken har slutförts.

Om du inte vill att den överordnade runbooken ska blockeras i väntan kan du starta den underordnade runbooken med hjälp Start-AzAutomationRunbook av utan Wait parametern . I det här fallet måste runbooken använda Get-AzAutomationJob för att vänta tills jobbet har slutförts. Den måste också använda Get-AzAutomationJobOutput och Get-AzAutomationJobOutputRecord för att hämta resultaten.

Parametrar för en underordnad runbook som startas med en cmdlet tillhandahålls som en hash-tabell, enligt beskrivningen i Runbook-parametrar . Du kan bara använda enkla datatyper. Om runbooken har en parameter med en komplex datatyp måste den anropas infogade.

Prenumerationskontexten kan gå förlorad när du startar underordnade runbooks som separata jobb. För att den underordnade runbooken ska kunna köra Az-modul-cmdlets mot en specifik Azure-prenumeration måste den underordnade användaren autentisera till den här prenumerationen oberoende av den överordnade runbooken.

Om jobb inom samma Automation-konto fungerar med fler än en prenumeration kan du ändra den valda prenumerationskontexten för andra jobb om du väljer en prenumeration i ett jobb. Undvik den här situationen genom att Disable-AzContextAutosave -Scope Process använda i början av varje runbook. Den här åtgärden sparar bara kontexten till den runbook-körningen.

Exempel

I följande exempel startas en underordnad runbook med parametrar och väntar sedan på att den ska slutföras med hjälp av Start-AzAutomationRunbook cmdleten med Wait parametern . När den underordnade runbooken är klar samlar exemplet in cmdlet-utdata från den underordnade runbooken. Om du Start-AzAutomationRunbook vill använda måste skriptet autentisera till din Azure-prenumeration.

# Ensure that the runbook does not inherit an AzContext
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

$params = @{"VMName"="MyVM";"RepeatCount"=2;"Restart"=$true}

Start-AzAutomationRunbook `
    -AutomationAccountName 'MyAutomationAccount' `
    -Name 'Test-ChildRunbook' `
    -ResourceGroupName 'LabRG' `
    -DefaultProfile $AzureContext `
    -Parameters $params -Wait

Om du vill att runbooken ska köras med den system tilldelade hanterade identiteten lämnar du koden som den är. Om du föredrar att använda en användar tilldelad hanterad identitet gör du följande:

1. Ta bort från rad $AzureContext = (Connect-AzAccount -Identity).context 5,
2. Ersätt den med $AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context , och
3. Ange Klient-ID.

Nästa steg

• Information om hur du kör din runbook finns i Starta en runbook i Azure Automation.
• Information om hur du övervakar runbook-åtgärden finns i Runbook-utdata och meddelanden i Azure Automation.