排查 Runbook 问题Troubleshoot runbook issues

本文描述可能会发生的各种 Runbook 问题及其解决方法。This article describes runbook issues that might occur and how to resolve them. 有关常规信息,请参阅在 Azure 自动化中执行 RunbookFor general information, see Runbook execution in Azure Automation.

诊断 Runbook 问题Diagnose runbook issues

如果在 Azure 自动化中执行 Runbook 期间遇到错误,可使用以下步骤来帮助诊断问题:When you receive errors during runbook execution in Azure Automation, you can use the following steps to help diagnose the issues:

  1. 确保 Runbook 脚本在本地计算机上执行成功。Ensure that your runbook script executes successfully on your local machine.

    有关语言参考和学习模块,请参阅 PowerShell 文档Python 文档。在本地运行脚本即可发现并解决常见错误,例如:For language reference and learning modules, see the PowerShell Docs or Python Docs. Running your script locally can discover and resolve common errors, such as:

    • 缺少模块Missing modules
    • 语法错误Syntax errors
    • 逻辑错误Logic errors
  2. 调查 Runbook 错误流Investigate runbook error streams.

    查看这些流中的特定消息,并将其与本文中所述的错误进行比较。Look at these streams for specific messages, and compare them to the errors documented in this article.

  3. 确保节点和自动化工作区具有所需的模块。Ensure that your nodes and Automation workspace have the required modules.

    如果 Runbook 导入任何模块,请使用导入模块中的步骤来验证这些模块是否可供自动化帐户使用。If your runbook imports any modules, verify that they're available to your Automation account by using the steps in Import modules. 按照更新 Azure 自动化中的 Azure PowerShell 模块中的说明将 PowerShell 模块更新到最新版本。Update your PowerShell modules to the latest version by following the instructions in Update Azure PowerShell modules in Azure Automation. 有关更多的故障排除信息,请参阅排查模块问题For more troubleshooting information, see Troubleshoot modules.

  4. 如果 Runbook 暂停或意外失败:If your runbook is suspended or unexpectedly fails:

  5. 如果混合 Runbook 辅助角色中的 Runbook 作业或环境无响应,请执行此步骤。Do this step if the runbook job or the environment on Hybrid Runbook Worker doesn't respond.

    如果在混合 Runbook 辅助角色而不是 Azure 自动化中运行 Runbook 作业,可能需要排查混合辅助角色本身的问题If you're running your runbooks on a Hybrid Runbook Worker instead of in Azure Automation, you might need to troubleshoot the hybrid worker itself.

场景:Runbook 失败并出现“无权限”或“禁止 403”错误Scenario: Runbook fails with a No permission or Forbidden 403 error


Runbook 失败并出现“无权限”或“禁止 403”错误或者类似的错误。Your runbook fails with a No permission or Forbidden 403 error, or equivalent.


运行方式帐户对 Azure 资源的权限可能与当前自动化帐户的权限不同。Run As accounts might not have the same permissions against Azure resources as your current Automation account.


确保运行方式帐户有权访问脚本中使用的任何资源Ensure that your Run As account has permissions to access any resources used in your script.

场景:登录到 Azure 帐户失败Scenario: Sign-in to Azure account failed


使用 Connect-AzAccount cmdlet 时遇到以下错误之一:You receive one of the following errors when you work with the Connect-AzAccount cmdlet:

Unknown_user_type: Unknown User Type
No certificate was found in the certificate store with thumbprint


如果凭据资产名称无效,将发生这些错误。These errors occur if the credential asset name isn't valid. 如果用于设置自动化凭据资产的用户名和密码无效,也可能会发生这些错误。They might also occur if the user name and password that you used to set up the Automation credential asset aren't valid.


若要确定问题所在,请执行以下步骤:To determine what's wrong, follow these steps:

  1. 确保没有包含任何特殊字符。Make sure that you don't have any special characters. 这些字符包括用于连接 Azure 的自动化凭据资产名称中的 \@ 字符。These characters include the \@ character in the Automation credential asset name that you're using to connect to Azure.

  2. 查看是否能够在本地 PowerShell ISE 编辑器中使用存储在 Azure 自动化凭据中的用户名和密码。Check to see if you can use the user name and password that are stored in the Azure Automation credential in your local PowerShell ISE editor. 在 PowerShell ISE 中运行以下 cmdlet。Run the following cmdlets in the PowerShell ISE.

    $Cred = Get-Credential
    #Using Azure Service Management
    Add-AzureAccount -Environment AzureChinaCloud -Credential $Cred  
    #Using Azure Resource Manager
    Connect-AzAccount -Environment AzureChinaCloud -Credential $Cred
  3. 如果该错误看上去是暂时性的,请尝试向身份验证例程添加重试逻辑,使身份验证更加可靠。If the error appears to be transient, try adding retry logic to your authentication routine to make authenticating more robust.

    # Get the connection "AzureRunAsConnection"
    $connectionName = "AzureRunAsConnection"
    $servicePrincipalConnection = Get-AutomationConnection -Name $connectionName
    $logonAttempt = 0
    $logonResult = $False
    while(!($connectionResult) -And ($logonAttempt -le 10))
        #Logging in to Azure...
        $connectionResult = Connect-AzAccount `
                               -Environment AzureChinaCloud `
                               -ServicePrincipal `
                               -Tenant $servicePrincipalConnection.TenantId `
                               -ApplicationId $servicePrincipalConnection.ApplicationId `
                               -CertificateThumbprint $servicePrincipalConnection.CertificateThumbprint
        Start-Sleep -Seconds 30

场景:运行 Login-AzureRMAccount 进行登录Scenario: Run Login-AzureRMAccount to log in


运行 Runbook 时遇到以下错误:You receive the following error when you run a runbook:

Run Login-AzureRMAccount to login.


如果使用的不是运行方式帐户或者运行方式帐户已过期,则可能会发生此错误。This error can occur when you're not using a Run As account or the Run As account has expired. 有关详细信息,请参阅 Azure 自动化运行方式帐户概述For more information, see Azure Automation Run As accounts overview.

此错误有两个主要原因:This error has two primary causes:

  • 使用了不同版本的 AzureRM 或 Az 模块。There are different versions of the AzureRM or Az module.
  • 正在尝试访问单独订阅中的资源。You're trying to access resources in a separate subscription.


如果在更新一个 AzureRM 或 Az 模块后遇到此错误,请将所有模块更新为同一版本。If you receive this error after you update one AzureRM or Az module, update all your modules to the same version.

如果你正在尝试访问其他订阅中的资源,请执行以下步骤来配置权限:If you're trying to access resources in another subscription, follow these steps to configure permissions:

  1. 转到自动化运行方式帐户,并复制“应用程序 ID”和“指纹”。 Go to the Automation Run As account, and copy the Application ID and Thumbprint.

    复制“应用程序 ID”和“指纹”

  2. 访问未托管自动化帐户的订阅的“访问控制”,并添加新的角色分配。Go to the subscription's Access control where the Automation account is not hosted, and add a new role assignment.


  3. 添加前面收集的“应用程序 ID”。Add the Application ID collected earlier. 选择“参与者”权限。Select Contributor permissions.


  4. 复制该订阅的名称。Copy the name of the subscription.

  5. 现在,可以使用以下 Runbook 代码来测试从自动化帐户访问其他订阅的权限。You can now use the following runbook code to test the permissions from your Automation account to the other subscription. 请将 "\<CertificateThumbprint\>" 替换为在步骤 1 中复制的值。Replace "\<CertificateThumbprint\>" with the value copied in step 1. 请将 "\<SubscriptionName\>" 替换为在步骤 4 中复制的值。Replace "\<SubscriptionName\>" with the value copied in step 4.

    $Conn = Get-AutomationConnection -Name AzureRunAsConnection
    Connect-AzAccount -Environment AzureChinaCloud -ServicePrincipal -Tenant $Conn.TenantID -ApplicationId $Conn.ApplicationID -CertificateThumbprint "<CertificateThumbprint>"
    #Select the subscription you want to work with
    Select-AzSubscription -SubscriptionName '<YourSubscriptionNameGoesHere>'
    #Test and get outputs of the subscriptions you granted access.
    $subscriptions = Get-AzSubscription
    foreach($subscription in $subscriptions)
        Set-AzContext $subscription
        Write-Output $subscription.Name

场景:无法找到 Azure 订阅Scenario: Unable to find the Azure subscription


使用 Select-AzureSubscriptionSelect-AzureRMSubscriptionSelect-AzSubscription cmdlet 时遇到以下错误:You receive the following error when you work with the Select-AzureSubscription, Select-AzureRMSubscription, or Select-AzSubscription cmdlet:

The subscription named <subscription name> cannot be found.


如果存在以下情况,则可能会发生此错误:This error can occur if:

  • 订阅名称无效。The subscription name isn't valid.
  • 尝试获取订阅详细信息的 Azure AD 用户未配置为订阅的管理员。The Azure AD user who's trying to get the subscription details isn't configured as an administrator of the subscription.
  • cmdlet 不可用。The cmdlet isn't available.


执行以下步骤来确定是否已在 Azure 中完成身份验证并有权访问你尝试选择的订阅:Follow these steps to determine if you've authenticated to Azure and have access to the subscription that you're trying to select:

  1. 为确保脚本可单独正常运行,请在 Azure 自动化外部对其进行测试。To make sure that your script works standalone, test it outside of Azure Automation.

  2. 确保脚本先运行 Connect-AzAccount cmdlet,再运行 Select-* cmdlet。Make sure that your script runs the Connect-AzAccount cmdlet before running the Select-* cmdlet.

  3. Disable-AzContextAutosave –Scope Process 添加到 runbook 的开头。Add Disable-AzContextAutosave –Scope Process to the beginning of your runbook. 此 cmdlet 可以确保任何凭据都仅适用于当前 runbook 的执行。This cmdlet ensures that any credentials apply only to the execution of the current runbook.

  4. 如果仍看到该错误消息,请通过为 Connect-AzAccount 添加 AzContext 参数来修改代码,然后执行代码。If you still see the error message, modify your code by adding the AzContext parameter for Connect-AzAccount, and then execute the code.

    Disable-AzContextAutosave –Scope Process
    $Conn = Get-AutomationConnection -Name AzureRunAsConnection
    Connect-AzAccount -Environment AzureChinaCloud -ServicePrincipal -Tenant $Conn.TenantID -ApplicationId $Conn.ApplicationID -CertificateThumbprint $Conn.CertificateThumbprint
    $context = Get-AzContext
    Get-AzVM -ResourceGroupName myResourceGroup -AzContext $context

场景:处理多个订阅时,Runbook 失败Scenario: Runbooks fail when dealing with multiple subscriptions


执行 Runbook 时,Runbook 无法管理 Azure 资源。When executing runbooks, the runbook fails to manage Azure resources.


Runbook 在运行时没有使用正确的上下文。The runbook isn't using the correct context when running. 这可能是因为 runbook 无意中尝试访问不正确的订阅。This may be because the runbook is accidentally trying to access the incorrect subscription.

你可能会看到如下错误:You may see errors like this one:

Get-AzVM : The client '<automation-runas-account-guid>' with object id '<automation-runas-account-guid>' does not have authorization to perform action 'Microsoft.Compute/virtualMachines/read' over scope '/subscriptions/<subcriptionIdOfSubscriptionWichDoesntContainTheVM>/resourceGroups/REsourceGroupName/providers/Microsoft.Compute/virtualMachines/VMName '.
   ErrorCode: AuthorizationFailed
   StatusCode: 403
   ReasonPhrase: Forbidden Operation
   ID : <AGuidRepresentingTheOperation> At line:51 char:7 + $vm = Get-AzVM -ResourceGroupName $ResourceGroupName -Name $UNBV... +


当某个 Runbook 调用多个 Runbook 时,订阅上下文可能会丢失。The subscription context might be lost when a runbook invokes multiple runbooks. 若要避免意外尝试访问不正确的订阅,应遵循以下指导。To avoid accidentally trying to access the incorrect subscription you should follow the guidance below.

  • 为避免引用错误的订阅,请在每个 runbook 的开头使用以下代码来禁用自动化 runbook 中的上下文保存。To avoid referencing the wrong subscription, disable context saving in your Automation runbooks by using the following code at the start of each runbook.

    Disable-AzContextAutosave –Scope Process
  • Azure PowerShell cmdlet 支持 -DefaultProfile 参数。The Azure PowerShell cmdlets support the -DefaultProfile parameter. 该支持已添加到所有 Az 和 AzureRm cmdlet 中,以支持在同一进程中运行多个 PowerShell 脚本,因此你可以指定上下文和要用于每个 cmdlet 的订阅。This was added to all Az and AzureRm cmdlets to support running multiple PowerShell scripts in the same process, allowing you to specify the context and which subscription to use for each cmdlet. 使用 runbook 时,应在创建 runbook(即帐户登录)时以及每次更改时将上下文对象保存在 runbook 中,并在指定 Az cmdlet 时引用上下文。With your runbooks, you should save the context object in your runbook when the runbook is created (that is, when an account signs in) and every time it's changed, and reference the context when you specify an Az cmdlet.


    即使在使用 Set-AzContextSelect-AzSubscription 之类的 cmdlet 直接操作上下文时,也应该传递上下文对象。You should pass in a context object even when manipulating the context directly using cmdlets such as Set-AzContext or Select-AzSubscription.

    $servicePrincipalConnection=Get-AutomationConnection -Name $connectionName 
    $context = Add-AzAccount `
               -Environment AzureChinaCloud `
               -ServicePrincipal `
               -TenantId $servicePrincipalConnection.TenantId `
               -ApplicationId $servicePrincipalConnection.ApplicationId `
               -Subscription 'cd4dxxxx-xxxx-xxxx-xxxx-xxxxxxxx9749' `
               -CertificateThumbprint $servicePrincipalConnection.CertificateThumbprint 
    $context = Set-AzContext -SubscriptionName $subscription `
         -DefaultProfile $context
    Get-AzVm -DefaultProfile $context

场景:无法在 Azure 中进行身份验证,因为已启用多重身份验证Scenario: Authentication to Azure fails because multifactor authentication is enabled


使用 Azure 用户名和密码在 Azure 中进行身份验证时遇到以下错误:You receive the following error when authenticating to Azure with your Azure user name and password:

Add-AzureAccount: AADSTS50079: Strong authentication enrollment (proof-up) is required


如果对 Azure 帐户设置了多重身份验证,则不能使用 Azure Active Directory 用户在 Azure 中进行身份验证,If you have multifactor authentication on your Azure account, you can't use an Azure Active Directory user to authenticate to Azure. 而必须使用证书或服务主体进行身份验证。Instead, you need to use a certificate or a service principal to authenticate.


若要通过 Azure 经典部署模型 cmdlet 使用经典运行方式帐户,请参阅创建经典运行方式帐户来管理 Azure 服务To use a Classic Run As account with Azure classic deployment model cmdlets, see Create a Classic Run As account to manage Azure services. 若要在 Azure 资源管理器 cmdlet 中使用服务主体,请参阅使用 Azure 门户创建服务主体使用 Azure 资源管理器对服务主体进行身份验证To use a service principal with Azure Resource Manager cmdlets, see Creating service principal using Azure portal and Authenticating a service principal with Azure Resource Manager.

场景:字词未识别为 cmdlet、函数或脚本的名称Scenario: Term not recognized as the name of a cmdlet, function, or script


Runbook 失败,出现类似于以下示例的错误:Your runbook fails with an error similar to the following example:

The term 'Connect-AzAccount' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if the path was included verify that the path is correct and try again.


此错误可能是由以下原因造成的:This error can happen for the following reasons:

  • 包含该 cmdlet 的模块未导入到自动化帐户中。The module that contains the cmdlet isn't imported into the Automation account.
  • 包含该 cmdlet 的模块已导入但已过时。The module that contains the cmdlet is imported but is out of date.


执行以下任务之一来解决此错误:Do one of the following tasks to resolve this error:

方案:对 Azure 自动化中的 PnP PowerShell Runbook 运行 Cmdlet 失败Scenario: Cmdlet fails in PnP PowerShell runbook on Azure Automation


当 Runbook 直接将 PnP PowerShell 生成的对象写入 Azure 自动化输出时,cmdlet 输出无法流式传输回自动化。When a runbook writes a PnP PowerShell-generated object to the Azure Automation output directly, cmdlet output can't stream back to Automation.


此问题的最常见原因是 Azure 自动化在未捕获返回对象的情况下处理调用 PnP PowerShell cmdlet(例如 add-pnplistitem)的 Runbook。This issue most commonly occurs when Azure Automation processes runbooks that invoke PnP PowerShell cmdlets, for example, add-pnplistitem, without catching the return objects.


编辑脚本以将任何返回值分配到变量,使 cmdlet 不会尝试将整个对象写入标准输出。Edit your scripts to assign any return values to variables so that the cmdlets don't attempt to write whole objects to the standard output. 脚本可将输出流重定向到 cmdlet,如下所示。A script can redirect the output stream to a cmdlet, as shown here.

  $null = add-pnplistitem

如果脚本分析 cmdlet 输出,该脚本必须将输出存储在某个变量中,然后操控变量,而不是仅流式传输输出。If your script parses cmdlet output, the script must store the output in a variable and manipulate the variable instead of simply streaming the output.

$SomeVariable = add-pnplistitem ....
if ($SomeVariable.someproperty -eq ....

场景:在执行 Runbook 时无法识别 cmdletScenario: Cmdlet not recognized when executing a runbook


Runbook 作业失败并显示错误:Your runbook job fails with the error:

<cmdlet name>: The term <cmdlet name> is not recognized as the name of a cmdlet, function, script file, or operable program.


当 PowerShell 引擎找不到要在 runbook 中使用的 cmdlet 时,则会导致此错误。This error is caused when the PowerShell engine can't find the cmdlet you're using in your runbook. 可能的原因是帐户中缺少包含该 cmdlet 的模块、与 Runbook 名称存在名称冲突,或者该 cmdlet 也存在于其他模块中,而自动化无法解析该名称。It's possible that the module containing the cmdlet is missing from the account, there's a name conflict with a runbook name, or the cmdlet also exists in another module and Automation can't resolve the name.


使用以下任一解决方法来解决问题。Use any of the following solutions to fix the problem:

  • 确保输入的 cmdlet 名称正确。Make sure that you've entered the cmdlet name correctly.
  • 确保 cmdlet 存在于自动化帐户中,且没有冲突。Ensure that the cmdlet exists in your Automation account and that there are no conflicts. 若要验证该 cmdlet 是否存在,请在编辑模式下打开一个 Runbook,并搜索希望在库中找到的 cmdlet,或者运行 Get-Command <CommandName>To verify if the cmdlet is present, open a runbook in edit mode and search for the cmdlet you want to find in the library, or run Get-Command <CommandName>. 验证该 cmdlet 可供帐户使用且与其他 cmdlet 或 Runbook 不存在名称冲突以后,可将该 cmdlet 添加到画布。After you've validated that the cmdlet is available to the account, and that there are no name conflicts with other cmdlets or runbooks, add the cmdlet to the canvas. 确保使用的是 Runbook 中的有效参数集。Make sure that you're using a valid parameter set in your runbook.
  • 如果存在名称冲突且 cmdlet 可在两个不同的模块中使用,请使用 cmdlet 的完全限定名称来解决问题。If you do have a name conflict and the cmdlet is available in two different modules, resolve the issue by using the fully qualified name for the cmdlet. 例如,可以使用 ModuleName\CmdletNameFor example, you can use ModuleName\CmdletName.
  • 如果在本地执行混合辅助角色组中的 Runbook,请确保模块和 cmdlet 已安装在托管混合辅助角色的计算机上。If you're executing the runbook on-premises in a hybrid worker group, ensure that the module and cmdlet are installed on the machine that hosts the hybrid worker.

场景:调用 Add-AzAccount 时对象引用不正确Scenario: Incorrect object reference on call to Add-AzAccount


使用 Add-AzAccountConnect-AzAccount cmdlet 的别名)时遇到此错误:You receive this error when you work with Add-AzAccount, which is an alias for the Connect-AzAccount cmdlet:

Add-AzAccount : Object reference not set to an instance of an object


如果在调用 Add-AzAccount 来添加自动化帐户之前 Runbook 未执行正确的步骤,则可能会发生此错误。This error can occur if the runbook doesn't do the proper steps before calling Add-AzAccount to add the Automation account. 例如,必要的步骤之一是使用运行方式帐户登录。An example of one of the necessary steps is signing in with a Run As account. 有关要在 Runbook 中使用的正确操作,请参阅在 Azure 自动化中执行 RunbookFor the correct operations to use in your runbook, see Runbook execution in Azure Automation.

场景:对象引用未设置为某个对象的实例Scenario: Object reference not set to an instance of an object


结合 Wait 参数调用子 Runbook 并且输出流包含对象时遇到以下错误:You receive the following error when you invoke a child runbook with the Wait parameter and the Output stream contains an object:

Object reference not set to an instance of an object


如果流包含对象,Start-AzAutomationRunbook 不会正常处理输出流。If the stream contains objects, Start-AzAutomationRunbook doesn't handle the Output stream correctly.


实现轮询逻辑,并使用 Get-AzAutomationJobOutput cmdlet 检索输出。Implement a polling logic, and use the Get-AzAutomationJobOutput cmdlet to retrieve the output. 下面定义了此逻辑的示例:A sample of this logic is defined here:

$automationAccountName = "ContosoAutomationAccount"
$runbookName = "ChildRunbookExample"
$resourceGroupName = "ContosoRG"

function IsJobTerminalState([string] $status) {
    return $status -eq "Completed" -or $status -eq "Failed" -or $status -eq "Stopped" -or $status -eq "Suspended"

$job = Start-AzAutomationRunbook -AutomationAccountName $automationAccountName -Name $runbookName -ResourceGroupName $resourceGroupName
$pollingSeconds = 5
$maxTimeout = 10800
$waitTime = 0
while($false -eq (IsJobTerminalState $job.Status) -and $waitTime -lt $maxTimeout) {
   Start-Sleep -Seconds $pollingSeconds
   $waitTime += $pollingSeconds
   $job = $job | Get-AzAutomationJob

$job | Get-AzAutomationJobOutput | Get-AzAutomationJobOutputRecord | Select-Object -ExpandProperty Value

场景:Runbook 因反序列化的对象而失败Scenario: Runbook fails because of deserialized object


Runbook 失败并显示错误:Your runbook fails with the error:

Cannot bind parameter <ParameterName>.

Cannot convert the <ParameterType> value of type Deserialized <ParameterType> to type <ParameterType>.


如果 runbook 为 PowerShell 工作流,它会将复杂对象以反序列化格式进行存储,以便在工作流暂停的情况下保留 runbook 状态。If your runbook is a PowerShell Workflow, it stores complex objects in a deserialized format to persist your runbook state if the workflow is suspended.


使用以下任一解决方案来解决此问题:Use any of the following solutions to fix this problem:

  • 如果将复杂对象从一个 cmdlet 传送到另一个 cmdlet,请将这些 cmdlet 包装在 InlineScript 活动中。If you're piping complex objects from one cmdlet to another, wrap these cmdlets in an InlineScript activity.
  • 传递复杂对象中你所需要的名称或值,不必传递整个对象。Pass the name or value that you need from the complex object instead of passing the entire object.
  • 使用 PowerShell Runbook,而不使用 PowerShell 工作流 Runbook。Use a PowerShell runbook instead of a PowerShell Workflow runbook.

场景:调用 Webhook 时显示“400 错误的请求”状态Scenario: 400 Bad Request status when calling a webhook


在尝试调用 Azure 自动化 Runbook 的 Webhook 时遇到以下错误:When you try to invoke a webhook for an Azure Automation runbook, you receive the following error:

400 Bad Request : This webhook has expired or is disabled


尝试调用的 Webhook 已禁用,或者已过期。The webhook that you're trying to call is either disabled or is expired.


如果 Webhook 处于禁用状态,可以通过 Azure 门户重新启用它。If the webhook is disabled, you can re-enable it through the Azure portal. 如果 Webhook 已过期,必须将其删除,然后重新创建。If the webhook has expired, you must delete and then re-create it. 如果尚未过期,只能续订 WebhookYou can only renew a webhook if it hasn't already expired.

场景:429:当前的请求速率过大Scenario: 429: The request rate is currently too large


在运行 Get-AzAutomationJobOutput cmdlet 时收到以下错误消息:You receive the following error message when running the Get-AzAutomationJobOutput cmdlet:

429: The request rate is currently too large. Please try again


从包含多个详细流的 Runbook 中检索作业输出时,可能会发生此错误。This error can occur when retrieving job output from a runbook that has many verbose streams.


执行以下操作之一来解决此错误:Do one of the following to resolve this error:

  • 编辑 Runbook,并减少它发出的作业流数量。Edit the runbook, and reduce the number of job streams that it emits.
  • 减少运行 cmdlet 时要检索的流数量。Reduce the number of streams to be retrieved when running the cmdlet. 为此,可以设置 Get-AzAutomationJobOutput cmdlet 的 Stream 参数值,以仅检索输出流。To do this, you can set the value of the Stream parameter for the Get-AzAutomationJobOutput cmdlet to retrieve only Output streams.

场景:Runbook 输出流大于 1 MBScenario: Runbook output stream greater than 1 MB


在 Azure 沙盒中运行的 runbook 失败,并出现以下错误:Your runbook running in the Azure sandbox fails with the following error:

The runbook job failed due to a job stream being larger than 1MB, this is the limit supported by an Azure Automation sandbox.


出现此错误是因为 runbook 尝试向输出流写入太多异常数据。This error occurs because your runbook attempted to write too much exception data to the output stream.


作业输出流限制为 1 MB。There's a 1 MB limit on the job output stream. 确保 Runbook 使用 trycatch 块包含对可执行文件或子进程的调用。Ensure that your runbook encloses calls to an executable or subprocess by using try and catch blocks. 如果操作引发异常,请让代码将该异常中的消息写入自动化变量中。If the operations throw an exception, have the code write the message from the exception into an Automation variable. 此方法可防止将消息写入作业输出流中。This technique prevents the message from being written into the job output stream. 对于执行的混合 Runbook 辅助角色作业,将显示截断为 1 MB 的输出流,且不显示任何错误消息。For Hybrid Runbook Worker jobs executed, the output stream truncated to 1 MB is displayed with no error message.

场景:已尝试启动 Runbook 作业三次,但每次都失败Scenario: Runbook job start attempted three times, but fails to start each time


Runbook 失败并出现以下错误:Your runbook fails with the following error:

The job was tried three times but it failed


此错误是由以下问题之一造成的:This error occurs because of one of the following issues:

  • 内存限制。Memory limit. 如果作业使用的内存超过 400 MB,则它可能会失败。A job might fail if it's using more than 400 MB of memory. 自动化服务限制中阐述了分配给沙盒的内存限制。The documented limits on memory allocated to a sandbox are found at Automation service limits.

  • 网络套接字。Network sockets. Azure 沙盒限制为 1000 个并发网络套接字。Azure sandboxes are limited to 1,000 concurrent network sockets. 有关详细信息,请参阅自动化服务限制For more information, see Automation service limits.

  • 模块不兼容。Module incompatible. 模块依赖关系可能不正确。Module dependencies might not be correct. 在这种情况下,Runbook 通常会返回 Command not foundCannot bind parameter 消息。In this case, your runbook typically returns a Command not found or Cannot bind parameter message.

  • 未为沙盒设置 Active Directory 身份验证。No authentication with Active Directory for sandbox. Runbook 尝试调用在 Azure 沙盒中运行的可执行文件或子进程。Your runbook attempted to call an executable or subprocess that runs in an Azure sandbox. 不支持将 Runbook 配置为使用 Azure Active Directory 身份验证库 (ADAL) 对 Azure AD 进行身份验证。Configuring runbooks to authenticate with Azure AD by using the Azure Active Directory Authentication Library (ADAL) isn't supported.


  • 内存限制,网络套接字。Memory limit, network sockets. 若要在内存限制内工作,建议的方法是在多个 Runbook 之间拆分工作负荷,在内存中处理更少的数据,避免从 Runbook 写入不必要的输出,并考虑将多少个检查点写入 PowerShell 工作流 Runbook。Suggested ways to work within the memory limits are to split the workload among multiple runbooks, process less data in memory, avoid writing unnecessary output from your runbooks, and consider how many checkpoints are written into your PowerShell workflow runbooks. 使用 clear 方法(例如 $myVar.clear)清除变量并使用 [GC]::Collect 立即运行垃圾回收。Use the clear method, such as $myVar.clear, to clear out variables and use [GC]::Collect to run garbage collection immediately. 这将减少运行时期间 runbook 的内存占用情况。These actions reduce the memory footprint of your runbook during runtime.

  • 模块不兼容。Module incompatible. 遵循如何更新 Azure 自动化中的 Azure PowerShell 模块中的步骤更新 Azure 模块。Update your Azure modules by following the steps in How to update Azure PowerShell modules in Azure Automation.

  • 未为沙盒设置 Active Directory 身份验证。No authentication with Active Directory for sandbox. 使用 Runbook 向 Azure AD 进行身份验证时,请确保 Azure AD 模块在自动化帐户中可用。When you authenticate to Azure AD with a runbook, ensure that the Azure AD module is available in your Automation account. 确保为运行方式帐户授予所需的权限,使其能够执行 Runbook 自动执行的任务。Be sure to grant the Run As account the necessary permissions to perform the tasks that the runbook automates.

    如果 Runbook 无法调用 Azure 沙盒中运行的可执行文件或子进程,请在混合 Runbook 辅助角色中使用 Runbook。If your runbook can't call an executable or subprocess running in an Azure sandbox, use the runbook on a Hybrid Runbook Worker. 混合辅助角色不受内存和网络限制,而 Azure 沙盒则受限于此限制。Hybrid workers aren't limited by the memory and network limits that Azure sandboxes have.

场景:PowerShell 作业失败并出现“无法调用方法”错误消息Scenario: PowerShell job fails with "Cannot invoke method" error message


某个 Runbook 在 Azure 中运行,而你在该 Runbook 中启动 PowerShell 作业时收到以下错误消息:You receive the following error message when you start a PowerShell job in a runbook that runs in Azure:

Exception was thrown - Cannot invoke method. Method invocation is supported only on core types in this language mode.


此错误可能表示在 Azure 沙盒中运行的 Runbook 无法在“完整语言”模式下运行。This error might indicate that runbooks that run in an Azure sandbox can't run in the Full Language mode.


可通过两种方法来解决此错误:There are two ways to resolve this error:

若要详细了解 Azure 自动化 Runbook 的此行为和其他行为,请参阅在 Azure 自动化中执行 RunbookTo learn more about this behavior and other behaviors of Azure Automation runbooks, see Runbook execution in Azure Automation.

场景:长时间运行的 Runbook 无法完成Scenario: A long-running runbook fails to complete


运行三小时后,Runbook 显示处于“已停止”状态。Your runbook shows in a Stopped state after running for three hours. 此外,可能会遇到以下错误:You might also receive this error:

The job was evicted and subsequently reached a Stopped state. The job cannot continue running.

此行为是 Azure 沙盒的设计使然,因为 Azure 自动化中会对进程进行公平份额监视。This behavior is by design in Azure sandboxes because of the fair share monitoring of processes within Azure Automation. 如果进程的执行时间超过三小时,公平份额会自动停止 Runbook。If a process executes longer than three hours, fair share automatically stops a runbook. 超过公平份额时间限制的 Runbook 的状态因 Runbook 类型而异。The status of a runbook that goes past the fair share time limit differs by runbook type. PowerShell 和 Python Runbook 设置为“已停止”状态。PowerShell and Python runbooks are set to a Stopped status. PowerShell 工作流 Runbook 设置为“失败”。PowerShell Workflow runbooks are set to Failed.


Runbook 运行时间超出了 Azure 沙盒中公平份额允许的三小时限制。The runbook ran over the three-hour limit allowed by fair share in an Azure sandbox.


建议的解决方案是在混合 Runbook 辅助角色上运行 runbook。One recommended solution is to run the runbook on a Hybrid Runbook Worker. 混合辅助角色不受 Azure 沙盒的三小时公平份额 Runbook 限制。Hybrid workers aren't limited by the three-hour fair share runbook limit that Azure sandboxes have. 应开发在混合 Runbook 辅助角色上运行的 Runbook,以便在出现意外的本地基础结构问题时支持重启行为。Runbooks that run on Hybrid Runbook Workers should be developed to support restart behaviors if there are unexpected local infrastructure issues.

另一种解决方案是通过创建子 Runbook 来优化 Runbook。Another solution is to optimize the runbook by creating child runbooks. 如果 Runbook 在多个资源上循环访问同一函数,例如在多个数据库上执行某个数据库操作,可将该函数移到子 Runbook。If your runbook loops through the same function on several resources, for example, in a database operation on several databases, you can move the function to a child runbook. 每个子 Runbook 在单独的进程中并行执行。Each child runbook executes in parallel in a separate process. 此行为降低了完成父 runbook 所需的时间总量。This behavior decreases the total amount of time for the parent runbook to complete.

启用子 runbook 方案的 PowerShell cmdlet 是:The PowerShell cmdlets that enable the child runbook scenario are:

  • Start-AzAutomationRunbookStart-AzAutomationRunbook. 此 cmdlet 用于启动 Runbook 并将参数传递给该 Runbook。This cmdlet allows you to start a runbook and pass parameters to the runbook.
  • Get-AzAutomationJobGet-AzAutomationJob. 如果在子 Runbook 完成后需要执行操作,可使用此 cmdlet 检查每个子 Runbook 的作业状态。If there are operations that need to be performed after the child runbook completes, this cmdlet allows you to check the job status for each child.

场景:作业流中出现有关 get_SerializationSettings 方法的错误Scenario: Error in job streams about the get_SerializationSettings method


Runbook 的作业流中出现以下错误:You see the following error in your job streams for a runbook:

Connect-AzAccount : Method 'get_SerializationSettings' in type
'Microsoft.Azure.Management.Internal.Resources.ResourceManagementClient' from assembly
'Microsoft.Azure.Commands.ResourceManager.Common, Version=, Culture=neutral, PublicKeyToken=31bf3856ad364e35'
does not have an implementation.
At line:16 char:1
+ Connect-AzAccount -ServicePrincipal -Tenant $Conn.TenantID -Appl ...
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : NotSpecified: (:) [Connect-AzAccount], TypeLoadException
    + FullyQualifiedErrorId : System.TypeLoadException,Microsoft.Azure.Commands.Profile.ConnectAzAccountCommand


此错误的可能原因是在 Runbook 中使用了从 AzureRM 到 Az 模块的不完整迁移。This error is probably caused by using an incomplete migration from AzureRM to Az modules in your runbook. 这种情况可能导致 Azure 自动化仅使用 AzureRM 模块启动 Runbook 作业,然后仅使用 Az 模块启动另一个作业,从而导致沙盒崩溃。This situation can cause Azure Automation to start a runbook job by using only AzureRM modules, and then start another job by using only Az modules, which leads to a sandbox crash.


不建议在同一 Runbook 中使用 Az 和 AzureRM cmdlet。We don't recommend the use of Az and AzureRM cmdlets in the same runbook. 若要详细了解模块的正确用法,请参阅迁移到 Az 模块To learn more about the correct use of the modules, see Migrate to Az modules.

场景:对 Runbook 或应用程序使用 Azure 沙盒时出现“拒绝访问”Scenario: Access denied when using Azure sandbox for runbook or application


当 Runbook 或应用程序尝试在 Azure 沙盒中运行时,环境将拒绝访问。When your runbook or application attempts to run in an Azure sandbox, the environment denies access.


之所以会出现此问题,是因为 Azure 沙盒会阻止访问所有的进程外 COM 服务器。This issue can occur because Azure sandboxes prevent access to all out-of-process COM servers. 例如,沙盒应用程序或 Runbook 无法调用 Windows Management Instrumentation (WMI) 或 Windows Installer 服务 (msiserver.exe)。For example, a sandboxed application or runbook can't call into Windows Management Instrumentation (WMI) or into the Windows Installer service (msiserver.exe).


若要详细了解如何使用 Azure 沙盒,请参阅 Runbook 执行环境For details about the use of Azure sandboxes, see Runbook execution environment.

方案:在 Runbook 中使用 Key Vault 时出现“无效且禁止”状态代码Scenario: Invalid Forbidden status code when using Key Vault inside a runbook


尝试通过 Azure 自动化 Runbook 访问 Azure Key Vault 时遇到以下错误:When you try to access Azure Key Vault through an Azure Automation runbook, you get the following error:

Operation returned an invalid status code 'Forbidden'


此问题的可能原因包括:Possible causes for this issue are:

  • 未使用运行方式帐户。Not using a Run As account.
  • 权限不足。Insufficient permissions.


未使用运行方式帐户Not using a Run As account

执行步骤 5 - 添加身份验证来管理 Azure 资源,以确保使用运行方式帐户访问 Key Vault。Follow Step 5 - Add authentication to manage Azure resources to ensure that you are using a Run As account to access Key Vault.

权限不足Insufficient permissions

将权限添加到 Key Vault,以确保运行方式帐户拥有足够的权限,可以访问 Key Vault。Add permissions to Key Vault to ensure that your Run As account has sufficient permissions to access Key Vault.

后续步骤Next steps

如果你的问题未在本文中列出,或者你无法解决自己的问题,请尝试通过以下渠道之一获取更多支持:If you don't see your problem here or you're unable to resolve your issue, try one of the following channels for more support: