Underordnade runbooks i Azure AutomationChild runbooks in Azure Automation

Det är en rekommendation i Azure Automation för att skriva återanvändningsbara, modulbaserade runbooks med en diskret funktion som är av andra runbooks.It is a recommended practice in Azure Automation to write reusable, modular runbooks with a discrete function that is by other runbooks. En överordnad runbook anropar ofta en eller flera underordnade runbooks för att utföra nödvändiga funktioner.A parent runbook often calls one or more child runbooks to perform required functionality. Det finns två sätt att anropa en underordnad runbook och var och en har tydliga skillnader som du bör känna till så att du kan fastställa som passar bäst för dina olika scenarier.There are two ways to call a child runbook, and each has distinct differences that you should understand so that you can determine which is best for your different scenarios.

Anropa en underordnad runbook med infogad körningInvoking a child runbook using inline execution

Om du vill aktivera en infogad runbook från en annan runbook, Använd namnet på runbooken och ange värden för parametrarna exakt samma sätt som du använder en aktivitet eller cmdlet.To invoke a runbook inline from another runbook, you use the name of the runbook and provide values for its parameters exactly like you would use an activity or cmdlet. Alla runbooks i samma Automation-kontot är tillgängliga för alla andra som ska användas i det här sättet.All runbooks in the same Automation account are available to all others to be used in this manner. Den överordnade runbooken väntar på att den underordnade runbooken ska slutföras innan du går till nästa rad och eventuella utdata returneras direkt till överordnat.The parent runbook will wait for the child runbook to complete before moving to the next line, and any output is returned directly to the parent.

När du anropar en infogad runbook körs i samma jobb som den överordnade runbooken.When you invoke a runbook inline, it runs in the same job as the parent runbook. Det finns ingen indikation i jobbhistoriken på underordnad runbook som kördes.There is no indication in the job history of the child runbook that it ran. Eventuella undantag och strömmad utdata från den underordnade runbooken är associerad med överordnat.Any exceptions and any stream output from the child runbook is associated with the parent. Detta innebär färre jobb och gör det enklare att spåra och felsöka eftersom alla undantag från den underordnade runbooken och någon av dess stream-utdata är associerade med det överordnade jobbet.This behavior results in fewer jobs and makes them easier to track and to troubleshoot since any exceptions thrown by the child runbook and any of its stream outputs are associated with the parent job.

När en runbook publiceras måste alla underordnade runbooks som anropas redan publiceras.When a runbook is published, any child runbooks that it calls must already be published. Det beror på att Azure Automation bygger en association med någon av underordnade runbooks när en runbook kompileras.This is because Azure Automation builds an association with any child runbooks when a runbook is compiled. Om de inte är den överordnade runbooken publicerar korrekt visas, men genererar ett undantag när den startas.If they aren’t, the parent runbook appears to publish properly, but will generate an exception when it’s started. Om det händer kan du publicera om den överordnade runbooken för att korrekt referens till underordnade runbooks.If this happens, you can republish the parent runbook to properly reference the child runbooks. Du behöver inte att publicera den överordnade runbooken om någon av underordnade runbooks ändras eftersom associationen redan har skapats.You do not need to republish the parent runbook if any of the child runbooks are changed because the association has already been created.

Parametrarna för en underordnad runbook som anropas internt kan vara en datatyp som inkluderar komplexa objekt.The parameters of a child runbook called inline can be any data type including complex objects. Det finns inga JSON-serialisering eftersom det inte finns när du startar en runbook med Azure portal eller med cmdleten Start-AzureRmAutomationRunbook.There is no JSON serialization as there is when you start the runbook using the Azure portal or with the Start-AzureRmAutomationRunbook cmdlet.

Runbook-typerRunbook types

Vilka typer kan anropa varandra:Which types can call each other:

  • En PowerShell-runbook och grafiska runbooks kan anropa varje andra infogad (båda är PowerShell-baserat).A PowerShell runbook and Graphical runbooks can call each other inline (both are PowerShell based).
  • En PowerShell Workflow-runbook och grafiska PowerShell Workflow-runbooks kan anropa varje andra infogad (båda är PowerShell-arbetsflöde baserat)A PowerShell Workflow runbook and Graphical PowerShell Workflow runbooks can call each other inline (both are PowerShell Workflow based)
  • PowerShell-typer och PowerShell Workflow-typer kan inte anropa varandra infogade och måste använda Start-AzureRmAutomationRunbook.The PowerShell types and the PowerShell Workflow types can’t call each other inline, and must use Start-AzureRmAutomationRunbook.

När du publicera ordning bara:When does publish order matter:

  • Publicera ordningen för runbooks är bara viktig för PowerShell-arbetsflödet och grafiska PowerShell Workflow-runbooks.The publish order of runbooks only matters for PowerShell Workflow and Graphical PowerShell Workflow runbooks.

När du anropar en grafisk eller PowerShell-arbetsflöde underordnad runbook med infogad körning, kan du använda namnet på runbooken.When you call a Graphical or PowerShell Workflow child runbook using inline execution, you use the name of the runbook. När du anropar en underordnad runbook som PowerShell, måste du starta dess namn med .\ att ange att skriptet finns i den lokala katalogen.When you call a PowerShell child runbook, you must start its name with .\ to specify that the script is located in the local directory.

ExempelExample

I följande exempel startar ett test en underordnad runbook som accepterar tre parametrar, ett komplext objekt, ett heltal och ett booleskt värde.The following example starts a test child runbook that accepts three parameters, a complex object, an integer, and a boolean. Utdata från den underordnade runbooken tilldelas till en variabel.The output of the child runbook is assigned to a variable. I det här fallet är den underordnade runbooken PowerShell Workflow-runbook.In this case, the child runbook is a PowerShell Workflow runbook.

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

Nedan följer samma exempel med hjälp av en PowerShell-runbook som barnet.Following is the same example using a PowerShell runbook as the child.

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

Starta en underordnad runbook med hjälp av cmdlet:Starting a child runbook using cmdlet

Viktigt

Om du anropar en underordnad runbook med den Start-AzureRmAutomationRunbook cmdlet med den -Wait växeln och resultatet av den underordnade runbooken är ett objekt, kan det uppstå fel.If you are invoking a child runbook with the Start-AzureRmAutomationRunbook cmdlet with the -Wait switch and the results of the child runbook is an object, you may encounter errors. Om du vill kringgå felet, se underordnade runbooks med objektutdata information om hur du implementerar logik för att söka efter resultaten och använda den Get-AzureRmAutomationJobOutputRecordTo work around the error, see Child runbooks with object output to learn how to implement the logic to poll for the results and use the Get-AzureRmAutomationJobOutputRecord

Du kan använda den Start-AzureRmAutomationRunbook cmdlet för att starta en runbook enligt beskrivningen i att starta en runbook med Windows PowerShell.You can use the Start-AzureRmAutomationRunbook cmdlet to start a runbook as described in To start a runbook with Windows PowerShell. Det finns två lägen för denna cmdlet.There are two modes of use for this cmdlet. I ett läge returnerar cmdlet: en jobb-id när underordnat jobb skapas för den underordnade runbooken.In one mode, the cmdlet returns the job id when the child job is created for the child runbook. I det andra läget som du gör det genom att ange den -vänta parametern cmdleten väntar tills det underordnade jobbet har slutförts och returnerar resultatet från den underordnade runbooken.In the other mode, which you enable by specifying the -wait parameter, the cmdlet waits until the child job finishes and returns the output from the child runbook.

Jobbet från en underordnad runbook som startas med en cmdlet körs i ett separat jobb från den överordnade runbooken.The job from a child runbook started with a cmdlet runs in a separate job from the parent runbook. Detta innebär fler jobb än att starta infogad runbook och gör dem svårare att spåra. Överordnat kan starta mer än en underordnad runbook asynkront utan att behöva vänta på att alla ska slutföras.This behavior results in more jobs than starting the runbook inline and makes them more difficult to track. The parent can start more than one child runbook asynchronously without waiting for each to complete. För att få samma typ av parallell körning vid anrop av infogade underordnade runbooks, skulle den överordnade runbooken måste du använda den parallellt nyckelord.For that same kind of parallel execution calling the child runbooks inline, the parent runbook would need to use the parallel keyword.

Resultatet av underordnade runbooks inte tillbaka till den överordnade runbooken på ett tillförlitligt sätt på grund av tiden.The output of child runbooks aren't returned to the parent runbook reliably because of timing. Även vissa variabler som $VerbosePreference, $WarningPreference, och andra inte att överföra till underordnade runbooks.Also certain variables like $VerbosePreference, $WarningPreference, and others may not be propagated to the child runbooks. För att undvika dessa problem kan du starta underordnade runbooks som separata Automation-jobb med hjälp av den Start-AzureRmAutomationRunbook cmdlet med den -Wait växla.To avoid these issues, you can start the child runbooks as separate Automation jobs using the Start-AzureRmAutomationRunbook cmdlet with the -Wait switch. Detta hindrar den överordnade runbooken tills den underordnade runbooken har slutförts.This blocks the parent runbook until the child runbook is complete.

Om du inte vill den överordnade runbooken blockeras på väntar du startar en underordnad runbook med hjälp av Start-AzureRmAutomationRunbook cmdlet utan att den -Wait växla.If you don’t want the parent runbook to be blocked on waiting, you can start the child runbook using Start-AzureRmAutomationRunbook cmdlet without the -Wait switch. Sedan måste du använda Get-AzureRmAutomationJob vänta tills jobbet är slutfört, och Get-AzureRmAutomationJobOutput och Get-AzureRmAutomationJobOutputRecord att hämta resultaten.You would then need to use Get-AzureRmAutomationJob to wait for job completion, and Get-AzureRmAutomationJobOutput and Get-AzureRmAutomationJobOutputRecord to retrieve the results.

Parametrar för en underordnad runbook som startas med en cmdlet tillhandahålls som en hash-tabell enligt beskrivningen i Runbookparametrar.Parameters for a child runbook started with a cmdlet are provided as a hashtable as described in Runbook Parameters. Endast enkla datatyper kan användas.Only simple data types can be used. Om runbooken har en parameter med en komplex datatyp, det måste den anropas infogad.If the runbook has a parameter with a complex data type, then it must be called inline.

Prenumerationskontexten kan gå förlorade när du startar underordnade runbooks som separat jobb.The subscription context might be lost when starting child runbooks as separate jobs. För den underordnade runbooken ska köra Azure RM-cmdlet: ar mot en specifik Azure-prenumeration, måste den underordnade runbooken autentisera till den här prenumerationen oberoende av den överordnade runbooken.In order for the child runbook to execute Azure RM cmdlets against a specific Azure subscription, the child runbook must authenticate to this subscription independently of the parent runbook.

Om jobb i samma Automation-kontot fungerar med mer än en prenumeration, kan om du väljer en prenumeration för ett jobb ändras den markerade prenumerationskontexten för andra jobb.If jobs within the same Automation account work with more than one subscription, selecting a subscription in one job may change the currently selected subscription context for other jobs. Du kan undvika det här problemet genom att använda Disable-AzureRmContextAutosave –Scope Processsave i början av varje runbook.To avoid this problem, use Disable-AzureRmContextAutosave –Scope Processsave at the beginning of each runbook. Den här åtgärden sparar endast kontexten till den runbook-körningen.This action only saves the context to that runbook execution.

ExempelExample

I följande exempel startar en underordnad runbook med parametrar och väntar sedan tills den är klar med Start-AzureRmAutomationRunbook-vänta parametern.The following example starts a child runbook with parameters and then waits for it to complete using the Start-AzureRmAutomationRunbook -wait parameter. När slutförd samlas utdata från den underordnade runbooken.Once completed, its output is collected from the child runbook. Att använda Start-AzureRmAutomationRunbook, du måste autentisera till Azure-prenumerationen.To use Start-AzureRmAutomationRunbook, you must authenticate to your Azure subscription.

# Ensures you do not inherit an AzureRMContext in your runbook
Disable-AzureRmContextAutosave –Scope Process

# Connect to Azure with RunAs account
$ServicePrincipalConnection = Get-AutomationConnection -Name 'AzureRunAsConnection'

Add-AzureRmAccount `
    -ServicePrincipal `
    -TenantId $ServicePrincipalConnection.TenantId `
    -ApplicationId $ServicePrincipalConnection.ApplicationId `
    -CertificateThumbprint $ServicePrincipalConnection.CertificateThumbprint

$AzureContext = Select-AzureRmSubscription -SubscriptionId $ServicePrincipalConnection.SubscriptionID

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

Start-AzureRmAutomationRunbook `
    –AutomationAccountName 'MyAutomationAccount' `
    –Name 'Test-ChildRunbook' `
    -ResourceGroupName 'LabRG' `
    -AzureRMContext $AzureContext `
    –Parameters $params –wait

Jämförelse av metoder för att anropa en underordnad runbookComparison of methods for calling a child runbook

I följande tabell sammanfattas skillnaderna mellan de två metoderna för att anropa en runbook från en annan runbook.The following table summarizes the differences between the two methods for calling a runbook from another runbook.

InfogadInline Cmdlet:Cmdlet
JobbetJob Underordnade runbooks körs i samma jobb som det överordnade objektet.Child runbooks run in the same job as the parent. Ett separat jobb skapas för den underordnade runbooken.A separate job is created for the child runbook.
KörningExecution Överordnad runbook väntar tills den underordnade runbooken ska slutföras innan du fortsätter.Parent runbook waits for the child runbook to complete before continuing. Överordnad runbook fortsätter omedelbart efter att underordnad runbook har startats eller överordnad runbook väntar underordnade jobbet är slutfört.Parent runbook continues immediately after child runbook is started or parent runbook waits for the child job to finish.
OutputOutput Överordnad runbook kan hämta utdata direkt från underordnad runbook.Parent runbook can directly get output from child runbook. Överordnad runbook måste hämta utdata från underordnat runbook-jobb eller överordnad runbook kan hämta utdata direkt från underordnad runbook.Parent runbook must retrieve output from child runbook job or parent runbook can directly get output from child runbook.
ParametrarParameters Värden för parametrar i underordnad runbook anges separat och kan använda alla datatyper.Values for the child runbook parameters are specified separately and can use any data type. Värden för underordnade runbook-parametrar måste kombineras i en enda hash-tabell.Values for the child runbook parameters have to be combined into a single hashtable. Den här hash-tabell kan endast innehålla enkla, matris och objekt-datatyper som använder JSON-serialisering.This hashtable can only include simple, array, and object data types that use JSON serialization.
Automation-kontoAutomation Account Överordnad runbook kan bara använda underordnad runbook på samma automation-konto.Parent runbook can only use child runbook in the same automation account. Överordnade runbooks kan använda en underordnad runbook från alla automation-konto från samma Azure-prenumeration och även en annan prenumeration som du har en anslutning till.Parent runbooks can use a child runbook from any automation account from the same Azure subscription and even a different subscription that you have a connection to.
PubliceringPublishing Underordnad runbook måste publiceras innan överordnad runbook publiceras.Child runbook must be published before parent runbook is published. Underordnad runbook måste publiceras när som helst innan överordnad runbook startas.Child runbook must be published anytime before parent runbook is started.

Nästa stegNext steps