• AWS Systems Manager CloudWatch 控制面板在 2026 年 4 月 30 日之后将不再可用。客户可以像现在一样继续使用 Amazon CloudWatch 控制台来查看、创建和管理其 Amazon CloudWatch 控制面板。有关更多信息，请参阅 [Amazon CloudWatch 控制面板文档](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)。
# 在运行手册中使用条件语句
默认情况下，在运行手册的 `mainSteps` 部分中定义的步骤将按先后顺序运行。在一个操作完成后，`mainSteps` 部分中指定的下一个操作将开始。此外，如果一个操作无法运行，则整个自动化将失败（默认情况下）。可以使用本节所述的 `aws:branch` 自动化操作和运行手册选项来创建执行*条件分支*的自动化。也就是说，您可以创建在评估不同选项后跳转到不同步骤或在某个步骤完成时动态响应更改的自动化。以下是可用于创建动态自动化的选项的列表：
+ **`aws:branch`**：此自动化操作让您能够创建一个动态自动化，该自动化可以在一个步骤中评估多个选项，然后根据评估结果跳转到运行手册中的不同步骤。
+ **`nextStep`**：此选项指定在成功完成一个步骤后，接下来处理自动化中的哪个步骤。
+ **`isEnd`**：此选项在特定步骤结束时停止自动化。该选项的默认值为 false。
+ **`isCritical`**：此选项将一个步骤指定为成功完成自动化的关键步骤。如果具有此分派的步骤失败，自动化会将自动化的最终状态报告为 `Failed`。该选项的默认值为 `true`。
+ **`onFailure`**：此选项指示自动化在失败时是应中止、继续还是转到其他步骤。该选项的默认值为 abort。
下一节介绍 `aws:branch` 自动化操作。有关 `nextStep`、`isEnd`、`isCritical` 和 `onFailure` 选项的更多信息，请参阅 [示例 `aws:branch` 运行手册](#branch-runbook-examples)。
## 使用 `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}}"`
**注意**
下一节[关于创建输出变量](#branch-action-output)更详细地介绍如何创建输出变量。
+ **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": "\$1\$1 describeInstance.Platform \$1\$1"* 的方法。
```
- 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` 和 AWS 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`) 的操作以运行 AWS 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
...
```