在运行手册中使用条件语句 - Amazon Systems Manager
使用 aws:branch 操作如何使用条件选项的示例
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

在运行手册中使用条件语句

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

  • aws:branch：此自动化操作让您能够创建一个动态自动化，该自动化可以在一个步骤中评估多个选项，然后根据评估结果跳转到运行手册中的不同步骤。

  • nextStep：此选项指定在成功完成一个步骤后，接下来处理自动化中的哪个步骤。

  • isEnd：此选项在特定步骤结束时停止自动化。该选项的默认值为 false。

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

  • onFailure：此选项指示自动化在失败时是应中止、继续还是转到其他步骤。该选项的默认值为 abort。

下一节介绍 aws:branch 自动化操作。有关 nextStep、isEnd、isCritical 和 onFailure 选项的更多信息，请参阅 示例 aws:branch 运行手册。

使用 aws:branch 操作

aws:branch 操作提供适用于自动化的大部分动态条件分支选项。如前所述，此操作让自动化能够在一个步骤中评估多个条件，然后根据评估结果跳转到新的步骤。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。自动化可以根据在运行手册的 Parameters 部分中指定的参数值来评估 Choices。自动化也可以基于上一步的输出来评估 Choices。

自动化使用布尔表达式评估每个选择。如果评估确定第一个选择为 true，自动化跳转到为该选择指定的步骤。如果评估确定第一个选择为 false，自动化程评估下一个选择。如果您的步骤包含三个或更多的 Choices，自动化按顺序评估每个选择，直到某个选择的评估结果为 true。然后，自动化跳转到为结果为 true 的选择指定的步骤。

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

以下是 YAML 的 aws:branch 步骤，命名为 chooseOSfromParameter。此步骤包含两个 Choices：(NextStep: runWindowsCommand) 和 (NextStep: runLinuxCommand)。自动化评估这些 Choices，以确定应为适当的操作系统运行哪个命令。每个选择的 Variable 都使用 {{OSName}}，这是运行手册作者在运行手册的 Parameters 部分中定义的参数。

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

以下是 YAML 的 aws:branch 步骤，命名为 chooseOSfromOutput。此步骤包含两个 Choices：(NextStep: runPowerShellCommand) 和 (NextStep: runShellCommand)。自动化评估这些 Choices，以确定应为适当的操作系统运行哪个命令。每个选择的 Variable 都使用 {{GetInstance.platform}}，这是文档中上一步的输出。此示例还包含一个名为 Default 的选项。如果自动化评估两个的结果都为 Choices，而且两个选择均为 true，自动化跳转到名为 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

在运行手册中创建 aws:branch 步骤

在运行手册中创建 aws:branch 步骤时，请定义自动化应对其进行评估的 Choices 以确定自动化应跳转到哪个步骤。如前所述，Choices 使用布尔表达式进行评估。每个选择都必须定义以下选项：

  • NextStep：当指定的选择为 true 时，运行手册要处理的下一个步骤。

  • 变量：指定在运行手册的 Parameters 部分中定义的参数的名称（在 Variables 部分中定义的参数），或指定上一步的输出对象。

    使用以下格式指定变量值。

    Variable: "{{variable name}}"

    使用以下格式指定参数值。

    Variable: "{{parameter name}}"

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

    Variable: "{{previousStepName.outputName}}"

    注意

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

  • Operation：用于评估选择的标准，例如 StringEquals: Linux。aws:branch 操作支持以下运算：

    字符串运算

    • 字符串等于

    • EqualsIgnoreCase

    • StartsWith

    • EndsWith

    • 包含

    数值运算

    • NumericEquals

    • NumericGreater

    • NumericLesser

    • NumericGreaterOrEquals

    • NumericLesser

    • NumericLesserOrEquals

    布尔运算

    • BooleanEquals

    重要

    创建运行手册时，系统将验证运行手册中的每个操作。在尝试创建运行手册时，如果某个操作不受支持，系统会返回错误。

  • Default：指定当所有 Choices 都为 true 时自动化应跳转到的回退步骤。

    注意

    如果不想指定 Default 值，则可以指定 isEnd 选项。如果所有 Choices 都为 true 并且未指定 Default 值，自动化在此步骤结束时停止。

使用以下模板可以帮助您在运行手册中构建 aws:branch 步骤：将每个示例资源占位符替换为您自己的信息。

YAML
mainSteps:
- name: step name
  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 for this choice is 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 for this choice is 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.outputName}}"

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

mainSteps:
- Name: GetInstance
  action: aws:executeAwsApi
  inputs:
    Service: ssm
    Api: DescribeInstanceInformation
    Filters:
    - Key: InstanceIds
      Values: ["{{ InstanceId }}"]
  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

这是一个示例，展示了从上一步和输出创建 "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 运行手册

下面是一些使用 aws:branch 的示例运行手册。

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

在此示例的第一步（GetInstance）中，运行手册作者使用 aws:executeAwsApi 操作来调用 ssm DescribeInstanceInformation API 操作。作者使用此操作确定实例使用的操作系统的类型。aws:executeAwsApi 操作输出实例 ID 和平台类型。

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

---
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}}") 中指定的参数选项。当用户运行此自动化时，他们在运行时为 OperatingSystemName 指定值。自动化在 Choices 评估期间使用运行时参数。自动化基于为 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 步骤中使用 And、Or 和 Not 运算符来创建复杂的分支自动化。

“And”运算符

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

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 和 Amazon Lambda 步骤的输出是不是真。如果任意一个变量的评估结果都为真，自动化跳转到 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，自动化跳转到 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:
    - "{{instanceIds}}"
    DocumentName: AWS-RunPowerShellScript
    Parameters:
      commands:
      - msiexec /i {{packageName}}
- name: TestInstall
  action: aws:invokeLambdaFunction
  maxAttempts: 1
  timeoutSeconds: 500
  inputs:
    FunctionName: TestLambdaFunction
...

使用 onFailure 选项创建跳转到不同步骤的动态自动化

下面的示例使用 onFailure: step:step name、nextStep 和 isEnd 选项创建一个动态自动化。在此示例中，如果 InstallMsiPackage 操作失败，自动化将跳转到名为 PostFailure (onFailure: step:PostFailure) 的操作以运行 Amazon Lambda 函数，从而在安装失败时执行某个操作。如果安装成功，自动化将跳转到 TestInstall 操作 (nextStep: TestInstall)。TestInstall 和 PostFailure 步骤都使用 isEnd 选项 (isEnd: true)，以便自动化在任一步骤完成时结束。

注意

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

示例 2：跳转到不同步骤的动态自动化

mainSteps
- name: InstallMsiPackage
  action: aws:runCommand
  onFailure: step:PostFailure
  maxAttempts: 2
  inputs:
    InstanceIds:
    - "{{instanceIds}}"
    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
...
注意

在处理运行手册之前，系统将验证运行手册不会创建无限循环。如果检测到无限循环，自动化将返回一个错误和一个显示哪些步骤创建循环的循环跟踪。

创建定义关键步骤的动态自动化

您可以指定一个对于自动化的整体成功很重要的步骤。如果关键步骤失败，自动化会将自动化状态报告为 Failed，即使已成功运行一个或多个步骤也是如此。在以下示例中，用户在 InstallMsiPackage 步骤失败 (onFailure: step:VerifyDependencies) 时标识 VerifyDependencies 步骤。用户指定 InstallMsiPackage 步骤为非关键步骤 (isCritical: false)。在此示例中，如果应用程序安装失败，自动化处理 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
...