• AWS Systems Manager CloudWatch 控制面板在 2026 年 4 月 30 日之后将不再可用。客户可以像现在一样继续使用 Amazon CloudWatch 控制台来查看、创建和管理其 Amazon CloudWatch 控制面板。有关更多信息，请参阅 [Amazon CloudWatch 控制面板文档](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)。

# 使用操作输出作为输入
<a name="automation-action-outputs-inputs"></a>

多个自动化操作会返回预定义的输出。您可以使用格式 `{{stepName.outputName}}` 将这些输出作为输入传递到运行手册的后续步骤。您还可以在运行手册中为自动化操作定义自定义输出。让您可以运行脚本，或调用其他 AWS 服务 的 API 操作一次，以便您在后续操作中重复使用这些值作为输入。运行手册中的参数类型是静态的。这意味着参数类型在定义后无法更改。要定义步骤输出，请提供以下字段：
+ 名称：（必需）输出名称，用于在后续步骤中引用输出值。
+ 选择器：（必需）用于确定输出值的 JSONPath 表达式。
+ 类型：（可选）选择器字段返回的值的数据类型。有效的类型值为 `String`、`Integer`、`Boolean`、`StringList`、`StringMap`、`MapList`。默认值为 `String`。

如果输出的值与您指定的数据类型不匹配，自动化会尝试转换该数据类型。例如，如果返回的值是 `Integer`，但指定的 `Type` 是 `String`，则最终输出值为 `String` 值。支持以下类型转换：
+ `String` 值可以转换为 `StringList`、`Integer` 和 `Boolean`。
+ `Integer` 值可以转换为 `String` 和 `StringList`。
+ `Boolean` 值可以转换为 `String` 和 `StringList`。
+ 包含一个元素的 `StringList`、`IntegerList` 或 `BooleanList` 值可以转换为 `String`、`Integer` 或 `Boolean`。

将参数或输出与自动化操作一起使用时，不能在操作的输入中动态更改数据类型。

这份示例运行手册演示了如何定义操作输出，并将该值引用为后续操作的输入。运行手册执行以下操作：
+ 使用 `aws:executeAwsApi` 操作调用 Amazon EC2 DescribeImages API 操作来获取特定 Windows Server 2016 AMI 的名称。它将映像 ID 输出为 `ImageId`。
+ 使用 `aws:executeAwsApi` 操作调用 Amazon EC2 RunInstances API 操作来启动一个实例，它使用上一步中的 `ImageId`。它将实例 ID 输出为 `InstanceId`。
+ 使用 ` aws:waitForAwsResourceProperty` 操作轮询 Amazon EC2 DescribeInstanceStatus API 操作来等待实例进入 `running` 状态。此操作的超时时间为 60 秒。如果实例在轮询 60 秒后未能进入 `running` 状态，则此步骤超时。
+ 使用 `aws:assertAwsResourceProperty` 操作调用 Amazon EC2 `DescribeInstanceStatus` API 操作来断言实例处于 `running` 状态。如果实例状态不为 `running`，则此步骤失败。

```
---
description: Sample runbook using AWS API operations
schemaVersion: '0.3'
assumeRole: "{{ AutomationAssumeRole }}"
parameters:
  AutomationAssumeRole:
    type: String
    description: "(Optional) The ARN of the role that allows Automation to perform the actions on your behalf."
    default: ''
  ImageName:
    type: String
    description: "(Optional) Image Name to launch EC2 instance with."
    default: "Windows_Server-2022-English-Full-Base*"
mainSteps:
- name: getImageId
  action: aws:executeAwsApi
  inputs:
    Service: ec2
    Api: DescribeImages
    Filters:  
    - Name: "name"
      Values: 
      - "{{ ImageName }}"
  outputs:
  - Name: ImageId
    Selector: "$.Images[0].ImageId"
    Type: "String"
- name: launchOneInstance
  action: aws:executeAwsApi
  inputs:
    Service: ec2
    Api: RunInstances
    ImageId: "{{ getImageId.ImageId }}"
    MaxCount: 1
    MinCount: 1
  outputs:
  - Name: InstanceId
    Selector: "$.Instances[0].InstanceId"
    Type: "String"
- name: waitUntilInstanceStateRunning
  action: aws:waitForAwsResourceProperty
  timeoutSeconds: 60
  inputs:
    Service: ec2
    Api: DescribeInstanceStatus
    InstanceIds:
    - "{{ launchOneInstance.InstanceId }}"
    PropertySelector: "$.InstanceStatuses[0].InstanceState.Name"
    DesiredValues:
    - running
- name: assertInstanceStateRunning
  action: aws:assertAwsResourceProperty
  inputs:
    Service: ec2
    Api: DescribeInstanceStatus
    InstanceIds:
    - "{{ launchOneInstance.InstanceId }}"
    PropertySelector: "$.InstanceStatuses[0].InstanceState.Name"
    DesiredValues:
    - running
outputs:
- "launchOneInstance.InstanceId"
...
```

前面介绍的每个自动化操作都允许您通过指定服务命名空间、API 操作名称、输入参数和输出参数来调用特定的 API 操作。输入由您选择的 API 操作定义。您可以在以下[服务参考](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/index.html)页面的左侧导航栏中选择服务来查看 API 操作（也称为方法）。在要调用的服务的**客户端**部分中选择一种方法。例如，以下页面中列出了 Amazon Relational Database Service (Amazon RDS) 的所有 API 操作（方法）：[Amazon RDS 方法](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html)。

您可以在以下位置查看每个自动化操作的架构：
+ [`aws:assertAwsResourceProperty` - 断言 AWS 资源状态或事件状态](automation-action-assertAwsResourceProperty.md)
+ [`aws:executeAwsApi` - 调用并运行 AWS API 操作](automation-action-executeAwsApi.md)
+ [`aws:waitForAwsResourceProperty` - 等待 AWS 资源属性](automation-action-waitForAwsResourceProperty.md)

架构包括使用每个操作所需字段的描述。

**使用 Selector/PropertySelector 字段**  
每个自动化操作都要求您指定一个输出 `Selector`（用于 `aws:executeAwsApi`）或 `PropertySelector`（用于 `aws:assertAwsResourceProperty` 和 `aws:waitForAwsResourceProperty`)。这些字段用于处理 AWS API 操作的 JSON 响应。这些字段使用 JSONPath 语法。

以下是帮助说明这一概念的 `aws:executeAwsAPi` 操作的示例：

```
---
mainSteps:
- name: getImageId
  action: aws:executeAwsApi
  inputs:
    Service: ec2
    Api: DescribeImages
    Filters:  
      - Name: "name"
        Values: 
          - "{{ ImageName }}"
  outputs:
    - Name: ImageId
      Selector: "$.Images[0].ImageId"
      Type: "String"
...
```

在 `aws:executeAwsApi` 步骤 `getImageId` 中，自动化将调用 `DescribeImages` API 操作并接收来自 `ec2` 的响应。然后，自动化将 `Selector - "$.Images[0].ImageId"` 应用于 API 响应，并将所选值分配给输出 `ImageId` 变量。通过指定 `"{{ getImageId.ImageId }}"`，同一自动化中的其他步骤可以使用 `ImageId` 的值。

以下是帮助说明这一概念的 `aws:waitForAwsResourceProperty` 操作的示例：

```
---
- name: waitUntilInstanceStateRunning
  action: aws:waitForAwsResourceProperty
  # timeout is strongly encouraged for action - aws:waitForAwsResourceProperty
  timeoutSeconds: 60
  inputs:
    Service: ec2
    Api: DescribeInstanceStatus
    InstanceIds:
    - "{{ launchOneInstance.InstanceId }}"
    PropertySelector: "$.InstanceStatuses[0].InstanceState.Name"
    DesiredValues:
    - running
...
```

在 `aws:waitForAwsResourceProperty` 步骤 `waitUntilInstanceStateRunning` 中，自动化将调用 `DescribeInstanceStatus` API 操作并接收来自 `ec2` 的响应。然后，自动化将 `PropertySelector - "$.InstanceStatuses[0].InstanceState.Name"` 应用于响应，并检查指定的返回值是否与 `DesiredValues` 列表中的值匹配（在本例中为 `running`）。此步骤重复这一过程，直到响应返回 `running` 实例状态。

## 在运行手册中使用 JSONPath
<a name="automation-action-json-path"></a>

JSONPath 表达式是以“\$1”开头的字符串。用于选择 JSON 元素中的一个或多个组件。下面的列表包含有关 Systems Manager 自动化支持的 JSONPath 运算符的信息：
+ **点表示的子字段 (.)**：用于 JSON 对象。此运算符选择特定键的值。
+ **深层扫描 (..)**：用于 JSON 元素。此运算符逐级扫描 JSON 元素，并使用特定键选择值列表。此运算符的返回类型始终为 JSON 数组。在自动化步骤输出类型上下文中，运算符可以是 StringList 或 MapList。
+ **数组索引 ([ ])**：用于 JSON 数组。此运算符获取特定索引的值。
+ **筛选条件 ([?(*expression*)])**：与 JSON 数组一起使用。此运算符筛选条件 JSON 数组值与筛选条件表达式中定义的标准相匹配。筛选条件表达式只能使用以下运算符：==、\$1=、>、<、>= 或 <=。不支持将多个筛选条件表达式与 AND (&&) 或 OR (\$1\$1) 组合使用。此运算符的返回类型始终为 JSON 数组。

为了更好地理解 JSONPath 运算符，请查看以下 ec2 `DescribeInstances` API 操作的 JSON 响应。此响应下面提供了几个示例，它们说明通过向 `DescribeInstances` API 操作响应应用不同的 JSONPath 表达式获取的不同结果。

```
{
    "NextToken": "abcdefg",
    "Reservations": [
        {
            "OwnerId": "123456789012",
            "ReservationId": "r-abcd12345678910",
            "Instances": [
                {
                    "ImageId": "ami-12345678",
                    "BlockDeviceMappings": [
                        {
                            "Ebs": {
                                "DeleteOnTermination": true,
                                "Status": "attached",
                                "VolumeId": "vol-000000000000"
                            },
                            "DeviceName": "/dev/xvda"
                        }
                    ],
                    "State": {
                        "Code": 16,
                        "Name": "running"
                    }
                }
            ],
            "Groups": []
        },
        {
            "OwnerId": "123456789012",
            "ReservationId": "r-12345678910abcd",
            "Instances": [
                {
                    "ImageId": "ami-12345678",
                    "BlockDeviceMappings": [
                        {
                            "Ebs": {
                                "DeleteOnTermination": true,
                                "Status": "attached",
                                "VolumeId": "vol-111111111111"
                            },
                            "DeviceName": "/dev/xvda"
                        }
                    ],
                    "State": {
                        "Code": 80,
                        "Name": "stopped"
                    }
                }
            ],
            "Groups": []
        }
    ]
}
```

**JSONPath 示例 1：从 JSON 响应获取特定的 String**

```
JSONPath: 
$.Reservations[0].Instances[0].ImageId 

Returns:
"ami-12345678"

Type: String
```

**JSONPath 示例 2：从 JSON 响应获取特定的 Boolean**

```
JSONPath:
$.Reservations[0].Instances[0].BlockDeviceMappings[0].Ebs.DeleteOnTermination
        
Returns:
true

Type: Boolean
```

**JSONPath 示例 3：从 JSON 响应获取特定的 Integer**

```
JSONPath:
$.Reservations[0].Instances[0].State.Code
        
Returns:
16

Type: Integer
```

**JSONPath 示例 4：深层扫描 JSON 响应，然后以 StringList 的形式获取 VolumeId 的所有值** 

```
JSONPath:
$.Reservations..BlockDeviceMappings..VolumeId
        
Returns:
[
   "vol-000000000000",
   "vol-111111111111"
]

Type: StringList
```

**JSONPath 示例 5：以 StringMap 的形式获取特定的 BlockDeviceMappings 对象**

```
JSONPath:
$.Reservations[0].Instances[0].BlockDeviceMappings[0]
        
Returns:
{
   "Ebs" : {
      "DeleteOnTermination" : true,
      "Status" : "attached",
      "VolumeId" : "vol-000000000000"
   },
   "DeviceName" : "/dev/xvda"
}

Type: StringMap
```

**JSONPath 示例 6：深层扫描 JSON 响应，然后以 MapList 的形式获取所有 State 对象**

```
JSONPath:
$.Reservations..Instances..State 
    
Returns:
[
   {
      "Code" : 16,
      "Name" : "running"
   },
   {
      "Code" : 80,
      "Name" : "stopped"
   }
]

Type: MapList
```

**JSONPath 示例 7：筛选处于 `running` 状态的实例**

```
JSONPath:
$.Reservations..Instances[?(@.State.Name == 'running')]

Returns:
[
  {
    "ImageId": "ami-12345678",
    "BlockDeviceMappings": [
      {
        "Ebs": {
          "DeleteOnTermination": true,
          "Status": "attached",
          "VolumeId": "vol-000000000000"
        },
        "DeviceName": "/dev/xvda"
      }
    ],
    "State": {
      "Code": 16,
      "Name": "running"
    }
  }
]

Type: MapList
```

**JSONPath 示例 8：返回未处于 `running` 状态实例的 `ImageId`**

```
JSONPath:
$.Reservations..Instances[?(@.State.Name != 'running')].ImageId

Returns:
[
  "ami-12345678"
]

Type: StringList | String
```