使用操作输出作为输入
多个自动化操作会返回预定义的输出。您可以使用格式 {{
将这些输出作为输入传递到运行手册的后续步骤。您还可以在运行手册中为自动化操作定义自定义输出。让您可以运行脚本,或调用其他 Amazon Web Services 服务 的 API 操作一次,以便您在后续操作中重复使用这些值作为输入。运行手册中的参数类型是静态的。这意味着参数类型在定义后无法更改。要定义步骤输出,请提供以下字段:stepName
.outputName
}}
-
名称:(必需)输出名称,用于在后续步骤中引用输出值。
-
选择器:(必需)用于确定输出值的 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 EC2DescribeInstanceStatus
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 操作定义。您可以在以下服务参考
您可以在以下位置查看每个自动化操作的架构:
架构包括使用每个操作所需字段的描述。
使用 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