AWS Systems Manager
用户指南
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

使用条件分支创建动态 Automation 工作流程

默认情况下,在 Automation 文档的 mainSteps 部分中定义的步骤将按先后顺序运行。在一个操作完成后,mainSteps 部分中指定的下一个操作将开始。此外,如果一个操作无法运行,则整个自动化工作流程将失败(默认情况下)。您可以使用本节所述的 aws:branch Automation 操作和 Automation 文档选项来创建执行条件分支 的 Automation 工作流程。也就是说,您可以创建在评估不同选项后跳转到不同步骤或在某个步骤完成时动态响应更改的 Automation 工作流程。以下是可用于创建动态 Automation 工作流程的选项的列表:

  • aws:branch:此 Automation 操作让您能够创建一个动态 Automation 工作流程,该流程可以在一个步骤中评估多个选项,然后根据评估结果跳转到 Automation 文档中的不同步骤。

  • nextStep:此选项指定在成功完成一个步骤后,接下来处理 Automation 工作流程中的哪个步骤。

  • isEnd:此选项在特定步骤结束时停止 Automation 执行。该选项的默认值为 false。

  • isCritical:此选项将一个步骤指定为成功完成 Automation 的关键步骤。如果具有此分派的步骤失败,则自动化会将自动化的最终状态报告为失败。该选项的默认值为 true。

  • onFailure:此选项指示工作流程在失败时是应中止、继续还是转到其他步骤。该选项的默认值为“中止”。

下一节介绍 aws:branch Automation 操作。有关 nextStepisEndisCriticalonFailure 工作流程选项的更多信息,请参阅如何使用动态工作流程选项的示例

使用 aws:branch 操作

aws:branch 操作提供适用于 Automation 工作流程的大部分动态条件分支选项。如前所述,此操作让 Automation 工作流程能够在一个步骤中评估多个条件,然后根据评估结果跳转到新的步骤。aws:branch 操作的功能类似于编程中的 IF-ELIF-ELSE 语句。

下面是一个 aws:branch 步骤的 YAML 示例:

- name: ChooseOSforCommands action: aws:branch inputs: Choices: - NextStep: runPowerShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Windows - NextStep: runShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Linux Default: PostProcessing

在为步骤指定 aws:branch 操作时,请指定工作流程必须评估的 Choices。工作流程可以根据在 Automation 文档的 Parameters 部分中指定的参数值来评估 Choices。工作流程也可以基于上一步的输出来评估 Choices

Automation 工作流程使用布尔表达式评估每个选择。如果评估确定第一个选择为真,则工作流程跳转到为该选择指定的步骤。如果评估确定第一个选择为假,则工作流程评估下一个选择。如果您的步骤包含三个或更多的 Choices,则工作流程按顺序评估每个选择,直到某个选择的评估结果为真。然后,工作流程跳转到为结果为真的选择指定的步骤。

如果所有 Choices 都为假,则工作流程检查该步骤是否包含 Default 值。Default 值定义当所有选择都为假时工作流程应跳转到的步骤。如果没有为该步骤指定 Default 值,则 Automation 工作流程处理文档中的下一个步骤。

下面是一个名为 chooseOSfromParameter 的 YAML 中的 aws:branch 步骤。此步骤包含两个 Choices:(NextStep: runWindowsCommand) 和 (NextStep: runLinuxCommand)。Automation 工作流程评估这些 Choices,以确定应为适当的操作系统运行哪个命令。每个选择的 Variable 都使用 {{OSName}} - 这是文档作者在文档的 Parameters 部分中定义的参数。

mainSteps: - name: chooseOSfromParameter action: aws:branch inputs: Choices: - NextStep: runWindowsCommand Variable: "{{OSName}}" StringEquals: Windows - NextStep: runLinuxCommand Variable: "{{OSName}}" StringEquals: Linux

下面是一个名为 chooseOSfromOutput 的 YAML 中的 aws:branch 步骤。此步骤包含两个 Choices:(NextStep: runPowerShellCommand) 和 (NextStep: runShellCommand)。Automation 工作流程评估这些 Choices,以确定应为适当的操作系统运行哪个命令。每个选择的 Variable 都使用 {{GetInstance.platform}} - 这是文档中上一步的输出。此示例还包含一个名为 Default 的选项。如果工作流程评估两个 Choices 后的结果都为假,则 Automation 工作流程跳转到名为 PostProcessing 的步骤。

mainSteps: - name: chooseOSfromOutput action: aws:branch inputs: Choices: - NextStep: runPowerShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Windows - NextStep: runShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Linux Default: PostProcessing

在 Automation 文档中创建 aws:branch 步骤

在 Automation 文档中创建 aws:branch 步骤时,请定义工作流程应对其进行评估以确定工作流程应跳转到哪个步骤的 Choices。如前所述,Choices 使用布尔表达式进行评估。每个选择都必须定义以下选项:

  • NextStep:当指定的选择为真时,Automation 文档要处理的下一个步骤。

  • Variable:指定在 Automation 文档的 Parameters 部分中定义的参数的名称,或指定 Automation 文档中上一步的输出对象。

    使用以下格式指定参数变量:

    Variable: "{{name_of_parameter}}"

    使用以下格式指定输出对象变量:

    Variable: "{{previousStepName.outputFieldName}}"

    注意

    下一节关于创建输出变量更详细地介绍如何创建输出变量。

  • Operation:用于评估选择的标准,例如 StringEquals: Linuxaws:branch 操作支持以下运算:

    字符串运算

    • 字符串等于

    • EqualsIgnoreCase

    • StartsWith

    • EndsWith

    • 包含

    数值运算

    • NumericEquals

    • NumericGreater

    • NumericLesser

    • NumericGreaterOrEquals

    • NumericLesser

    • NumericLesserOrEquals

    布尔运算

    • BooleanEquals

    重要

    创建 Automation 文档时,系统将验证文档中的每个操作。在尝试创建文档时,如果某个操作不受支持,系统会返回错误。

  • Default:指定当所有 Choices 都为假时工作流程应跳转到的回退步骤。

    注意

    如果不想指定 Default 值,则可以指定 isEnd 工作流程选项。如果所有 Choices 都为假并且未指定 Default 值,则 Automation 工作流程在此步骤结束时停止。

使用以下模板可以帮助您在 Automation 文档中构建 aws:branch 步骤:

YAML 模板

mainSteps: - name: a name for the step action: aws:branch inputs: Choices: - NextStep: step to jump to if evaluation for this choice is true Variable: "{{parameter name or output from previous step}}" Operation type: Operation value - NextStep: step to jump to if evaluation = true Variable: "{{parameter name or output from previous step}}" Operation type: Operation value Default: step to jump to if all choices are false

JSON 模板

{ "mainSteps":[ { "name":"a name for the step", "action":"aws:branch", "inputs":{ "Choices":[ { "NextStep":"step to jump to if evaluation for this choice is true", "Variable":"{{parameter name or output from previous step}}", "Operation type":"Operation value" }, { "NextStep":"step to jump to if evaluation = true", "Variable":"{{parameter name or output from previous step}}", "Operation type":"Operation value" } ], "Default":"step to jump to if all choices are false" } } ] }

关于创建输出变量

要创建引用上一步输出的 aws:branch 选择,您需要标识上一步的名称和输出字段的名称。然后,使用以下格式组合步骤和字段的名称:

Variable: "{{previousStepName.outputFieldName}}"

例如,下面的第一个步骤名为 GetInstance。然后,在 outputs 下,有一个名为 platform 的字段。在第二个步骤 (ChooseOSforCommands) 中,作者希望将平台字段的输出引用为变量。要创建变量,只需将步骤名称 (GetInstance) 与输出字段名称 (platform) 组合在一起即可创建 Variable: "{{GetInstance.platform}}"

mainSteps: - Name: GetInstance action: aws:executeAwsApi inputs: Service: ssm Api: DescribeInstanceInformation outputs: - Name: myInstance Selector: "$.InstanceInformationList[0].InstanceId" Type: String - Name: platform Selector: "$.InstanceInformationList[0].PlatformType" Type: String - name: ChooseOSforCommands action: aws:branch inputs: Choices: - NextStep: runPowerShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Windows - NextStep: runShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Linux Default: Sleep

下面的 JSON 示例介绍如何从上一个步骤 ("describeInstance") 和输出字段 ("Platform") 创建 "Variable": "{{ describeInstance.Platform }}"

{ "name": "describeInstance", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "DescribeInstances", "InstanceIds": [ "{{ InstanceId }}" ] }, "outputs": [ { "Name": "Platform", "Selector": "$.Reservations[0].Instances[0].Platform", "Type": "String" } ], "nextStep": "branchOnInstancePlatform" }, { "name": "branchOnInstancePlatform", "action": "aws:branch", "inputs": { "Choices": [ { "NextStep": "runEC2RescueForWindows", "Variable": "{{ describeInstance.Platform }}", "StringEquals": "windows" } ], "Default": "runEC2RescueForLinux" } }

示例 aws:branch Automation 文档

下面是一些使用 aws:branch 的示例 Automation 文档。

示例 1:使用 aws:branch 和输出变量基于操作系统类型运行命令

在此示例的第一个步骤 (GetInstance) 中,文档作者使用 aws:executeAwsApi 操作来调用 ssm DescribeInstanceInformation API 操作。作者使用此操作确定实例使用的操作系统的类型。aws:executeAwsApi 操作输出实例 ID 和平台类型。

在第二个步骤 (ChooseOSforCommands) 中,作者使用了 aws:branch 操作和两个 Choices:(NextStep: runPowerShellCommand) 和 (NextStep: runShellCommand)。Automation 工作流程使用上一步 (Variable: "{{GetInstance.platform}}") 的输出评估实例的操作系统。Automation 工作流程跳转到指定操作系统的步骤。

--- schemaVersion: '0.3' assumeRole: "{{AutomationAssumeRole}}" parameters: AutomationAssumeRole: default: "" type: String mainSteps: - name: GetInstance action: aws:executeAwsApi inputs: Service: ssm Api: DescribeInstanceInformation outputs: - Name: myInstance Selector: "$.InstanceInformationList[0].InstanceId" Type: String - Name: platform Selector: "$.InstanceInformationList[0].PlatformType" Type: String - name: ChooseOSforCommands action: aws:branch inputs: Choices: - NextStep: runPowerShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Windows - NextStep: runShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Linux Default: Sleep - name: runShellCommand action: aws:runCommand inputs: DocumentName: AWS-RunShellScript InstanceIds: - "{{GetInstance.myInstance}}" Parameters: commands: - ls isEnd: true - name: runPowerShellCommand action: aws:runCommand inputs: DocumentName: AWS-RunPowerShellScript InstanceIds: - "{{GetInstance.myInstance}}" Parameters: commands: - ls isEnd: true - name: Sleep action: aws:sleep inputs: Duration: PT3S

示例 2:使用 aws:branch 和参数变量基于操作系统类型运行命令

文档作者在 parameters 部分的文档开头定义了几个参数选项。一个参数名为 OperatingSystemName。在第一个步骤 (ChooseOS) 中,作者使用了 aws:branch 操作和两个 Choices:(NextStep: runWindowsCommand) 和 (NextStep: runLinuxCommand)。这些 Choices 的变量引用在参数部分 (Variable: "{{OperatingSystemName}}") 中指定的参数选项。当用户运行此 Automation 工作流程时,他们在运行时为 OperatingSystemName 指定值。Automation 工作流程在 Choices 评估期间使用运行时参数。Automation 工作流程基于为 OperatingSystemName 指定的运行时参数跳转到指定操作系统的步骤。

--- schemaVersion: '0.3' assumeRole: "{{AutomationAssumeRole}}" parameters: AutomationAssumeRole: default: "" type: String OperatingSystemName: type: String LinuxInstanceId: type: String WindowsInstanceId: type: String mainSteps: - name: ChooseOS action: aws:branch inputs: Choices: - NextStep: runWindowsCommand Variable: "{{OperatingSystemName}}" StringEquals: windows - NextStep: runLinuxCommand Variable: "{{OperatingSystemName}}" StringEquals: linux Default: Sleep - name: runLinuxCommand action: aws:runCommand inputs: DocumentName: "AWS-RunShellScript" InstanceIds: - "{{LinuxInstanceId}}" Parameters: commands: - ls isEnd: true - name: runWindowsCommand action: aws:runCommand inputs: DocumentName: "AWS-RunPowerShellScript" InstanceIds: - "{{WindowsInstanceId}}" Parameters: commands: - date isEnd: true - name: Sleep action: aws:sleep inputs: Duration: PT3S

使用运算符创建复杂的分支文档

您可以在 aws:branch 步骤中使用 AndOrNot 运算符来创建复杂的分支文档。

“And”运算符

如果某个选择的多个变量需要为真,可以使用 And 运算符。在下面的示例中,第一个选择评估实例是否 running 并且使用的是 Windows 操作系统。如果这两个 变量的评估结果都为真,则 Automation 工作流程跳转到 runPowerShellCommand 步骤。如果一个或多个变量为假,则工作流程评估第二个选择的变量。

mainSteps: - name: switch2 action: aws:branch inputs: Choices: - And: - Variable: "{{GetInstance.pingStatus}}" StringEquals: running - Variable: "{{GetInstance.platform}}" StringEquals: Windows NextStep: runPowerShellCommand - And: - Variable: "{{GetInstance.pingStatus}}" StringEquals: running - Variable: "{{GetInstance.platform}}" StringEquals: Linux NextStep: runShellCommand Default: sleep3

“Or”运算符

如果某个选择的任意 变量需要为真,可以使用 Or 运算符。在下面的示例中,第一个选择评估参数字符串是不是 Windows 和 AWS Lambda 步骤的输出是不是真。如果任意一个 变量的评估结果都为真,则 Automation 工作流程跳转到 RunPowerShellCommand 步骤。如果两个变量都为假,则工作流程评估第二个选择的变量。

- Or: - Variable: "{{parameter1}}" StringEquals: Windows - Variable: "{{BooleanParam1}}" BooleanEquals: true NextStep: RunPowershellCommand - Or: - Variable: "{{parameter2}}" StringEquals: Linux - Variable: "{{BooleanParam2}}" BooleanEquals: true NextStep: RunShellScript

“Not”运算符

如果需要在某个变量为 时跳转到定义的步骤,可以使用 Not 运算符。在下面的示例中,第一个选择评估参数字符串是不是 Not Linux。如果变量的评估结果不为 Linux,则 Automation 工作流程跳转到 sleep2 步骤。如果第一个选择的评估结果 Linux,则工作流程评估下一个选择。

mainSteps: - name: switch action: aws:branch inputs: Choices: - NextStep: sleep2 Not: Variable: "{{testParam}}" StringEquals: Linux - NextStep: sleep1 Variable: "{{testParam}}" StringEquals: Windows Default: sleep3

如何使用动态工作流程选项的示例

本部分包括有关如何使用自动化文档中的动态工作流程选项的其他示例。本部分中的每个示例均扩展以下自动化文档。此文档包含两个操作。第一个操作名为 InstallMsiPackage。它使用 aws:runCommand 操作将应用程序安装到 Windows Server 实例上。第二个操作名为 TestInstall。它使用 aws:invokeLambdaFunction 操作在成功安装应用程序后测试该应用程序。步骤 1 指定 onFailure: Abort。这意味着,如果应用程序未成功安装,则自动化工作流程执行会在进入步骤 2 前停止。

示例 1:带两个线性操作的自动化文档

--- schemaVersion: '0.3' description: Install MSI package and run validation. assumeRole: "{{automationAssumeRole}}" parameters: automationAssumeRole: type: String description: "(Required) Assume role." packageName: type: String description: "(Required) MSI package to be installed." instanceIds: type: String description: "(Required) Comma separated list of instances." mainSteps: - name: InstallMsiPackage action: aws:runCommand maxAttempts: 2 onFailure: Abort inputs: InstanceIds: - i-02573cafcfEXAMPLE - i-0471e04240EXAMPLE - i-07782c72faEXAMPLE DocumentName: AWS-RunPowerShellScript Parameters: commands: - msiexec /i {{packageName}} - name: TestInstall action: aws:invokeLambdaFunction maxAttempts: 1 timeoutSeconds: 500 inputs: FunctionName: TestLambdaFunction ...

使用 onFailure 选项创建跳转到不同步骤的动态工作流程

下面的示例使用 onFailure: step:step_namenextStepisEnd 选项创建一个动态 Automation 工作流程。在此示例中,如果 InstallMsiPackage 操作失败,则工作流程将跳转到名为 PostFailure (onFailure: step:PostFailure) 的操作以运行 AWS Lambda 函数,从而在安装失败时执行某个操作。如果安装成功,则工作流程进程将跳转到 TestInstall 操作 (nextStep: TestInstall)。TestInstallPostFailure 步骤都使用 isEnd 选项 (isEnd: true),以便工作流程在任一步骤完成时完成工作流程执行。

注意

可以选择在 mainSteps 部分的最后一步中使用 isEnd 选项。如果最后一个步骤未跳转到其他步骤,则自动化工作流程会在最后一步中运行操作后停止。

示例 2:跳转到不同步骤的动态工作流程

mainSteps - name: InstallMsiPackage action: aws:runCommand onFailure: step:PostFailure maxAttempts: 2 inputs: InstanceIds: - i-02573cafcfEXAMPLE - i-0471e04240EXAMPLE DocumentName: AWS-RunPowerShellScript Parameters: commands: - msiexec /i {{packageName}} nextStep: TestInstall - name: TestInstall action: aws:invokeLambdaFunction maxAttempts: 1 timeoutSeconds: 500 inputs: FunctionName: TestLambdaFunction isEnd: true - name: PostFailure action: aws:invokeLambdaFunction maxAttempts: 1 timeoutSeconds: 500 inputs: FunctionName: PostFailureRecoveryLambdaFunction isEnd: true ...

注意

在处理自动化文档时,系统将确认文档不会创建无限循环。如果检测到无限循环,则自动化将返回一个错误和一个显示哪些步骤创建循环的循环跟踪。

创建定义关键步骤的动态工作流程

您可以指定一个对于自动化工作流程的整体成功很重要的步骤。如果关键步骤失败,则 Automation 会将执行状态报告为失败,即使已成功运行一个或多个步骤也是如此。在以下示例中,用户在 InstallMsiPackage 步骤失败 (onFailure: step:VerifyDependencies) 时标识 VerifyDependencies 步骤。用户指定 InstallMsiPackage 步骤为非关键步骤 (isCritical: false)。在此示例中,如果应用程序安装失败,Automation 处理 VerifyDependencies 步骤以确定是否因一个或多个依赖项缺失而导致应用程序安装失败。

示例 3:定义自动化工作流程的关键步骤

--- name: InstallMsiPackage action: aws:runCommand onFailure: step:VerifyDependencies isCritical: false maxAttempts: 2 inputs: InstanceIds: - "{{instanceIds}}" DocumentName: AWS-RunPowerShellScript Parameters: commands: - msiexec /i {{packageName}} nextStep: TestPackage ...