在 Azure 自动化中启动 RunbookStart a runbook in Azure Automation

下表将帮助你确定如何在 Azure 自动化中以最适合你方案的方法启动 Runbook。The following table helps you determine the method to start a runbook in Azure Automation that is most suitable to your particular scenario. 本文包含有关使用 Azure 门户和 Windows PowerShell 启动 Runbook 的详细信息。This article includes details on starting a runbook with the Azure portal and with Windows PowerShell. 有关其他方法的详细信息会在其他文档中提供,可以通过以下链接来访问。Details on the other methods are provided in other documentation that you can access from the links below.

方法Method 特征Characteristics
Azure 门户Azure portal
  • 使用交互式用户界面的最简单方法。Simplest method with interactive user interface.
  • 用于提供简单参数值的窗体。Form to provide simple parameter values.
  • 轻松跟踪作业状态。Easily track job state.
  • 使用 Azure 登录对访问进行身份验证。Access authenticated with Azure sign in.
  • Windows PowerShellWindows PowerShell
  • 使用 Windows PowerShell cmdlet 从命令行调用。Call from command line with Windows PowerShell cmdlets.
  • 可以使用多个步骤包含在自动化解决方案中。Can be included in automated solution with multiple steps.
  • 使用证书或 OAuth 用户主体/服务主体对请求进行身份验证。Request is authenticated with certificate or OAuth user principal / service principal.
  • 提供简单和复杂的参数值。Provide simple and complex parameter values.
  • 跟踪作业状态。Track job state.
  • 支持 PowerShell cmdlet 所需的客户端。Client required to support PowerShell cmdlets.
  • Azure 自动化 APIAzure Automation API
  • 最有弹性的方法,但也最复杂。Most flexible method but also most complex.
  • 从任何可发出 HTTP 请求的自定义代码调用。Call from any custom code that can make HTTP requests.
  • 使用证书或 OAuth 用户主体/服务主体对请求进行身份验证。Request authenticated with certificate, or Oauth user principal / service principal.
  • 提供简单和复杂的参数值。Provide simple and complex parameter values. 如果正在使用 API 调用 Python runbook,则必须序列化 JSON 有效负载。If you're calling a Python runbook using the API, the JSON payload must be serialized.
  • 跟踪作业状态。Track job state.
  • WebhookWebhooks
  • 从单个 HTTP 请求启动 Runbook。Start runbook from single HTTP request.
  • 使用 URL 中的安全令牌进行身份验证。Authenticated with security token in URL.
  • 客户端无法替代创建 Webhook 时指定的参数值。Client can't override parameter values specified when webhook created. Runbook 可以定义填入了 HTTP 请求详细信息的单个参数。Runbook can define single parameter that is populated with the HTTP request details.
  • 无法通过 Webhook URL 跟踪作业状态。No ability to track job state through webhook URL.
  • 响应 Azure 警报Respond to Azure Alert
  • 启动 Runbook 以响应 Azure 警报。Start a runbook in response to Azure alert.
  • 为 Runbook 配置 webhook 并链接到警报。Configure webhook for runbook and link to alert.
  • 使用 URL 中的安全令牌进行身份验证。Authenticated with security token in URL.
  • 计划Schedule
  • 按每小时、每天、每周或每月计划自动启动 Runbook。Automatically start runbook on hourly, daily, weekly, or monthly schedule.
  • 通过 Azure 门户、PowerShell cmdlet 或 Azure API 来操作计划。Manipulate schedule through Azure portal, PowerShell cmdlets, or Azure API.
  • 提供与计划配合使用的参数值。Provide parameter values to be used with schedule.
  • 从另一个 RunbookFrom Another Runbook
  • 将一个 Runbook 作为另一个 Runbook 中的活动使用。Use a runbook as an activity in another runbook.
  • 对多个 Runbook 使用的功能很有用。Useful for functionality used by multiple runbooks.
  • 为子 Runbook 提供参数值,并使用父 Runbook 中的输出。Provide parameter values to child runbook and use output in parent runbook.
  • 下图演示了 Runbook 生命周期的详细分步过程。The following image illustrates detailed step-by-step process in the life cycle of a runbook. 它包括在 Azure 自动化中启动 Runbook 的不同方式、混合 Runbook 辅助角色执行 Azure 自动化 Runbook 所需的组件以及不同组件之间的交互方式。It includes different ways a runbook starts in Azure Automation, which components required for Hybrid Runbook Worker to execute Azure Automation runbooks and interactions between different components. 若要了解如何在数据中心执行自动化 Runbook,请参阅混合 Runbook 辅助角色To learn about executing Automation runbooks in your datacenter, refer to hybrid runbook workers

    Runbook 体系结构

    Runbook 参数Runbook parameters

    使用 Azure 门户或 Windows PowerShell 启动 Runbook 时,系统将通过 Azure 自动化 Web 服务发送指令。When you start a runbook from the Azure portal or Windows PowerShell, the instruction is sent through the Azure Automation web service. 此服务不支持包含复杂数据类型的参数。This service doesn't support parameters with complex data types. 如果需要提供复杂参数的值,则必须根据 Azure 自动化中的子 Runbook 中所述,以内联方式从另一个 Runbook 调用该参数值。If you need to provide a value for a complex parameter, then you must call it inline from another runbook as described in Child runbooks in Azure Automation.

    Azure 自动化 Web 服务将为使用特定数据类型的参数提供特殊功能,如以下部分中所述。The Azure Automation web service provides special functionality for parameters using certain data types as described in the following sections:

    命名值Named values

    如果参数的数据类型为 [object],则可以使用以下 JSON 格式向它发送命名值列表:{Name1:'Value1', Name2:'Value2', Name3:'Value3'}。If the parameter is data type [object], then you can use the following JSON format to send it a list of named values: {Name1:'Value1', Name2:'Value2', Name3:'Value3'}. 这些值必须使用简单类型。These values must be simple types. Runbook 以 PSCustomObject 的形式接收参数,该对象的属性对应于每个命名值。The runbook receives the parameter as a PSCustomObject with properties that correspond to each named value.

    请考虑以下接受名为 user 的参数的测试 Runbook。Consider the following test runbook that accepts a parameter called user.

    Workflow Test-Parameters
    {
       param (
          [Parameter(Mandatory=$true)][object]$user
       )
        $userObject = $user | ConvertFrom-JSON
        if ($userObject.Show) {
            foreach ($i in 1..$userObject.RepeatCount) {
                $userObject.FirstName
                $userObject.LastName
            }
        }
    }
    

    可为 user 参数使用以下文本。The following text could be used for the user parameter.

    {FirstName:'Joe',LastName:'Smith',RepeatCount:'2',Show:'True'}
    

    这会导致生成以下输出:This results in the following output:

    Joe
    Smith
    Joe
    Smith
    

    数组Arrays

    如果参数是数组(如 [array] 或 [string[]]),则可以使用以下 JSON 格式向它发送值列表: [Value1,Value2,Value3]If the parameter is an array such as [array] or [string[]], then you can use the following JSON format to send it a list of values: [Value1, Value2, Value3]. 这些值必须使用简单类型。These values must be simple types.

    请考虑以下接受名为 user的参数的测试 Runbook。Consider the following test runbook that accepts a parameter called user.

    Workflow Test-Parameters
    {
       param (
          [Parameter(Mandatory=$true)][array]$user
       )
        if ($user[3]) {
            foreach ($i in 1..$user[2]) {
                $ user[0]
                $ user[1]
            }
        }
    }
    

    可为 user 参数使用以下文本。The following text could be used for the user parameter.

    ["Joe","Smith",2,true]
    

    这会导致生成以下输出:This results in the following output:

    Joe
    Smith
    Joe
    Smith
    

    凭据Credentials

    如果参数的数据类型为 PSCredential,则可以提供 Azure 自动化凭据资产的名称。If the parameter is data type PSCredential, you can provide the name of an Azure Automation credential asset. Runbook 将检索具有指定名称的凭据。The runbook retrieves the credential with the name that you specify. 以下测试 runbook 接受名为 credential 的参数。The following test runbook accepts a parameter called credential.

    Workflow Test-Parameters
    {
       param (
          [Parameter(Mandatory=$true)][PSCredential]$credential
       )
       $credential.UserName
    }
    

    假设存在名为 My Credential 的凭据资产,则可对 user 参数使用以下文本。The following text could be used for the user parameter assuming that there was a credential asset called My Credential.

    My Credential
    

    假设凭据中的用户名为 jsmith,则会显示以下输出。Assuming that the user name in the credential is jsmith, the following output is displayed.

    jsmith
    

    使用 Azure 门户启动 RunbookStart a runbook with the Azure portal

    1. 在 Azure 门户中选择“自动化”,然后单击自动化帐户的名称。In the Azure portal, select Automation and then click the name of an Automation account.
    2. 在“中心”菜单中选择“Runbook”。On the Hub menu, select Runbooks.
    3. 在“Runbook”页上选择一个 Runbook,然后单击“启动”。On the Runbooks page, select a runbook, and then click Start.
    4. 如果 Runbook 包含参数,则系统会提示在文本框中提供每个参数的值。If the runbook has parameters, you're prompted to provide values with a text box for each parameter. 有关参数的详细信息,请参阅 Runbook 参数For more information on parameters, see Runbook Parameters.
    5. 在“作业”窗格上,可以查看 runbook 作业的状态。On the Job pane, you can view the status of the runbook job.

    使用 PowerShell 启动 RunbookStart a runbook with PowerShell

    可以在 Windows PowerShell 中使用 Start-AzAutomationRunbook 启动 Runbook。You can use the Start-AzAutomationRunbook to start a runbook with Windows PowerShell. 以下示例代码启动名为“Test-Runbook”的 Runbook。The following sample code starts a runbook called Test-Runbook.

    Start-AzAutomationRunbook -AutomationAccountName "MyAutomationAccount" -Name "Test-Runbook" -ResourceGroupName "ResourceGroup01"
    

    Start-AzAutomationRunbook 返回一个作业对象。启动 Runbook 后,可以使用该对象来跟踪状态。Start-AzAutomationRunbook returns a job object that you can use to track status once the runbook is started. 然后,可以将此作业对象用于 Get-AzAutomationJob 以确定作业的状态,用于 Get-AzAutomationJobOutput 以检索其输出。You can then use this job object with Get-AzAutomationJob to determine the status of the job and Get-AzAutomationJobOutput to retrieve its output. 以下示例将启动名为“Test-Runbook”的 Runbook,等到它完成后显示其输出。The following example starts a runbook called Test-Runbook, waits until it has completed, and then displays its output.

    $runbookName = "Test-Runbook"
    $ResourceGroup = "ResourceGroup01"
    $AutomationAcct = "MyAutomationAccount"
    
    $job = Start-AzAutomationRunbook –AutomationAccountName $AutomationAcct -Name $runbookName -ResourceGroupName $ResourceGroup
    
    $doLoop = $true
    While ($doLoop) {
       $job = Get-AzAutomationJob –AutomationAccountName $AutomationAcct -Id $job.JobId -ResourceGroupName $ResourceGroup
       $status = $job.Status
       $doLoop = (($status -ne "Completed") -and ($status -ne "Failed") -and ($status -ne "Suspended") -and ($status -ne "Stopped"))
    }
    
    Get-AzAutomationJobOutput -AutomationAccountName $AutomationAcct -Id $job.JobId -ResourceGroupName $ResourceGroup -Stream Output
    

    如果 Runbook 需要参数,则必须以哈希表的形式提供参数。If the runbook requires parameters, then you must provide them as a hashtable. 哈希表的键必须与参数名称匹配,且值为参数值。The key of the hashtable must match the parameter name and the value is the parameter value. 以下示例演示如何启动包含两个名称分别为 FirstName 和 LastName 的字符串参数、一个名为 RepeatCount 的整数和一个名为 Show 的布尔参数的 Runbook。The following example shows how to start a runbook with two string parameters named FirstName and LastName, an integer named RepeatCount, and a boolean parameter named Show. 有关参数的详细信息,请参阅 Runbook 参数For more information on parameters, see Runbook Parameters.

    $params = @{"FirstName"="Joe";"LastName"="Smith";"RepeatCount"=2;"Show"=$true}
    Start-AzureRmAutomationRunbook -AutomationAccountName "MyAutomationAccount" -Name "Test-Runbook" -ResourceGroupName "ResourceGroup01" -Parameters $params
    

    后续步骤Next steps

    • 若要了解如何在数据中心执行自动化 Runbook,请参阅 混合 Runbook 辅助角色To learn about executing Automation runbooks in your datacenter, refer to Hybrid Runbook Workers.
    • 若要详细了解如何创建模块化 Runbook,供其他 Runbook 用于特定或常用函数,请参阅子 RunbookTo learn more about the creating modular runbooks to be used by other runbooks for specific or common functions, refer to Child Runbooks.
    • 有关 PowerShell 的详细信息(包括语言参考和学习模块),请参阅 PowerShell 文档For more information on PowerShell, including language reference and learning modules, refer to the PowerShell Docs.