使用操作输出作为输入 - Amazon Systems Manager
在运行手册中使用 JSONPath
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

Amazon Systems Manager Change Manager 不再向新客户开放。现有客户可以继续正常使用该服务。有关更多信息，请参阅 Amazon Systems Manager Change Manager 可用性变更。

使用操作输出作为输入

多个自动化操作会返回预定义的输出。您可以使用格式 {{stepName.outputName}} 将这些输出作为输入传递到运行手册的后续步骤。您还可以在运行手册中为自动化操作定义自定义输出。让您可以运行脚本，或调用其他 Amazon Web Services 服务 的 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 Amazon 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 操作定义。您可以在以下服务参考页面的左侧导航栏中选择服务来查看 API 操作（也称为方法）。在要调用的服务的客户端部分中选择一种方法。例如，以下页面中列出了 Amazon Relational Database Service (Amazon RDS) 的所有 API 操作（方法）：Amazon RDS 方法。

您可以在以下位置查看每个自动化操作的架构：

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

使用 Selector/PropertySelector 字段

每个自动化操作都要求您指定一个输出 Selector（用于 aws:executeAwsApi）或 PropertySelector（用于 aws:assertAwsResourceProperty 和 aws:waitForAwsResourceProperty)。这些字段用于处理 Amazon 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

JSONPath 表达式是以“$”开头的字符串。用于选择 JSON 元素中的一个或多个组件。下面的列表包含有关 Systems Manager 自动化支持的 JSONPath 运算符的信息：

  • 点表示的子字段 (.)：用于 JSON 对象。此运算符选择特定键的值。

  • 深层扫描 (..)：用于 JSON 元素。此运算符逐级扫描 JSON 元素，并使用特定键选择值列表。此运算符的返回类型始终为 JSON 数组。在自动化步骤输出类型上下文中，运算符可以是 StringList 或 MapList。

  • 数组索引 ([ ])：用于 JSON 数组。此运算符获取特定索引的值。

  • 筛选条件 ([?(expression)])：与 JSON 数组一起使用。此运算符筛选条件 JSON 数组值与筛选条件表达式中定义的标准相匹配。筛选条件表达式只能使用以下运算符：==、!=、>、<、>= 或 <=。不支持将多个筛选条件表达式与 AND (&&) 或 OR (||) 组合使用。此运算符的返回类型始终为 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