Skapa modulära runbooks i Automation

  • Artikel

Det är en bra idé i 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: infogad eller via en cmdlet. I följande tabell sammanfattas skillnaderna som hjälper dig att avgöra vilket sätt som är bättre för dina scenarier.

Infogad Cmdlet
Jobb Underordnade runbooks körs i samma jobb som den överordnade. Ett separat jobb skapas för den underordnade runbooken.
Utförande Den överordnade runbooken väntar på att den underordnade runbooken ska slutföras innan den fortsätter. Den överordnade runbooken fortsätter omedelbart efter att den underordnade runbooken har startats, eller så väntar den överordnade runbooken på att det underordnade jobbet ska slutföras.
Output Den överordnade runbooken kan hämta utdata direkt från den underordnade runbooken. Den överordnade runbooken måste hämta utdata från det underordnade Runbook-jobbet, annars kan den överordnade runbooken hämta utdata direkt från den underordnade runbooken.
Parametrar Värden för de underordnade runbookparametrarna anges separat och kan använda valfri datatyp. Värden för de underordnade runbookparametrarna måste kombineras till en enda hashtable. Den här hashtabellen kan bara innehålla enkla datatyper, matriser och objekt som använder JSON-serialisering.
Automation-konto Den överordnade runbooken kan bara använda en underordnad runbook i samma Automation-konto. Överordnade runbooks kan använda en underordnad runbook från alla Automation-konton, från samma Azure-prenumeration och även från en annan prenumeration som du har en anslutning till.
Publicerar En underordnad runbook måste publiceras innan den överordnade runbooken publiceras. En underordnad runbook publiceras när som helst innan den överordnade runbooken startas.

Anropa en underordnad runbook med hjälp av infogad körning

Om du vill anropa en runbook infogad från en annan runbook använder du namnet på runbooken och anger värden för dess parametrar, precis som du skulle använda en aktivitet eller en cmdlet. Alla runbooks på 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 runbook infogad 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. 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 publiceras. Anledningen är att Azure Automation skapar en association med eventuella underordnade runbooks när den kompilerar en runbook. Om 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 referera till de underordnade runbooksna korrekt. 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 som kallas infogad kan vara av valfri datatyp, inklusive komplexa objekt. Det finns ingen JSON-serialisering, som när du startar runbooken med hjälp av Azure-portalen eller med hjälp av cmdleten Start-AzAutomationRunbook .

Runbook-typer

För närvarande stöds PowerShell 5.1 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-arbetsflödesrunbook 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.

Viktigt!

Körning av underordnade skript som använder .\child-runbook.ps1 stöds inte i PowerShell 7.1 och PowerShell 7.2 Lösning: Använd Start-AutomationRunbook (intern cmdlet) eller Start-AzAutomationRunbook (från Az.Automation-modulen ) för att starta en annan runbook från den överordnade runbooken.

Publiceringsordningen för runbooks är endast viktig för PowerShell-arbetsflöden och grafiska PowerShell-arbetsflödesrunbooks.

När din runbook anropar en underordnad runbook för grafiskt arbetsflöde eller PowerShell-arbetsflöde med hjälp av infogad körning använder den 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. Utdata från 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 använder 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

Viktigt!

Om din runbook anropar en underordnad runbook med hjälp av cmdleten Start-AzAutomationRunbook med parametern Wait och den underordnade runbooken genererar ett objektresultat, kan åtgärden stöta på ett fel. Information om hur du kringgår felet finns i Underordnade runbooks med objektutdata. Den här artikeln visar hur du implementerar logiken för att söka efter resultaten med hjälp av cmdleten Get-AzAutomationJobOutputRecord .

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 den här cmdleten:

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

Jobbet från en underordnad runbook startades med en cmdlet som körs separat från det överordnade runbook-jobbet. Det här beteendet resulterar i fler jobb än att starta runbook-inline och gör jobben svårare att spåra. Den överordnade kan starta mer än en underordnad runbook asynkront utan att vänta på att var och en ska slutföras. För den här parallella körningen som anropar underordnade runbooks infogade 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. $VerbosePreferenceDessutom kan det hända att , $WarningPreferenceoch andra variabler inte sprids till de underordnade runbooksna. För att undvika dessa problem kan du starta underordnade runbooks som separata Automation-jobb med hjälp Start-AzAutomationRunbook av parametern Wait . Den här tekniken blockerar den överordnade runbooken tills den underordnade runbooken är klar.

Om du inte vill att den överordnade runbooken ska blockeras vid väntan kan du starta den underordnade runbooken med hjälp Start-AzAutomationRunbook av utan parametern Wait . I det här fallet måste din runbook 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 resultatet.

Parametrar för en underordnad runbook som startats med en cmdlet tillhandahålls som en hashtable, 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 infogad.

Prenumerationskontexten kan gå förlorad när du startar underordnade runbooks som separata jobb. För att den underordnade runbooken ska köra Az-modul-cmdletar mot en specifik Azure-prenumeration måste det underordnade 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 genom att välja en prenumeration i ett jobb. Undvik den här situationen genom att använda Disable-AzContextAutosave -Scope Process i början av varje runbook. Den här åtgärden sparar bara kontexten till 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 cmdleten Start-AzAutomationRunbook med parametern Wait . När den underordnade runbooken är klar samlar exemplet in cmdlet-utdata från den underordnade runbooken. Om du vill använda Start-AzAutomationRunbookmå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 systemtilldelade hanterade identiteten lämnar du koden som den är. Om du föredrar att använda en användartilldelad hanterad identitet:

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

Nästa steg