Modulaire runbooks maken in Automation

  • Artikel

Het is een goede gewoonte in Azure Automation om herbruikbare, modulaire runbooks te schrijven met een discrete functie die door andere runbooks wordt aangeroepen. Een bovenliggend runbook roept vaak een of meer onderliggende runbooks aan om de vereiste functionaliteit uit te voeren.

Er zijn twee manieren om een onderliggend runbook aan te roepen: inline of via een cmdlet. De volgende tabel bevat een overzicht van de verschillen waarmee u kunt bepalen welke manier beter is voor uw scenario's.

Inline Cmdlet
Functie Onderliggende runbooks worden uitgevoerd in dezelfde taak als het bovenliggende item. Er wordt een afzonderlijke taak gemaakt voor het onderliggende runbook.
Uitvoering Het bovenliggende runbook wacht totdat het onderliggende runbook is voltooid voordat u doorgaat. Het bovenliggende runbook wordt direct voortgezet nadat het onderliggende runbook is gestart of het bovenliggende runbook wacht totdat de onderliggende taak is voltooid.
Uitvoer Het bovenliggende runbook kan rechtstreeks uitvoer ophalen van het onderliggende runbook. Het bovenliggende runbook moet uitvoer ophalen uit de onderliggende runbooktaak of het bovenliggende runbook kan rechtstreeks uitvoer ophalen van het onderliggende runbook.
Parameters Waarden voor de onderliggende runbookparameters worden afzonderlijk opgegeven en kunnen elk gegevenstype gebruiken. Waarden voor de onderliggende runbookparameters moeten worden gecombineerd tot één hashtabel. Deze hashtabel kan alleen eenvoudige, matrix- en objectgegevenstypen bevatten die gebruikmaken van JSON-serialisatie.
Automation-account Het bovenliggende runbook kan alleen een onderliggend runbook in hetzelfde Automation-account gebruiken. Bovenliggende runbooks kunnen een onderliggend runbook gebruiken vanuit elk Automation-account, van hetzelfde Azure-abonnement en zelfs van een ander abonnement waarvoor u verbinding hebt.
Publiceren Een onderliggend runbook moet worden gepubliceerd voordat het bovenliggende runbook wordt gepubliceerd. Een onderliggend runbook wordt op elk gewenst moment gepubliceerd voordat het bovenliggende runbook wordt gestart.

Een onderliggend runbook aanroepen met behulp van inline-uitvoering

Als u een runbook inline wilt aanroepen vanuit een ander runbook, gebruikt u de naam van het runbook en geeft u waarden op voor de parameters, net zoals u een activiteit of cmdlet zou gebruiken. Alle runbooks in hetzelfde Automation-account zijn beschikbaar voor alle andere runbooks die op deze manier kunnen worden gebruikt. Het bovenliggende runbook wacht totdat het onderliggende runbook is voltooid voordat het naar de volgende regel gaat en eventuele uitvoer rechtstreeks naar het bovenliggende runbook wordt geretourneerd.

Wanneer u een runbook inline aanroept, wordt het uitgevoerd in dezelfde taak als het bovenliggende runbook. Er is geen indicatie in de taakgeschiedenis van het onderliggende runbook. Eventuele uitzonderingen en stroomuitvoer van het onderliggende runbook zijn gekoppeld aan het bovenliggende runbook. Dit gedrag resulteert in minder taken en maakt het gemakkelijker om bij te houden en problemen op te lossen.

Wanneer een runbook wordt gepubliceerd, moeten alle onderliggende runbooks die worden aanroepen, al worden gepubliceerd. De reden hiervoor is dat Azure Automation een koppeling bouwt met onderliggende runbooks wanneer een runbook wordt gecompileerd. Als de onderliggende runbooks nog niet zijn gepubliceerd, lijkt het bovenliggende runbook correct te worden gepubliceerd, maar wordt er een uitzondering gegenereerd wanneer deze wordt gestart.

Als u een uitzondering krijgt, kunt u het bovenliggende runbook opnieuw publiceren om naar de onderliggende runbooks te verwijzen. U hoeft het bovenliggende runbook niet opnieuw te publiceren als er een onderliggend runbook wordt gewijzigd omdat de koppeling al is gemaakt.

De parameters van een onderliggend runbook dat inline wordt genoemd, kunnen van elk gegevenstype zijn, inclusief complexe objecten. Er is geen JSON-serialisatie, zoals wanneer u het runbook start met behulp van Azure Portal of met behulp van de cmdlet Start-AzAutomationRunbook .

Runbooktypen

Op dit moment wordt PowerShell 5.1 ondersteund en kunnen alleen bepaalde runbooktypen elkaar aanroepen:

  • Een PowerShell-runbook en een grafisch runbook kunnen elkaar inline aanroepen, omdat beide op PowerShell zijn gebaseerd.
  • Een PowerShell Workflow-runbook en een grafisch PowerShell Workflow-runbook kunnen elkaar inline aanroepen, omdat beide op PowerShell Workflow zijn gebaseerd.
  • De PowerShell-typen en de PowerShell-werkstroomtypen kunnen elkaar niet inline aanroepen. Ze moeten gebruiken Start-AzAutomationRunbook.

Belangrijk

Het uitvoeren van onderliggende scripts die worden gebruikt .\child-runbook.ps1 , wordt niet ondersteund in PowerShell 7.1 en PowerShell 7.2 Tijdelijke oplossing: Gebruik Start-AutomationRunbook (interne cmdlet) of Start-AzAutomationRunbook (vanuit de Az.Automation-module ) om een ander runbook te starten vanuit een bovenliggend runbook.

De publicatievolgorde van runbooks is alleen van belang voor PowerShell Workflow en grafische PowerShell Workflow-runbooks.

Wanneer uw runbook een grafisch of onderliggend PowerShell Workflow-runbook aanroept met behulp van inline-uitvoering, wordt de naam van het runbook gebruikt. De naam moet beginnen met .\\ het opgeven dat het script zich in de lokale map bevindt.

Opmerking

In het volgende voorbeeld wordt een onderliggend runbook gestart dat een complex object, een geheel getal en een Booleaanse waarde accepteert. De uitvoer van het onderliggende runbook wordt toegewezen aan een variabele. In dit geval is het onderliggende runbook een PowerShell Workflow-runbook.

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

Hier volgt hetzelfde voorbeeld, maar het gebruik van een PowerShell-runbook als het onderliggende.

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

Een onderliggend runbook starten met behulp van een cmdlet

Belangrijk

Als uw runbook een onderliggend runbook aanroept met behulp van de cmdlet met de Start-AzAutomationRunbookWait parameter en het onderliggende runbook een objectresultaat produceert, kan de bewerking een fout tegenkomen. Zie Onderliggende runbooks met objectuitvoer om de fout te omzeilen. In dit artikel leest u hoe u de logica implementeert om de resultaten te peilen met behulp van de cmdlet Get-AzAutomationJobOutputRecord .

U kunt Start-AzAutomationRunbook een runbook starten, zoals beschreven in Een runbook starten met Windows PowerShell. Er zijn twee gebruiksmodi voor deze cmdlet:

  • De cmdlet retourneert de taak-id wanneer de taak wordt gemaakt voor het onderliggende runbook.
  • De cmdlet wacht totdat de onderliggende taak is voltooid en retourneert de uitvoer van het onderliggende runbook. Uw script schakelt deze modus in door de Wait parameter op te geven.

De taak van een onderliggend runbook dat is gestart met een cmdlet, wordt afzonderlijk uitgevoerd van de bovenliggende runbooktaak. Dit gedrag resulteert in meer taken dan het starten van het runbook inline en maakt de taken moeilijker bij te houden. Het bovenliggende item kan meer dan één onderliggend runbook asynchroon starten zonder te wachten tot elk runbook is voltooid. Voor deze parallelle uitvoering die de onderliggende runbooks inline aanroept, moet het bovenliggende runbook het parallelle trefwoord gebruiken.

Uitvoer van onderliggend runbook keert niet betrouwbaar terug naar het bovenliggende runbook vanwege timing. $VerbosePreference$WarningPreferenceEn andere variabelen worden mogelijk niet doorgegeven aan de onderliggende runbooks. U kunt deze problemen voorkomen door de onderliggende runbooks als afzonderlijke Automation-taken te starten met behulp van Start-AzAutomationRunbook de Wait parameter. Met deze techniek wordt het bovenliggende runbook geblokkeerd totdat het onderliggende runbook is voltooid.

Als u niet wilt dat het bovenliggende runbook wordt geblokkeerd wanneer u wacht, kunt u het onderliggende runbook starten met behulp van Start-AzAutomationRunbook de Wait parameter. In dit geval moet uw runbook Get-AzAutomationJob gebruiken om te wachten op voltooiing van de taak. Het moet ook Get-AzAutomationJobOutput en Get-AzAutomationJobOutputRecord gebruiken om de resultaten op te halen.

Parameters voor een onderliggend runbook dat is gestart met een cmdlet, worden geleverd als een hashtabel, zoals beschreven in Runbook-parameters. U kunt alleen eenvoudige gegevenstypen gebruiken. Als het runbook een parameter met een complex gegevenstype heeft, moet het inline worden aangeroepen.

De abonnementscontext kan verloren gaan wanneer u onderliggende runbooks als afzonderlijke taken start. Het onderliggende runbook moet zich onafhankelijk van het bovenliggende runbook verifiëren bij dit abonnement om Az-module-cmdlets uit te voeren voor een specifiek Azure-abonnement.

Als taken binnen hetzelfde Automation-account met meer dan één abonnement werken, kan het selecteren van een abonnement in de ene taak de momenteel geselecteerde abonnementscontext voor andere taken wijzigen. Gebruik deze situatie aan het begin van elk runbook om deze situatie Disable-AzContextAutosave -Scope Process te voorkomen. Met deze actie wordt alleen de context opgeslagen in de uitvoering van dat runbook.

Opmerking

In het volgende voorbeeld wordt een onderliggend runbook gestart met parameters en wordt gewacht totdat het is voltooid met behulp van de Start-AzAutomationRunbook cmdlet met de Wait parameter. Nadat het onderliggende runbook is voltooid, verzamelt het voorbeeld cmdlet-uitvoer van het onderliggende runbook. Als u dit wilt gebruiken Start-AzAutomationRunbook, moet het script worden geverifieerd bij uw Azure-abonnement.

# 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

Als u wilt dat het runbook wordt uitgevoerd met de door het systeem toegewezen beheerde identiteit, laat u de code staan. Als u liever een door de gebruiker toegewezen beheerde identiteit gebruikt, gaat u als volgende te werk:

  1. Uit regel 5, verwijder $AzureContext = (Connect-AzAccount -Identity).context,
  2. Vervang het door $AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context, en
  3. Voer de client-id in.

Volgende stappen