Modulaire runbooks maken in Automation

Het is een goed idee om Azure Automation herbruikbare, modulaire runbooks te schrijven met een discrete functie die door andere runbooks wordt aanroepen. 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 om u te helpen bepalen welke manier beter is voor uw scenario's.

Inline Cmdlet
Taak Onderliggende runbooks worden uitgevoerd in dezelfde taak als het bovenliggende runbook. Er wordt een afzonderlijke taak gemaakt voor het onderliggende runbook.
Uitvoering Het bovenliggende runbook wacht tot het onderliggende runbook is uitgevoerd voordat het verdergaat. Het bovenliggende runbook wordt onmiddellijk voortgezet nadat het onderliggende runbook is gestart, of het bovenliggende runbook wacht tot de onderliggende taak is uitgevoerd.
Uitvoer Het bovenliggende runbook kan rechtstreeks uitvoer van het onderliggende runbook krijgen. Het bovenliggende runbook moet uitvoer ophalen van de onderliggende runbook-taak, anders kan het bovenliggende runbook rechtstreeks uitvoer van het onderliggende runbook ophalen.
Parameters Waarden voor de parameters van onderliggend runbook worden afzonderlijk opgegeven en kunnen elk gegevenstype hebben. Waarden voor de parameters van het onderliggende runbook 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 uit elk Automation-account, uit hetzelfde Azure-abonnement en zelfs vanuit een ander abonnement waarmee 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 een 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 tot het onderliggende runbook is uitgevoerd voordat het naar de volgende regel wordt verplaatst. Alle uitvoer wordt rechtstreeks naar het bovenliggende runbook teruggeplaatst.

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 taken bij te houden en problemen op te lossen.

Wanneer een runbook wordt gepubliceerd, moeten alle onderliggende runbooks die het aanroept, al zijn gepubliceerd. De reden hiervoor is dat Azure Automation een verband met onderliggende runbooks maakt wanneer een runbook wordt ge compileerd. Als de onderliggende runbooks nog niet zijn gepubliceerd, lijkt het bovenliggende runbook correct te publiceren, maar wordt er een uitzondering gegenereerd wanneer het 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 is gewijzigd omdat de associatie al is gemaakt.

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

Runbooktypen

Momenteel worden PowerShell 5.1 en 7.1 (preview) ondersteund en kunnen alleen bepaalde runbooktypen elkaar aanroepen:

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

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

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

Voorbeeld

In het volgende voorbeeld wordt een onderliggend testrunbook gestart dat een complex object, een geheel getal en een Booleaanse waarde accepteert. De uitvoer van het onderliggende runbook is 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 is hetzelfde voorbeeld, maar met een PowerShell-runbook als 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 parameter en het onderliggende runbook een objectresultaat produceert, kan er een fout worden Start-AzAutomationRunbook Wait aangetroffen in de bewerking. Zie Onderliggende runbooks met objectuitvoer om de fout te voorkomen. In dit artikel wordt beschreven hoe u de logica implementeert om de resultaten te peilen met behulp van de cmdlet Get-AzAutomationJobOutputRecord.

U kunt gebruiken Start-AzAutomationRunbook om een runbook te 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 uitgevoerd en retourneert de uitvoer van het onderliggende runbook. Uw script schakelt deze modus in door de parameter op te Wait geven.

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

De uitvoer van onderliggend runbook keert niet betrouwbaar terug naar het bovenliggende runbook vanwege timing. Bovendien worden $VerbosePreference , en andere variabelen mogelijk niet doorgegeven aan de $WarningPreference onderliggende runbooks. Om deze problemen te voorkomen, kunt u de onderliggende runbooks als afzonderlijke Automation-taken starten met behulp Start-AzAutomationRunbook van met de parameter Wait . Met deze techniek blokkeert u het bovenliggende runbook totdat het onderliggende runbook is voltooid.

Als u niet wilt dat het bovenliggende runbook wordt geblokkeerd bij het wachten, kunt u het onderliggende runbook starten met behulp Start-AzAutomationRunbook van zonder de parameter Wait . In dit geval moet uw runbook Get-AzAutomationJob gebruiken om te wachten tot de taak is voltooid. Ook moeten Get-AzAutomationJobOutput en Get-AzAutomationJobOutputRecord worden gebruikt om de resultaten op te halen.

Parameters voor een onderliggend runbook dat is gestart met een cmdlet worden opgegeven als een hashtabel, zoals beschreven in Runbookparameters. 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. Om ervoor te zorgen dat het onderliggende runbook Az-module-cmdlets uitvoert voor een specifiek Azure-abonnement, moet het onderliggende runbook onafhankelijk van het bovenliggende runbook worden geverifieerd bij dit abonnement.

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

Voorbeeld

In het volgende voorbeeld wordt een onderliggend runbook met parameters gestart en wordt gewacht tot het is uitgevoerd met behulp van de Start-AzAutomationRunbook cmdlet met de Wait parameter . Nadat het onderliggende runbook is uitgevoerd, verzamelt het voorbeeld cmdlet-uitvoer van het onderliggende runbook. Als u Start-AzAutomationRunbook wilt gebruiken, 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 zoals deze is. Als u liever een door de gebruiker toegewezen beheerde identiteit gebruikt, gaat u als volgende te werk:

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

Volgende stappen