配置运行手册的输出和消息流

大多数 Azure 自动化的 runbooks 都有某种形式的输出。 此输出可以是给用户的错误消息，或者是你打算与其他运行手册结合使用的复杂对象。 Windows PowerShell 提供多个流，以便从脚本或工作流发送输出。 Azure 自动化以不同方式处理每个流。 在创建 runbook 时，应遵循使用数据流的最佳实践。

下表简要介绍了在 Azure 门户中，发布的 Runbook 以及测试 Runbook 期间每个流及其行为。 输出流是 Runbook 之间进行通信的主要通道。 其他流分类为消息流，旨在向用户传递信息。

使用输出流

输出流用于输出脚本或工作流创建的对象（如果该脚本或工作流正常运行）。 Azure 自动化将此流主要用于供调用当前 Runbook 的父 Runbook 使用的对象。 当父级 Runbook 调用内联 Runbook 时，子 Runbook 会将输出流中的数据返回给父级 Runbook。

只有当其他 Runbook 从未调用它时，你的 Runbook 才使用输出流向客户端传递常规信息。 然而，作为最佳实践，建议您的运行手册通常使用详细信息流向用户传达一般信息。

让 runbook 使用 Write-Output 将数据写入输出流。 或者，你可以在脚本中将对象放置在其自己的行上。

#The following lines both write an object to the output stream.
Write-Output -InputObject $object
$object

处理函数输出

当 runbook 函数写入到输出流时，输出会传递回 runbook。 如果 Runbook 将该输出分配给某个变量，则不会将输出写入输出流。 从函数内部向其他任何流写入数据会写入到 Runbook 相应的流。 请考虑以下示例 PowerShell 工作流运行手册(runbook)。

Workflow Test-Runbook
{
  Write-Verbose "Verbose outside of function" -Verbose
  Write-Output "Output outside of function"
  $functionOutput = Test-Function
  $functionOutput

  Function Test-Function
  {
    Write-Verbose "Verbose inside of function" -Verbose
    Write-Output "Output inside of function"
  }
}

运行手册作业的输出流为：

Output inside of function
Output outside of function

以下是 Runbook 作业的详细信息流：

Verbose outside of function
Verbose inside of function

发布 runbook 后，在启动它之前，还必须在 runbook 设置中启用详细日志，以便获取详细输出流。

声明输出数据类型

下面是输出数据类型的示例：

• System.String
• System.Int32
• System.Collections.Hashtable
• Microsoft.Azure.Commands.Compute.Models.PSVirtualMachine

在工作流中声明输出数据类型

工作流使用 OutputType 属性指定其输出的数据类型。 此属性在运行时不起作用，但在设计时，它会指示 Runbook 的预期输出。 随着 Runbook 工具集的持续发展，在设计时声明输出数据类型的重要性也在不断提升。 因此，一个最佳做法是在您创建的所有运行手册中包含此声明。

以下示例作业计划将输出一个字符串对象，并包含其输出类型的声明。 如果 Runbook 输出了某种特定类型的数组，你仍然应该指定该类型，而不是该类型的数组。

Workflow Test-Runbook
{
  [OutputType([string])]

  $output = "This is some string output."
  Write-Output $output
}

在图形化分册中声明输出数据的类型

若要在图形运行簿或 PowerShell 工作流运行簿中声明输出类型，可以选择“输入和输出”菜单选项，并输入输出类型。 建议使用完整的 .NET 类名，这样当父级 runbook 引用该类型时，可以轻松识别它。 使用全名会向 Runbook 中的数据总线公开该类的所有属性，并在将这些属性用于条件逻辑、日志记录和作为其他 Runbook 活动的值引用时提高灵活性。

以下示例展示两个图形化的 Runbook，以演示输入和输出功能。 如果应用模块化 Runbook 设计模型，您将拥有一个用作身份验证的 Runbook 模板，该模板通过使用托管标识来管理对 Azure 的身份验证。 第二个 Runbook 通常执行核心逻辑来自动执行给定方案，在本例中，执行身份验证 Runbook 模板。 它会将结果显示在测试输出窗格中。 在正常情况下，会使用此 Runbook 针对利用子 Runbook 输出的资源执行某些操作。

下面是 AuthenticateTo-Azure Runbook 的基本逻辑。
。

Runbook 包括输出类型 Microsoft.Azure.Commands.Profile.Models.PSAzureProfile，该输出类型返回身份验证配置文件属性。

尽管此运行手册操作非常简单，但此处仍需指出一个配置项。 最后一个活动执行 Write-Output cmdlet，使用一个针对Inputobject参数的PowerShell表达式将配置文件数据写入变量中。 此参数是 Write-Output 必需的。

本示例中名为 Test-ChildOutputType 的第二个 Runbook 仅定义两项活动。

第一个活动调用 AuthenticateTo-Azure Runbook。 第二个活动运行 Write-Verbose cmdlet，且将“数据源”设置为“活动输出”。 此外，“字段路径”被设置为 Context.Subscription.Name，这是从 AuthenticateTo-Azure 运行手册的上下文输出中得出的。

生成的输出是订阅名称。

处理消息流

与输出流不同，消息流向用户传递信息。 有多个消息流用于传递不同类型的信息，且 Azure 自动化以不同的方式处理每个流。

将输出写入到警告和错误流

警告和错误日志流记录运行手册中出现的问题。 执行 Runbook 时，Azure 自动化会将这些流写入作业历史记录。 在测试 Runbook 时，自动化包括 Azure 门户“测试输出”窗格中的数据流。

默认情况下，在出现警告或错误后，Runbook 将继续执行。 您可以指定在 Runbook 创建消息之前，通过在其中设置首选项变量，使其在出现警告或错误时暂停。 例如，要在出现错误时使运行手册（Runbook）暂停，就像出现异常时会暂停一样，请将 ErrorActionPreference 变量设置为 "Stop"。

使用 Write-Warning 或 Write-Error cmdlet 创建警告或错误消息。 活动还可以输出到警告流和错误流。

#The following lines create a warning message and then an error message that will suspend the runbook.

$ErrorActionPreference = "Stop"
Write-Warning -Message "This is a warning message."
Write-Error -Message "This is an error message that will stop the runbook because of the preference variable."

将输出写入到调试流

Azure 自动化为交互式用户提供调试消息流。 默认情况下，Azure 自动化不会捕获任何调试流数据，而只捕获输出、错误和警告数据。另外，如果将 runbook 配置为捕获详细数据，则也会捕获详细数据。

若要捕获调试流数据，需要在 runbook 中执行两项操作：

1. 设置变量 $GLOBAL:DebugPreference="Continue"，以便在遇到调试消息时指示 PowerShell 继续运行。 “$GLOBAL:”部分指示 PowerShell 在全局范围内执行此操作，而不是在执行语句时脚本所在的任何本地范围内这样做。

2. 将我们不会捕获的调试流重定向到我们会捕获的流，如输出。 此操作通过对要执行的语句设置 PowerShell 重定向来完成。 有关 PowerShell 重定向的详细信息，请参阅关于重定向。

例子

在此示例中，为了输出两个不同的流，我们使用 Write-Output 和 Write-Debug cmdlet 来配置 runbook。

Write-Output "This is an output message." 
Write-Debug "This is a debug message."

如果此 runbook 按原样执行，runbook 作业的输出窗格就会流式传输以下输出：

This is an output message.

在此示例中，runbook 的配置与前一个示例类似，不同之处是加入了 $GLOBAL:DebugPreference="Continue" 语句，并且在 5>&1 语句的结尾添加了 Write-Debug。

Write-Output "This is an output message." 
$GLOBAL:DebugPreference="Continue" 
Write-Debug "This is a debug message." 5>&1

如果执行此运行手册，运行手册作业的输出窗格将显示如下输出内容：

This is an output message.
This is a debug message.

出现这种情况的原因是，$GLOBAL:DebugPreference="Continue" 语句指示 PowerShell 显示调试消息，而在 5>&1 语句的结尾添加 Write-Debug 则会指示 PowerShell 将流 5（调试）重定向到流 1（输出）。

将输出写入到详细流

详细日志流支持有关 Runbook 操作的一般信息。 由于调试流不适用于 Runbook，因此 Runbook 应使用详细消息来传达调试信息。

默认情况下，出于性能原因，作业历史记录不会存储已发布 Runbook 的详细消息。 若要存储详细消息，请使用 Azure 门户的“配置”选项卡，并通过“日志详细记录”设置将已发布的运行手册配置为记录详细消息。 启用此选项的目的只是为了排查 Runbook 的问题或对它进行调试。 在大多数情况下，应该保留默认设置，即，不记录详细记录。

测试 runbook 时，即使已将该 runbook 配置为记录详细记录，详细消息也不会显示。 若要在测试 Runbook 时显示详细消息，必须将 VerbosePreference 变量设置为 Continue。 设置该变量后，Azure 门户的测试输出窗格中会显示详细消息。

以下代码使用 Write-Verbose cmdlet 创建详细消息。

#The following line creates a verbose message.

Write-Verbose -Message "This is a verbose message."

处理进度记录

你可以使用 Azure 门户的“配置”选项卡将 Runbook 配置为记录进度记录。 默认设置为不记录这些记录，以最大程度地提高性能。 在大多数情况下，应该保留默认设置。 启用此选项的目的只是为了排查 Runbook 的问题或对它进行调试。

如果启用进度记录日志，Runbook 会在每个活动运行前后向作业历史记录中写入一条记录。 测试 Runbook 不会显示进度消息，即使已将该 Runbook 配置为记录进度记录也是如此。

使用首选项变量

你可以在 runbook 中设置某些 Windows PowerShell 首选项变量，以控制发送到不同输出流的数据的响应。 下表列出了可在 Runbook 中使用的首选项变量及其默认值和有效值。 在 Azure 自动化之外的 Windows PowerShell 中使用时，首选项变量可以使用其他可用值。

下表列出了在 Runbook 中有效的首选项变量值的行为。

检索 Runbook 输出和消息

检索 Azure 门户中的运行手册输出和消息

可以在 Azure 门户中使用 Runbook 的“作业”选项卡查看 Runbook 作业的详细信息。 作业摘要显示输入参数和输出流，此外，还显示有关作业的一般信息以及发生的任何异常。 “作业历史记录”包括来自输出流以及警告和错误流的消息。 如果 runbook 已配置为记录详细日志和进度日志，其还包含来自详细日志以及进度日志的消息。

在 Windows PowerShell 中检索运行簿输出和消息

在 Windows PowerShell 中，可以使用 Get-AzAutomationJobOutput cmdlet 检索 Runbook 的输出和消息。 此 cmdlet 需要作业的 ID，还有一个名为 Stream 的参数（用于指定要检索的流）。 可以为此参数指定 Any 值，以检索作业的所有流。

以下示例将启动一个示例运行簿，然后等待该运行簿完成。 Runbook 执行完毕后，该脚本将从作业收集 Runbook 输出流。

$job = Start-AzAutomationRunbook -ResourceGroupName "ResourceGroup01" `
  -AutomationAccountName "MyAutomationAccount" -Name "Test-Runbook"

$doLoop = $true
While ($doLoop) {
  $job = Get-AzAutomationJob -ResourceGroupName "ResourceGroup01" `
    -AutomationAccountName "MyAutomationAccount" -Id $job.JobId
  $status = $job.Status
  $doLoop = (($status -ne "Completed") -and ($status -ne "Failed") -and ($status -ne "Suspended") -and ($status -ne "Stopped"))
}

Get-AzAutomationJobOutput -ResourceGroupName "ResourceGroup01" `
  -AutomationAccountName "MyAutomationAccount" -Id $job.JobId -Stream Output

# For more detailed job output, pipe the output of Get-AzAutomationJobOutput to Get-AzAutomationJobOutputRecord
Get-AzAutomationJobOutput -ResourceGroupName "ResourceGroup01" `
  -AutomationAccountName "MyAutomationAccount" -Id $job.JobId -Stream Any | Get-AzAutomationJobOutputRecord

检索图形化Runbook中的输出和消息

对于图形化运行手册，以活动级别追踪的形式提供了输出和消息的额外日志记录。 有两个级别的跟踪：基本和详细。 基本跟踪显示 runbook 中每个活动的开始和结束时间，以及与任何活动重试相关的信息。 一些示例是活动的尝试次数和开始时间。 详细跟踪包括基本跟踪功能以及每个活动的输入和输出数据日志记录。

当前活动级别跟踪使用详细日志流来写入记录。 因此，当启用跟踪时，必须启用详细日志记录。 对于启用了跟踪的图形 runbook，无需记录进度记录。 基本跟踪具有相同的目的，并提供了更多的信息。

从图像中可以看出，当启用图形 Runbook 的详细日志记录和跟踪时，“作业流”视图中会在生产环境中提供更多信息。 此额外信息对于使用操作手册排除生产问题可能至关重要。

但是，除非需要此信息来跟踪 Runbook 进度以进行故障排除，否则你可能想要按一般做法使跟踪保持关闭状态。 跟踪记录尤其多。 借助图形化 Runbook 跟踪，每个活动可以获取两到四条记录，具体数量取决于您配置的是基本跟踪还是详细跟踪。

若要启用活动级别跟踪：

1. 在 Azure 门户中，打开自动化帐户。

2. 在“流程自动化”下选择“Runbooks”以打开 Runbooks 列表。

3. 在“运行手册”页上，从运行手册列表中选择一个图形运行手册。

4. 在“设置”下，单击“日志记录和跟踪”。

5. 在“日志记录和跟踪”页面的“记录详细日志”下单击“启用”以激活详细日志记录。

6. 在“活动级别跟踪”下，根据所需的跟踪级别，将跟踪级别更改为“基本”或“详细”。
   

   

检索 Azure Monitor 日志中的 Runbook 输出与消息

Azure 自动化可将 Runbook 作业状态和作业流发送到 Log Analytics 工作区。 Azure Monitor 支持允许你执行以下操作的日志：

• 获取有关自动化任务的深入了解。
• 根据您的 Runbook 作业状态（例如失败或暂停），触发电子邮件或警报。
• 编写跨作业流的高级查询。
• 跨自动化帐户关联作业。
• 可视化作业历史记录。

若要详细了解如何配置与 Azure Monitor 日志的集成以收集、关联和处理作业数据，请参阅将作业状态和作业流从自动化转发到 Azure Monitor 日志。

后续步骤

• 有关示例查询，请参阅作业日志和作业流的示例查询
• 若要使用 Runbook，请参阅在 Azure 自动化中管理 Runbook。
• 如果不熟悉 PowerShell 脚本编写，请参阅 PowerShell 文档。
• 有关 Azure 自动化 PowerShell cmdlet 参考，请参阅 Az.Automation。
• 若要排查与 Runbook 输出和消息流相关的问题，请参阅 Runbook 问题疑难解答。