本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 创建 YAML 工作流文档
YAML 格式定义文档为映像构建过程的构建和测试阶段配置输入、输出和工作流步骤。您可以从包含标准化步骤的模板开始，也可以从头开始定义自己的工作流。无论您使用模板还是从头开始，都可以自定义工作流以满足您的需求。
## YAML 工作流文档的结构
Image Builder 用于执行映像构建和测试操作的 YAML 工作流文档的结构如下。
+ [工作流文档标识](#wfdoc-struct-ident)
+ [工作流文档输入参数](#wfdoc-struct-param)
+ [工作流文档步骤](#wfdoc-struct-step)
+ [工作流文档输出](#wfdoc-struct-output)
### 工作流文档标识
对工作流进行唯一标识。此部分可以包含以下属性。
| 字段 | 描述 | Type | 必需 |
| --- | --- | --- | --- |
| name | 工作流文档名称。 | 字符串 | 否 |
| 描述 | 文档描述。 | 字符串 | 否 |
| schemaVersion | 文档架构版本，当前为 1.0。 | 字符串 | 是 |
**示例**
```
---
name: sample-test-image
description: Workflow for a sample image, with extra configuration options exposed through workflow parameters.
schemaVersion: 1.0
```
### 工作流文档输入参数
工作流文档的这一部分定义了调用方可以指定的输入参数。如果您没有任何参数，则可以省略此部分。如果您确实指定了参数，则每个参数可以包含以下属性。
| 字段 | 描述 | Type | 必需 | 约束 |
| --- | --- | --- | --- | --- |
| name | 参数的名称。 | 字符串 | 是 | |
| 描述 | 参数描述。 | 字符串 | 否 | |
| 默认 | 如果未提供值，则为该参数的默认值。如果参数定义中未包含默认值，则运行时需要该参数值。 | 匹配参数数据类型。 | 否 | |
| 类型 | 参数的数据类型。如果参数定义中未包含数据类型，则参数类型默认为运行时所需的字符串值。 | 字符串 | 是 | 参数的数据类型必须为以下类型之一： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/imagebuilder/latest/userguide/image-workflow-create-document.html) |
**示例**
在工作流文档中指定参数。
```
parameters:
- name: waitForActionAtEnd
type: boolean
default: true
description: "Wait for an external action at the end of the workflow"
```
在工作流文档中使用参数值。
```
$.parameters.waitForActionAtEnd
```
### 工作流文档步骤
为工作流指定最多 15 个步骤操作。步骤按照工作流文档中定义的顺序运行。如果失败，将按相反的顺序运行回滚，从失败的步骤开始，然后反向执行之前的步骤。
每个步骤都可以引用任何先前步骤操作的输出。这称为*链接或引用*。要引用前一步操作的输出，可以使用 JSONPath 选择器。例如：
```
$.stepOutputs.step-name.output-name
```
有关更多信息，请参阅 [在工作流文档中使用动态变量](wfdoc-dynamic-vars.md)。
**注意**
尽管步骤本身并没有输出属性，但步骤操作的任何输出都包含在该步骤的 `stepOutput` 中。
每个步骤都可以包含以下属性。
| 字段 | 描述 | Type | 必需 | 默认 值 | 约束 |
| --- | --- | --- | --- | --- | --- |
| action | 此步骤执行的工作流操作。 | 字符串 | 是 | | 必须是 Image Builder 工作流文档支持的步骤操作。 |
| `if`，后跟一组修改 `if` 运算符的条件语句。 | 条件语句将控制决策点流程添加到工作流步骤的主体中。 | 字典 | 否 | | Image Builder 支持以下条件语句作为 `if` 运算符的修饰符： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/imagebuilder/latest/userguide/image-workflow-create-document.html) |
| 描述 | 步骤描述。 | 字符串 | 否 | | 不允许使用空字符串。如果包含，长度必须为 1-1024 个字符。 |
| 输入 | 包含步骤操作运行所需的参数。您可以将键值指定为静态值，也可以使用可解析为正确数据类型的 JSONPath 变量来指定。 | 字典 | 是 | | |
| name | 步骤的名称。在工作流文档内，此名称必须具有唯一性。 | 字符串 | 是 | | 长度必须介于 3-128 个字符之间。 可以包含字母数字字符和 `_`。不能包含空格。 |
| onFailure | 配置步骤失败时要执行的操作，如下所示。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/imagebuilder/latest/userguide/image-workflow-create-document.html) | 字符串 | 否 | `Abort` | `Abort` \$1 `Continue` |
| rollbackEnabled | 配置发生故障时是否回滚该步骤。您可以使用静态布尔值或解析为布尔值的动态 JSONPath 变量。 | 布尔值 | 否 | `true` | `true` \$1 `false` \$1 或者解析为真或假的 JSONPath 变量。 |
| timeoutSeconds | 在失败和重试（如果重试适用）之前步骤运行的最长时间（以秒为单位）。 | 整数 | 否 | 取决于为步骤操作定义的默认值（如果适用）。 | 不能超过步骤操作的最大超时时间 |
| 等待秒 | 步骤执行暂停的时间，以秒为单位。 | 整数 | 否 | 0 | 不能超过步骤操作的 timeoutSeconds |
**示例**
```
steps:
- name: LaunchTestInstance
action: LaunchInstance
onFailure: Abort
inputs:
waitFor: "ssmAgent"
- name: ApplyTestComponents
action: ExecuteComponents
onFailure: Abort
inputs:
instanceId.$: "$.stepOutputs.LaunchTestInstance.instanceId"
- name: TerminateTestInstance
action: TerminateInstance
onFailure: Continue
inputs:
instanceId.$: "$.stepOutputs.LaunchTestInstance.instanceId"
- name: WaitForActionAtEnd
action: WaitForAction
if:
booleanEquals: true
value: "$.parameters.waitForActionAtEnd"
```
### 工作流文档输出
定义工作流的输出。每个输出都是一个键值对，可指定输出的名称和值。您可以使用输出在运行时导出后续工作流可以使用的数据。此部分是可选的。
您定义的每个输出都包含以下属性。
| 字段 | 描述 | Type | 必需 |
| --- | --- | --- | --- |
| name | 输出的名称。此名称在管道包含的工作流中必须具有唯一性。 | 字符串 | 是 |
| 值 | 输出的值。字符串的值可以是动态变量，例如步骤操作的输出文件。有关更多信息，请参阅 [在工作流文档中使用动态变量](wfdoc-dynamic-vars.md)。 | 字符串 | 是 |
**示例**
使用 `createProdImage` 步骤的步骤输出为工作流文档创建输出映像 ID。
```
outputs:
- name: 'outputImageId'
value: '$.stepOutputs.createProdImage.imageId'
```
请参阅下一个工作流中的工作流输出。
```
$.workflowOutputs.outputImageId
```
# 工作流程文档支持的步骤操作
本节详细介绍了 Image Builder 支持的步骤操作。本节中使用的术语
AMI
亚马逊机器映像
进行筛选
Amazon 资源名称
**Topics**
+ [ApplyImageConfigurations](#wfdoc-step-action-apply-image-configurations)
+ [BootstrapInstanceForContainer](#wfdoc-step-action-bootstrap-container)
+ [CollectImageMetadata](#wfdoc-step-action-collect-image-metadata)
+ [CollectImageScanFindings](#wfdoc-step-action-collect-findings)
+ [CreateImage](#wfdoc-step-action-create-img-from-inst)
+ [DistributeImage](#wfdoc-step-action-distribute-image)
+ [ExecuteComponents](#wfdoc-step-action-exec-components)
+ [ExecuteStateMachine](#wfdoc-step-action-exec-state-machine)
+ [LaunchInstance](#wfdoc-step-action-launch-instance)
+ [ModifyImageAttributes](#wfdoc-step-action-modify-image-attributes)
+ [RegisterImage](#wfdoc-step-action-register-image)
+ [RunCommand](#wfdoc-step-action-run-command)
+ [RunSysPrep](#wfdoc-step-action-run-sysprep)
+ [SanitizeInstance](#wfdoc-step-action-sanitize-instance)
+ [TerminateInstance](#wfdoc-step-action-terminate-instance)
+ [WaitForAction](#wfdoc-step-action-waitfor)
+ [WaitForSSMAgent](#wfdoc-step-action-wait-for-ssm-agent)
## ApplyImageConfigurations
此步骤操作将各种配置和集成应用于分布式 AMIs，例如许可证配置、启动模板配置、S3 导出配置、 EC2 快速启动配置和 Systems Manager 参数配置。配置仅适用于源账户中的分布式映像，但可以跨账户应用的 SSM 参数配置除外。
**默认超时：**360 分钟
**最大超时：**720 分钟
**回滚：**此步骤操作没有回滚。
**输入：**下表包含此步骤操作支持的输入。
| 输入名称 | 说明 | Type | 必需 | 默认 | 约束 |
| --- | --- | --- | --- | --- | --- |
| region | 图像区域。 | 字符串 | 是 | | |
| licenseConfigurationArns | 镜像的许可配置 ARN。 | 数组 | 否 | | |
| launchTemplateConfigurations | | 数组 | 否 | | |
| launchTemplateConfigurations:launchTemplateId | 要应用于图像的启动模板 ID。 | 字符串 | 如果launchTemplateConfigurations已指定，则是 | | |
| launchTemplateConfigurations:账户 ID | IDs 要应用于图片的启动模板账户。 | 字符串 | 否 | | |
| launchTemplateConfigurations:setDefaultVersion | 图像的启动模板默认版本设置。 | 布尔值 | 否 | | |
| s3 ExportConfiguration | | 数组 | 否 | | |
| s3ExportConfiguration: 角色名 | 映像的 S3 导出配置角色名称。 | 字符串 | 如果s3ExportConfiguration已指定，则是 | | |
| s3ExportConfiguration：diskImageFormat | 映像的 S3 导出配置磁盘映像格式。 | 字符串 | 如果s3ExportConfiguration已指定，则是 | | 允许的值-VMDK\$1RAW\$1VHD |
| s3: s3Bucket ExportConfiguration | 映像的 S3 导出配置存储桶名称。 | 字符串 | 如果s3ExportConfiguration已指定，则是 | | |
| s3: s3Prefix ExportConfiguration | 映像的 S3 导出配置存储桶前缀。 | 字符串 | 否 | | |
| fastLaunchConfigurations | 映像的 EC2 快速启动配置。 | 数组 | 否 | | |
| fastLaunchConfigurations:已启用 | EC2 图像 enabled/disabled 的快速启动。 | 布尔值 | 如果fastLaunchConfigurations已指定，则是 | | |
| fastLaunchConfigurations:快照配置 | EC2 图像 enabled/disabled 的快速启动。 | Map | 否 | | |
| fastLaunchConfigurations:快照配置：targetResourceCount | EC2 快速启动图像的目标资源数量。 | 整数 | 否 | | |
| fastLaunchConfigurations:maxParallelLaunches | EC2 Fast Launch 图像的最大并行启动次数。 | 整数 | 否 | | |
| fastLaunchConfigurations:启动模板 | | | 否 | | |
| fastLaunchConfigurations:启动模板:launchTemplateId | EC2 图像的快速启动启动模板 ID。 | 字符串 | 否 | | |
| fastLaunchConfigurations:启动模板:launchTemplateName | EC2 快速启动镜像的启动模板名称。 | 字符串 | 否 | | |
| fastLaunchConfigurations:启动模板:launchTemplateVersion | EC2 快速启动启动镜像的模板版本。 | 字符串 | 否 | | |
| ssmParameterConfigurations | 镜像的 SSM 参数配置。 | Map | 否 | | |
| ssmParameterConfigurations:amiAccountId | 图像的 SSM 参数 AMI 账户 ID。 | 字符串 | 否 | | |
| ssmParameterConfigurations:parameterName | 图像的 SSM 参数名称。 | 字符串 | 如果ssmParameterConfigurations已指定，则是 | | |
| ssmParameterConfigurations:dataType | 图像的 SSM 参数数据类型。 | 字符串 | 否 | | 允许的值-文本 \$1 aws: ec2: image) |
**输出：**下表包含此步骤操作的输出。
| 输出名称 | 说明 | Type |
| --- | --- | --- |
| 配置镜像 | 已配置映像的列表。 | 数组 |
| 配置镜像：账号 ID | 分布式镜像的目标账户 ID。 | 字符串 |
| 配置图像:名称 | AMI 的名称。 | 字符串 |
| 配置图片:amiid | 分布式映像的 AMI ID。 | 字符串 |
| 配置图片：开始日期 | 开始分发的 UTC 时间。 | 字符串 |
| 配置图片：日期已停止 | 分发完成时的 UTC 时间。 | 字符串 |
| 配置图像:步骤 | 分发停止的步骤。 | 已完成\$1 \$1 AssociateLicensesRunning \$1 \$1 UpdateLaunchTemplateRunning \$1 PutSsmParametersRunning \$1 UpdateFastLaunchConfiguration ExportAmiQueued ExportAmiRunning |
| 配置图片:区域 | 分布式映像的 AWS | 字符串 |
| 配置图像:状态 | 分发状态。 | 已完成 \$1 失败 \$1 已取消 \$1 TimedOut |
| 配置图像：错误消息 | 错误消息（如果有）。 | 字符串 |
**示例**
在工作流文档中指定步骤操作。
```
- name: ApplyImageConfigurations
action: ApplyImageConfigurations
onFailure: Abort
inputs:
distributedImages.$: $.stepOutputs.DistributeImageStep.distributedImages
```
在工作流文档中使用步骤操作值的输出。
```
$.stepOutputs.ApplyImageConfigurationsStep.configuredImages
```
## BootstrapInstanceForContainer
此步骤操作运行服务脚本来引导实例，以最低要求运行容器工作流。Image Builder 使用 Systems Manager API 中的 **sendCommand** 来运行此脚本。有关更多信息，请参阅 [AWS Systems Manager Run Command](https://docs.aws.amazon.com/systems-manager/latest/userguide/execute-remote-commands.html)。
**注意**
引导脚本会安装 AWS CLI 和 Docker 包，它们是 Image Builder 成功构建 Docker 容器的先决条件。如果未包含此步骤操作，映像构建可能会失败。
**默认超时：**60 分钟
**最大超时：**720 分钟
**回滚：**此步骤操作没有回滚。
**输入：**下表包含此步骤操作支持的输入。
| 输入名称 | 说明 | Type | 必需 | 默认 | 约束 |
| --- | --- | --- | --- | --- | --- |
| instanceId | 要引导的实例 ID。 | 字符串 | 是 | | 这必须是启动此工作流实例的工作流步骤的输出实例 ID。 |
**输出：**下表包含此步骤操作的输出。
| 输出名称 | 说明 | Type |
| --- | --- | --- |
| runCommandId | 在实例上运行引导脚本的 Systems Manager sendCommand 的 ID。 | 字符串 |
| status | 从 Systems Manager sendCommand 返回的状态。 | 字符串 |
| output | 从 Systems Manager sendCommand 返回的输出。 | 字符串 |
**示例**
在工作流文档中指定步骤操作。
```
- name: ContainerBootstrapStep
action: BootstrapInstanceForContainer
onFailure: Abort
inputs:
instanceId.$: $.stepOutputs.LaunchStep.instanceId
```
在工作流文档中使用步骤操作值的输出。
```
$.stepOutputs.ContainerBootstrapStep.status
```
## CollectImageMetadata
此步骤操作仅对构建工作流有效。
EC2 Image Builder 在其启动的 EC2 实例上运行 [AWS Systems Manager （Systems Manager）代理](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent.html)，以构建和测试您的映像。Image Builder 使用 [Systems Manager 清单](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-inventory.html)，以收集在构建阶段使用的实例的其他信息。该信息包括操作系统 (OS) 名称和版本，以及操作系统报告的软件包及其相应版本的列表。
**注意**
此步骤操作仅适用于创建的图像 AMIs。
**默认超时：**30 分钟
**最大超时：**720 分钟
**回滚：**Image Builder 会回滚在此步骤中创建的所有 Systems Manager 资源。
**输入：**下表包含此步骤操作支持的输入。
| 输入名称 | 说明 | Type | 必需 | 默认 | 约束 |
| --- | --- | --- | --- | --- | --- |
| instanceId | 应用元数据设置的构建实例。 | 字符串 | 是 | | 这必须是启动此工作流构建实例的工作流步骤的输出实例 ID。 |
**输出：**下表包含此步骤操作的输出。
| 输出名称 | 说明 | Type |
| --- | --- | --- |
| osVersion | 从构建实例收集的操作系统名称和版本。 | 字符串 |
| associationId | 用于清单收集的 Systems Manager 关联 ID。 | 字符串 |
**示例**
在工作流文档中指定步骤操作。
```
- name: CollectMetadataStep
action: CollectImageMetadata
onFailure: Abort
inputs:
instanceId: $.stepOutputs.LaunchStep.instanceId
```
在工作流文档中使用步骤操作的输出。
```
$.stepOutputs.CollectMetadataStep.osVersion
```
## CollectImageScanFindings
如果您的账户启用了 Amazon Inspector，并且您的管道启用了映像扫描，则此步骤操作会收集 Amazon Inspector 为您的测试实例报告的映像扫描调查发现。此步骤操作不适用于构建工作流。
**默认超时：**120 分钟
**最大超时：**720 分钟
**回滚：**此步骤操作没有回滚。
**输入：**下表包含此步骤操作支持的输入。
| 输入名称 | 说明 | Type | 必需 | 默认 | 约束 |
| --- | --- | --- | --- | --- | --- |
| instanceId | 在其上运行扫描的实例的 ID。 | 字符串 | 是 | | 这必须是启动此工作流实例的工作流步骤的输出实例 ID。 |
**输出：**下表包含此步骤操作的输出。
| 输出名称 | 说明 | Type |
| --- | --- | --- |
| runCommandId | 运行脚本以收集调查发现的 Systems Manager sendCommand 的 ID。 | 字符串 |
| status | 从 Systems Manager sendCommand 返回的状态。 | 字符串 |
| output | 从 Systems Manager sendCommand 返回的输出。 | 字符串 |
**示例**
在工作流文档中指定步骤操作。
```
- name: CollectFindingsStep
action: CollectImageScanFindings
onFailure: Abort
inputs:
instanceId.$: $.stepOutputs.LaunchStep.instanceId
```
在工作流文档中使用步骤操作值的输出。
```
$.stepOutputs.CollectFindingsStep.status
```
## CreateImage
此步骤操作使用 Amazon EC2 `CreateImage` API 从正在运行的实例创建映像。在创建过程中，步骤操作会根据需要进行等待，以验证资源是否已达到正确的状态，然后再继续后续操作。
**默认超时：**720 分钟
**最大超时时间：**3 天
**回滚：**此步骤操作没有回滚。
**输入：**下表包含此步骤操作支持的输入。
| 输入名称 | 说明 | Type | 必需 | 默认 | 约束 |
| --- | --- | --- | --- | --- | --- |
| instanceId | 要从中创建新映像的实例。 | 字符串 | 是 | | 此步骤开始时，提供实例 ID 的实例必须处于 running 状态。 |
**输出：**下表包含此步骤操作的输出。
| 输出名称 | 说明 | Type |
| --- | --- | --- |
| imageId | 所创建映像的 AMI ID。 | 字符串 |
**示例**
在工作流文档中指定步骤操作。
```
- name: CreateImageFromInstance
action: CreateImage
onFailure: Abort
inputs:
instanceId.$: "i-1234567890abcdef0"
```
在工作流文档中使用步骤操作值的输出。
```
$.stepOutputs.CreateImageFromInstance.imageId
```
## DistributeImage
此步骤操作将 AMI 分发到指定的区域和账户。它根据工作流程中提供的 CreateImage CreateImagePipeline APIs或和/或自定义分发设置请求中提供的分配配置在目标区域和账户中创建 AMI 的副本，以覆盖分配配置中的设置。
**默认超时：**360 分钟
**最大超时：**720 分钟
**回滚：**此步骤操作没有回滚。
**输入：**下表包含此步骤操作支持的输入。
| 输入名称 | 说明 | Type | 必需 | 默认 | 约束 |
| --- | --- | --- | --- | --- | --- |
| region | 要分发图像的区域列表。 | 字符串 | 是 | | 最小长度为 1。最大长度为 1024。 |
| name | 分发配置的名称。 | 字符串 | 否 | | |
| 描述 | 分布配置的分布。 | 字符串 | 否 | | |
| targetAccountIds | IDs 要将图像分发到的账户。 | 数组 | 否 | | |
| amiTags | 分发配置的标签。 | Map | 否 | | |
| kmsKeyId | 应用于分布式映像的 KMS 密钥。 | 字符串 | 否 | | |
**输出：**下表包含此步骤操作的输出。
| 输出名称 | 说明 | Type |
| --- | --- | --- |
| 分布式图片 | 分布式映像列表 | 数组 |
| 分布式图片:区域 | 分布式图像的 AWS 区域。 | 字符串 |
| 分布式图片:名称 | AMI 的名称。 | 字符串 |
| 分布式图片:amiid | 分布式映像的 AMI ID。 | 字符串 |
| 分布式图片：账户 ID | 分布式镜像的目标账户 ID。 | 字符串 |
| 分布式图片：开始日期 | 开始分发的 UTC 时间。 | 字符串 |
| 分布式图片：日期已停止 | 分发完成时的 UTC 时间。 | 字符串 |
| 分布式图片:状态 | 分发状态。 | 已完成 \$1 失败 \$1 已取消 \$1 TimedOut |
| 分布式图像:步骤 | 分发停止的步骤。 | 已完成\$1 CopyAmiRunning |
| 分布式镜像：错误消息 | 错误消息（如果有）。 | 字符串 |
**示例**
在工作流文档中指定步骤操作。
```
- name: DistributeImage
action: DistributeImage
onFailure: Abort
inputs:
distributions:
- region.$: "$.parameters.SourceRegion"
description: "AMI distribution to source region"
amiTags:
DistributionTest: "SourceRegion"
WorkflowStep: "DistributeToSourceRegion"
BuildDate: "{{imagebuilder:buildDate:yyyyMMHHss}}"
BuildVersion: "{{imagebuilder:buildVersion}}"
```
在工作流文档中使用步骤操作值的输出。
```
$.stepOutputs.DistributeImageStep.distributedImages
```
## ExecuteComponents
此步骤操作会运行配方中为当前正在构建的映像指定的组件。构建工作流在构建实例上运行构建组件。测试工作流仅在测试实例上运行测试组件。
Image Builder 使用 Systems Manager API 中的 **sendCommand** 来运行组件。有关更多信息，请参阅 [AWS Systems Manager Run Command](https://docs.aws.amazon.com/systems-manager/latest/userguide/execute-remote-commands.html)。
**默认超时：**720 分钟
**最大超时时间：**1 天
**回滚：**此步骤操作没有回滚。
**输入：**下表包含此步骤操作支持的输入。
| 输入名称 | 说明 | Type | 必需 | 默认 | 约束 |
| --- | --- | --- | --- | --- | --- |
| instanceId | 组件应在其上运行的实例的 ID。 | 字符串 | 是 | | 这必须是启动此工作流实例的工作流步骤的输出实例 ID。 |
**输出：**下表包含此步骤操作的输出。
| 输出名称 | 说明 | Type |
| --- | --- | --- |
| runCommandId | 在实例上运行组件的 Systems Manager sendCommand 的 ID。 | 字符串 |
| status | 从 Systems Manager sendCommand 返回的状态。 | 字符串 |
| output | 从 Systems Manager sendCommand 返回的输出。 | 字符串 |
**示例**
在工作流文档中指定步骤操作。
```
- name: ExecComponentsStep
action: ExecuteComponents
onFailure: Abort
inputs:
instanceId: $.stepOutputs.LaunchStep.instanceId
```
在工作流文档中使用步骤操作的输出。
```
$.stepOutputs.ExecComponentsStep.status
```
## ExecuteStateMachine
此步骤操作从 Image Builder 工作流程中开始执行 AWS Step Functions 状态机。Image Builder 使用 Step Functions `StartExecution` API 启动状态机并等待状态机完成。这对于将复杂的工作流程、合规性验证或认证流程集成到您的图像构建管道中非常有用。
有关更多信息，请参阅《*AWS Step Functions 开发者指南》*[中的 Step Functions 中了解状态机](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-statemachines.html)。
**默认超时：**6 小时
**最大超时：**24 小时
**回滚：**此步骤操作没有回滚。
**输入：**下表包含此步骤操作支持的输入。
| 输入名称 | 说明 | Type | 必需 | 默认 | 约束 |
| --- | --- | --- | --- | --- | --- |
| stateMachineArn | 要执行的 Step Functions 状态机的 ARN。 | 字符串 | 是 | | 必须是有效的状态机 ARN。 |
| input | 要提供给状态机的 JSON 输入数据。 | 字符串 | 否 | \$1\$1 | 必须是有效的 JSON 字符串，最大长度：16 KiB。 |
**输出：**下表包含此步骤操作的输出。
| 输出名称 | 说明 | Type |
| --- | --- | --- |
| 执行 Arn | 状态机执行的 ARN。 | 字符串 |
| output | 状态机执行的输出。 | 字符串 |
**需要 IAM 权限**
您的自定义执行角色必须具有以下权限才能使用此步骤操作：
**允许操作**
+ `states:StartExecution`
+ `states:DescribeExecution`
**指定资源**
+ `arn:aws:states:us-west-2:111122223333:stateMachine:state-machine-name`
+ `arn:aws:states:us-west-2:111122223333:execution:state-machine-name:*`
**示例**
在工作流文档中指定步骤操作。
```
- name: ValidateImageCompliance
action: ExecuteStateMachine
timeoutSeconds: 3600
onFailure: Abort
inputs:
stateMachineArn: arn:aws:states:us-west-2:111122223333:stateMachine:ImageComplianceValidation
input: |
{
"imageId": "{{ $.stepOutputs.CreateImageFromInstance.imageId }}",
"region": "us-west-2",
"complianceLevel": "high",
"requiredScans": ["cve", "benchmark", "configuration"]
}
```
在工作流文档中使用步骤操作值的输出。
```
$.stepOutputs.ValidateImageCompliance.executionArn
```
## LaunchInstance
此步骤操作将在您的中启动一个实例， AWS 账户 并等待 Systems Manager 代理在该实例上运行，然后再继续下一步操作。启动操作使用与您的映像关联的配方和基础设施配置资源中的设置。例如，要启动的实例类型来自基础设施配置。输出是其启动的实例的实例 ID。
`waitFor` 输入会配置满足步骤完成要求的条件。
**默认超时：**75 分钟
**最大超时：**720 分钟
**回滚：**对于构建实例，回滚会执行您在基础设施配置资源中配置的操作。默认情况下，如果映像创建失败，则会终止构建实例。但是，基础设施配置中有一个设置，用于保留构建实例以进行故障排除。
**输入：**下表包含此步骤操作支持的输入。
| 输入名称 | 说明 | Type | 必需 | 默认 | 约束 |
| --- | --- | --- | --- | --- | --- |
| imageIdOverride | 用于启动实例的镜像 | 字符串 | 否 | 构建阶段：图像配方基础图片 测试阶段：从构建阶段输出 AMI | 必须是有效的 AMI ID |
| instanceTypesOverride | Image Builder 会尝试列表中的每种实例类型，直到找到成功启动的实例类型 | 字符串列表 | 否 | 在您的基础设施配置中指定的实例类型 | 必须是有效的实例类型 |
| waitFor | 在完成工作流程步骤并进入下一步之前要等待的条件 | 字符串 | 是 | | Image Builder 支持 ssmAgent。 |
**输出：**下表包含此步骤操作的输出。
| 输出名称 | 说明 | Type |
| --- | --- | --- |
| instanceId | 所启动实例的实例 ID。 | 字符串 |
**示例**
在工作流文档中指定步骤操作。
```
- name: LaunchStep
action: LaunchInstance
onFailure: Abort
inputs:
waitFor: ssmAgent
```
在工作流文档中使用步骤操作的输出。
```
$.stepOutputs.LaunchStep.instanceId
```
## ModifyImageAttributes
此步骤操作修改分布式的属性 AMIs，例如启动权限和其他 AMI 属性。它对 AMIs 已分配给目标地区和账户的内容进行操作。
**默认超时：**120 分钟
**最大超时时间：**180 分钟
**回滚：**此步骤操作没有回滚。
**输入：**下表包含此步骤操作支持的输入。
| 输入名称 | 说明 | Type | 必需 | 默认 | 约束 |
| --- | --- | --- | --- | --- | --- |
| region | 图像的区域。 | 字符串 | 是 | | |
| 启动许可 | | | 否 | | |
| 启动权限：用户 ID | 在图像 IDs 的启动权限中要修改的用户。 | 字符串 | 否 | | |
| 启动权限：用户组 | 在图像的启动权限中要修改的用户组。 | 字符串 | 否 | | |
| 启动权限：组织 ARN | 在镜像的启动权限中 ARNs 要修改的 AWS 组织。 | 字符串 | 否 | | |
| 启动权限：organizationalUnitArns | 在镜像的启动权限中 ARNs 要修改的 AWS 组织单位。 | 字符串 | 否 | | |
**输出：**下表包含此步骤操作的输出。
| 输出名称 | 说明 | Type |
| --- | --- | --- |
| ModifiedImages | 修改过的图像列表 | 数组 |
| 修改过的图片:账号 ID | 分布式镜像的目标账户 ID。 | 字符串 |
| 修改后的图片:名称 | AMI 的名称。 | 字符串 |
| 修改后的图片:amiid | 分布式映像的 AMI ID。 | 字符串 |
| 修改后的图片:开始日期 | 开始分发的 UTC 时间。 | 字符串 |
| 修改后的图片:日期已停止 | 分发完成时的 UTC 时间。 | 字符串 |
| 修改后的图像:步骤 | 分发停止的步骤。 | 已完成\$1 ModifyAmiRunning |
| 修改后的图片:区域 | 图像的 AWS 区域。 | 字符串 |
| 修改后的图片:状态 | 分发状态。 | 已完成 \$1 失败 \$1 已取消 \$1 TimedOut |
| 修改后的图像：错误消息 | 错误消息（如果有）。 | 字符串 |
**示例**
在工作流文档中指定步骤操作。
```
- name: ModifyImageAttributes
action: ModifyImageAttributes
onFailure: Abort
inputs:
distributedImages.$: $.stepOutputs.DistributeImageStep.distributedImages
```
在工作流文档中使用步骤操作值的输出。
```
$.stepOutputs.ModifyImageAttributesStep.modifiedImages
```
## RegisterImage
此步骤操作使用亚马逊 API 注册新的亚马逊系统映像 (AM EC2 RegisterImage I)。它允许您根据现有快照或一组快照创建 AMI，并指定各种图像属性。
**默认超时：**540 分钟
**最大超时：**720 分钟
**回滚：**此步骤操作没有回滚。
**输入：**下表包含此步骤操作支持的输入。
| 输入名称 | 说明 | Type | 必需 | 默认 | 约束 |
| --- | --- | --- | --- | --- | --- |
| 架构 | AMI 的架构。 | 字符串 | 否 | | 有效值：i386、x86\$164、arm64、x86\$164\$1mac、arm64\$1mac |
| blockDeviceMapping | AMI 的块储存设备映射条目。 | 数组 | 否 | | |
| 启动模式 | AMI 的启动模式。 | 字符串 | 否 | | 有效值：legacy-bios、uefi、uefi 首选 |
| 描述 | 对 AMI 的描述。 | 字符串 | 否 | | |
| enaSupport | 是否启用了 ENA 增强联网。 | 布尔值 | 否 | | |
| 图像位置 | AMI 清单的位置。 | 字符串 | 否 | | 支持 S3 的必填项 AMIs |
| IMDS 支持 | 支 IMDSv2 撑级别。 | 字符串 | 否 | | 有效值：v2.0 |
| includeSnapshotTags | 是否包含块储存设备映射中定义的第一个快照中的标签。 | 布尔值 | 否 | FALSE | 设置为 true 时，将按如下方式包含标签： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/imagebuilder/latest/userguide/wfdoc-step-actions.html) |
| kerneLid | 要使用的内核的 ID。 | 字符串 | 否 | | |
| ramdisKid | 要使用的 RAM 磁盘的 ID。 | 字符串 | 否 | | |
| rootDeviceName | 根设备的设备名称。 | 字符串 | 否 | | 示例：/dev/sda1 |
| sriovNetSupport | 使用英特尔 82599 VF 接口增强联网。 | 字符串 | 否 | | |
| tpm 支持 | TPM 版本支持。 | 字符串 | 否 | | 有效值：v2.0 |
| uefidata | Base64 编码的 UEFI 数据。 | 字符串 | 否 | | |
| 虚拟化类型 | 虚拟化类型。 | 字符串 | 否 | | 有效值：hvm、半虚拟化 |
**输出：**下表包含此步骤操作的输出。
| 输出名称 | 说明 | Type |
| --- | --- | --- |
| imageId | 已注册图像的 AMI ID。 | 字符串 |
**需要 IAM 权限**
您的自定义执行角色必须具有以下权限才能使用此步骤操作：
**允许操作**
+ `ec2:DescribeSnapshots`
+ `ec2:CreateTags`
**示例**
在工作流文档中指定步骤操作。
```
- name: RegisterNewImage
action: RegisterImage
onFailure: Abort
inputs:
architecture: "x86_64"
bootMode: "uefi"
blockDeviceMapping:
- DeviceName: "/dev/sda1"
Ebs:
SnapshotId: "snap-1234567890abcdef0"
VolumeSize: 100
VolumeType: "gp3"
rootDeviceName: "/dev/sda1"
virtualizationType: "hvm"
```
在工作流文档中使用步骤操作值的输出。
```
$.stepOutputs.RegisterNewImage.imageId
```
**示例： SnapshotId 来自另一个步骤，生成的 AMI 中包含快照标签**
```
- name: CreateSnapshot
action: RunCommand
onFailure: Abort
inputs:
instanceId: "i-1234567890abcdef0"
documentName: "AWS-RunShellScript"
parameters:
commands:
- "aws ec2 create-snapshot --volume-id vol-1234567890abcdef0 --description 'Snapshot for AMI' --query 'SnapshotId' --output text"
- name: RegisterImageFromSnapshot
action: RegisterImage
onFailure: Abort
inputs:
architecture: "x86_64"
bootMode: "uefi"
blockDeviceMapping:
- DeviceName: "/dev/sda1"
Ebs:
SnapshotId.$: "$.stepOutputs.CreateSnapshot.output[0]"
VolumeSize: 100
VolumeType: "gp3"
includeSnapshotTags: true
rootDeviceName: "/dev/sda1"
virtualizationType: "hvm"
```
## RunCommand
此步骤操作为您的工作流运行命令文档。Image Builder 使用 Systems Manager API 中的 **sendCommand** 来为您运行命令文档。有关更多信息，请参阅 [AWS Systems Manager Run Command](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command.html)。
**默认超时：**720 分钟
**最大超时：**720 分钟
**回滚：**此步骤操作没有回滚。
**输入：**下表包含此步骤操作支持的输入。
| 输入名称 | 说明 | Type | 必需 | 默认 | 约束 |
| --- | --- | --- | --- | --- | --- |
| instanceId | 要在其上运行命令文档的实例的 ID。 | 字符串 | 是 | | 这必须是启动此工作流实例的工作流步骤的输出实例 ID。 |
| documentName | 要运行的 Systems Manager 命令文档的名称。 | 字符串 | 是 | | |
| 参数 | 命令文档所需的任何参数的键值对列表。 | dictionary> | 有条件 | | |
| documentVersion | 要运行的命令文档版本。 | 字符串 | 否 | \$1DEFAULT | |
**输出：**下表包含此步骤操作的输出。
| 输出名称 | 说明 | Type |
| --- | --- | --- |
| runCommandId | 在实例上运行命令文档的 Systems Manager sendCommand 的 ID。 | 字符串 |
| status | 从 Systems Manager sendCommand 返回的状态。 | 字符串 |
| output | 从 Systems Manager sendCommand 返回的输出。 | 字符串列表 |
**示例**
在工作流文档中指定步骤操作。
```
- name: RunCommandDoc
action: RunCommand
onFailure: Abort
inputs:
documentName: SampleDocument
parameters:
osPlatform:
- "linux"
instanceId.$: $.stepOutputs.LaunchStep.instanceId
```
在工作流文档中使用步骤操作值的输出。
```
$.stepOutputs.RunCommandDoc.status
```
## RunSysPrep
此步骤操作使用 Systems Manager API 中的 **sendCommand** 为 Windows 实例运行 `AWSEC2-RunSysprep` 文档，然后为快照关闭构建实例。 这些操作遵循了[强化和清理图像AWS 的最佳实践。](https://aws.amazon.com/articles/public-ami-publishing-hardening-and-clean-up-requirements/)
**默认超时：**60 分钟
**最大超时：**720 分钟
**回滚：**此步骤操作没有回滚。
**输入：**下表包含此步骤操作支持的输入。
| 输入名称 | 说明 | Type | 必需 | 默认 | 约束 |
| --- | --- | --- | --- | --- | --- |
| instanceId | 要在其上运行 AWSEC2-RunSysprep 文档的实例的 ID。 | 字符串 | 是 | | 这必须是启动此工作流实例的工作流步骤的输出实例 ID。 |
**输出：**下表包含此步骤操作的输出。
| 输出名称 | 说明 | Type |
| --- | --- | --- |
| runCommandId | 在实例上运行 AWSEC2-RunSysprep 文档的 Systems Manager sendCommand 的 ID。 | 字符串 |
| status | 从 Systems Manager sendCommand 返回的状态。 | 字符串 |
| output | 从 Systems Manager sendCommand 返回的输出。 | 字符串 |
**示例**
在工作流文档中指定步骤操作。
```
- name: RunSysprep
action: RunSysPrep
onFailure: Abort
inputs:
instanceId.$: $.stepOutputs.LaunchStep.instanceId
```
在工作流文档中使用步骤操作值的输出。
```
$.stepOutputs.RunSysprep.status
```
## SanitizeInstance
此操作步骤会运行适用于 Linux 实例的推荐清理脚本，然后为快照关闭构建实例。清理脚本可帮助确保最终映像遵循安全最佳实践，并删除不应延续到快照中的构建构件或设置。有关脚本的更多信息，请参阅[需要在构建后进行清理](security-best-practices.md#post-build-cleanup)。此步骤操作不适用于容器映像。
Image Builder 使用 Systems Manager API 中的 **sendCommand** 来运行此脚本。有关更多信息，请参阅 [AWS Systems Manager Run Command](https://docs.aws.amazon.com/systems-manager/latest/userguide/execute-remote-commands.html)。
**默认超时：**60 分钟
**最大超时：**720 分钟
**回滚：**此步骤操作没有回滚。
**输入：**下表包含此步骤操作支持的输入。
| 输入名称 | 说明 | Type | 必需 | 默认 | 约束 |
| --- | --- | --- | --- | --- | --- |
| instanceId | 要清理的实例的 ID。 | 字符串 | 是 | | 这必须是启动此工作流实例的工作流步骤的输出实例 ID。 |
**输出：**下表包含此步骤操作的输出。
| 输出名称 | 说明 | Type |
| --- | --- | --- |
| runCommandId | 在实例上运行清理脚本的 Systems Manager sendCommand 的 ID。 | 字符串 |
| status | 从 Systems Manager sendCommand 返回的状态。 | 字符串 |
| output | 从 Systems Manager sendCommand 返回的输出。 | 字符串 |
**示例**
在工作流文档中指定步骤操作。
```
- name: SanitizeStep
action: SanitizeInstance
onFailure: Abort
inputs:
instanceId: $.stepOutputs.LaunchStep.instanceId
```
在工作流文档中使用步骤操作值的输出。
```
$.stepOutputs.SanitizeStep.status
```
## TerminateInstance
此步骤操作使用作为输入传入的实例 id 终止实例。
**默认超时：**30 分钟
**最大超时：**720 分钟
**回滚：**此步骤操作没有回滚。
**输入：**下表包含此步骤操作支持的输入。
| 输入名称 | 说明 | Type | 必需 | 默认 | 约束 |
| --- | --- | --- | --- | --- | --- |
| instanceId | 要终止的实例的 ID。 | 字符串 | 是 | | |
**输出：**此步骤操作没有输出。
**示例**
在工作流文档中指定步骤操作。
```
- name: TerminateInstance
action: TerminateInstance
onFailure: Continue
inputs:
instanceId.$: i-1234567890abcdef0
```
## WaitForAction
此步骤操作会暂停正在运行的工作流，并等待接收来自 Image Builder **SendWorkflowStepAction** API 操作的外部操作。此步骤使用详细信息类型将 EventBridge 事件发布到您的默认 EventBridge 事件总线`EC2 Image Builder Workflow Step Waiting`。如果您提供 SNS 主题 ARN，则该步骤还可以发送 SNS 通知；如果您提供 Lambda 函数名称，则该步骤还可以异步调用 Lambda 函数。
**默认超时：**3 天
**最大超时时间：**7 天
**回滚：**此步骤操作没有回滚。
**输入：**下表包含此步骤操作支持的输入。
| 输入名称 | 说明 | Type | 必需 | 默认 | 约束 |
| --- | --- | --- | --- | --- | --- |
| snsTopicArn | 可选的 SNS 主题 ARN，用于在工作流步骤处于待处理状态时向其发送通知。 | 字符串 | 否 | | |
| lambdaFunctionName | Lambda 函数的可选名称或 ARN，用于在工作流程步骤处于待处理状态时异步调用。 | 字符串 | 否 | | |
| payload | JSON 字符串用作 SNS 的消息和 Lambda 的有效负载。如果提供，则默认封装自定义有效负载message/payload, used for SNS and Lambda respectively. If not provided, generates default message/payload。 | 字符串 | 否 | | 必须是有效的 JSON 字符串，最大 16 KiB |
**输出：**下表包含此步骤操作的输出。
| 输出名称 | 说明 | Type |
| --- | --- | --- |
| action | SendWorkflowStepAction API 操作返回的操作。 | 字符串（RESUME 或 STOP） |
| reason | 返回操作的原因。 | 字符串 |
**需要 IAM 权限**
您的自定义执行角色必须具有以下权限才能使用此步骤操作：
**允许操作**
+ `lambda:InvokeFunction`
**指定资源**
+ `arn:aws:lambda:us-west-2:111122223333:function:function-name`
+ `arn:aws:lambda:us-west-2:111122223333:function:*`
**示例**
在带有 SNS 通知的工作流程文档中指定步骤操作。
```
- name: SendEventAndWait
action: WaitForAction
onFailure: Abort
inputs:
snsTopicArn: arn:aws:sns:us-west-2:111122223333:ExampleTopic
```
使用 Lambda 函数调用在工作流程文档中指定步骤操作。
```
- name: SendEventAndWaitWithLambda
action: WaitForAction
onFailure: Abort
inputs:
lambdaFunctionName: ExampleFunction
payload: |
{
"imageId": "{{ $.stepOutputs.CreateImageFromInstance.imageId }}",
"region": "us-west-2"
}
```
在工作流文档中使用步骤操作值的输出。
```
$.stepOutputs.SendEventAndWait.reason
```
## WaitForSSMAgent
此步骤操作等待 EC2 实例在预期的无响应时间 AWS Systems Manager 之后变得可控。它对于存在已知实例中断的工作流程（例如系统重启、操作系统升级或暂时断开实例与 SSM 连接的特定于平台的操作）特别有用。Image Builder 会监控该实例，直到它恢复 SSM 连接或超时。
**默认超时：**60 分钟
**最大超时时间：**180 分钟
**回滚：**此步骤操作没有回滚。
**输入：**下表包含此步骤操作支持的输入。
| 输入名称 | 说明 | Type | 必需 | 默认 | 约束 |
| --- | --- | --- | --- | --- | --- |
| instanceId | 要监控 SSM 连接的实例的 ID。 | 字符串 | 是 | | 必须是有效的 EC2 实例 ID |
**输出：**下表包含此步骤操作的输出。
| 输出名称 | 说明 | Type |
| --- | --- | --- |
| status | SSM 代理的连接状态。 | 字符串 |
**示例**
在工作流文档中指定步骤操作。
```
- name: WaitForInstanceAfterReboot
action: WaitForSSMAgent
onFailure: Abort
timeoutInSeconds: 900
inputs:
instanceId.$: $.stepOutputs.LaunchStep.instanceId
```
在工作流文档中使用步骤操作值的输出。
```
$.stepOutputs.WaitForInstanceAfterReboot.Status
```
# 在工作流文档中使用动态变量
您可以在工作流文档中使用动态变量来表示映像创建过程中在运行时会发生变化的值。动态变量的字符串插值允许您在结构化内容（例如 JSON 字符串）中嵌入 JSONPath 表达式。当您需要将复杂负载中的运行时值传递给步进操作（如或）时，这特别有用。`ExecuteStateMachine` `WaitForAction`
要对动态变量使用字符串插值，请在字符串内容中将 JSONPath 表达式用双大括号`"{{...}}"`括起来。只有用双花括号括起来的 JSONPath 表达式才会被当作变量处理。任何未用双大括号括起的 JSONPath 表达式都被视为文字字符串内容。
**JSONPath 动态工作流程变量语法**
```
$..[.]
```
动态变量值表示为具有唯一标识目标变量的结构节点的 JSONPath 选择器。根 (\$1) 之后的第一个节点是指工作流文档结构，例如 `stepOutputs`，如果是 Image Builder 系统变量，则为 `imageBuilder`。以下列表包含支持 JSONPath 的工作流文档结构节点。
**文档结构节点**
+ 参数 – 工作流参数
+ stepOutputs – 同一工作流文档中某个步骤的输出
+ workflowOutputs – 已运行的工作流文档的输出
+ imagebuilder – Image Builder 系统变量
`parameters` 和 `stepOutputs` 文档结构节点包括步骤名称的可选节点。这样有助于确保所有步骤中变量名称的唯一性。
中的最后一个节点 JSONPath 是目标变量的名称，例如`instanceId`。
每个步骤都可以使用这些 JSONPath 动态变量引用任何先前步骤操作的输出。这也称为*链接或引用*。要引用先前步骤操作的输出，可以使用以下动态变量。
```
$.stepOutputs.step-name.output-name
```
**重要**
当输入参数引用动态变量时，必须将链接指示符 (`.$`) 附加到参数名称的末尾。
**示例 1：输入参数链接指示器**
以下示例显示了一个输入参数，该参数在运行时使用字符串插值来解析参数值中的动态变量。
```
- name: ApplyTestComponents
action: ExecuteComponents
onFailure: Abort
inputs:
instanceId.$: "$.stepOutputs.LaunchTestInstance.instanceId"
```
**示例 2：动态变量中的字符串插值**
以下示例演示了动态变量如何在运行时使用字符串插值来确定值。
```
- name: ValidateImageConfiguration
action: ExecuteStateMachine
inputs:
stateMachineArn: arn:aws:states:us-east-1:111122223333:stateMachine:ImageValidation
input: |
{
"imageId": "{{ $.stepOutputs.CreateImageFromInstance.imageId }}",
"region": "us-east-1",
"buildDate": "{{ $.imagebuilder.dateTime }}",
"instanceType": "{{ $.stepOutputs.LaunchStep.instanceType }}"
}
```
在此示例中，用双大括号包裹的 JSONPath 表达式在运行时被解析：
+ `{{ $.stepOutputs.CreateImageFromInstance.imageId }}`-解析为步骤中的实际图片 ID CreateImageFromInstance
+ `{{ $.imagebuilder.dateTime }}`-解析为当前构建时间戳。有关您可以使用[使用 Image Builder 系统变量](#wfdoc-ib-vars)的 Image Builder 系统变量的列表，请参阅。
+ `{{ $.stepOutputs.LaunchStep.instanceType }}`-解析为中使用的实例类型 LaunchStep
像这样的字面字符串`"region": "us-east-1"`保持不变。
**注意**
字符串插值适用于工作流程文档中的任何字符串内容，包括使用 YAML pipe () 运算符的多行字符串。`|`大括号要求充当一种转义机制，可以清楚地区分JSONPath 变量和文字文本内容。
## 使用 Image Builder 系统变量
Image Builder 提供了以下可在工作流文档中使用的系统变量：
| 变量名称 | 说明 | Type | 示例值 |
| --- | --- | --- | --- |
| cloudWatchLog群组 | 输出 CloudWatch 日志的日志组的名称。 格式：`/aws/imagebuilder/` | 字符串 | `/aws/imagebuilder/sampleImageRecipe` |
| cloudWatchLog直播 | 输出 CloudWatch 日志的日志流的名称。 | 字符串 | *1.0.0/1* |
| collectImageMetadata | 指示 Image Builder 是否收集实例元数据的设置。 | 布尔值 | `true` \$1 `false` |
| collectImageScan调查结果 | 设置的当前值，该设置允许 Image Builder 收集映像扫描调查发现。 | 布尔值 | `true` \$1 `false` |
| imageBuildNumber | 映像的构建版本号。 | 整数 | *1* |
| imageId | 基础映像的 AMI ID。 | 字符串 | *ami-1234567890abcdef1* |
| imageName | 映像名称。 | 字符串 | *sampleImage* |
| imageType | 映像输出类型。 | 字符串 | `AMI` \$1 `Docker` |
| imageVersionNumber | 映像版本号。 | 字符串 | *1.0.0* |
| instanceProfileName | Image Builder 用于启动构建和测试实例的实例配置文件角色的名称。 | 字符串 | *SampleImageBuilderInstanceProfileRole* |
| platform | 所构建映像的操作系统平台。 | 字符串 | `Linux` \$1 `Windows` \$1 `MacOS` |
| s3Logs | 一个 JSON 对象，包含 Image Builder 写入的 S3 日志的配置。 | JSON 对象 | \$1's3Logs': \$1's3 BucketName ':*sample-bucket*', '3 ':KeyPrefix'\$1\$1 *ib-logs* |
| securityGroups | 适用于构建和测试实例的安全组 IDs 。 | 列表 [字符串] | *[sg-1234567890abcdef1, sg-11112222333344445]* |
| sourceImageARN | 工作流用于构建和测试阶段的 Image Builder 映像资源的 Amazon 资源名称（ARN）。 | 字符串 | arn: aws: imagebuilder::: image//*us-east-1**111122223333**sampleImage**1.0.0/1* |
| subnetId | 要在其中启动构建和测试实例的子网 ID。 | 字符串 | *subnet-1234567890abcdef1* |
| terminateInstanceOn失败 | 设置的当前值，可指示 Image Builder 在发生故障时终止实例或保留实例以进行故障排除。 | 布尔值 | `true` \$1 `false` |
| workflowPhase | 为执行工作流而运行的当前阶段。 | 字符串 | `Build` \$1 `Test` |
| workingDirectory | 工作目录的路径。 | 字符串 | `/tmp` |
# 在工作流步骤中使用条件语句
条件语句以 `if` 语句文档属性开头。`if` 语句的最终目的为确定是运行还是跳过该步骤操作。如果 `if` 语句解析为 `true`，则该步骤操作将运行。如果解析为 `false`，Image Builder 将跳过该步骤操作并在日志中记录 `SKIPPED` 的步骤状态。
`if` 语句支持分支语句（`and`、`or`）和条件修饰符 (`not`)。其还支持以下比较运算符，这些运算符根据所比较的数据类型（字符串或数字）执行值比较（等于、小于、大于）。
**支持的比较运算符**
+ `booleanEquals`
+ `numberEquals`
+ `numberGreaterThan`
+ `numberGreaterThanEquals`
+ `numberLessThan`
+ `numberLessThanEquals`
+ `stringEquals`
**分支语句和条件修饰符的规则**
以下规则适用于分支语句（`and`、`or`）和条件修饰符 (`not`)。
+ 分支语句和条件修饰符必须单独出现在某一行上。
+ 分支语句和条件修饰符必须遵循级别规则。
+ 父级别只能有一个语句。
+ 每个子分支或修饰符都会启动一个新级别。
有关级别的更多信息，请参阅 [条件语句中的嵌套级别](#wfdoc-conditional-structure)。
+ 每个分支语句必须至少包含一个子条件语句，但不能超过十个。
+ 条件修饰符仅对一个子条件语句执行操作。
## 条件语句中的嵌套级别
条件语句在自身部分中的多个级别上执行操作。例如，`if` 语句属性在工作流文档中与步骤名称和操作显示在同一级别。这是条件语句的基础。
您可以指定最多四个级别的条件语句，但父级别只能显示一个语句。所有其他分支语句、条件修饰符或条件运算符都从此处缩进，每个级别缩进一个。
以下概述显示了条件语句的最大嵌套级别数。
```
base:
parent:
- child (level 2)
- child (level 3)
child (level 4)
```
`if` 属性
`if` 属性将条件语句指定为文档属性。这是零级。
父级别
这是条件语句的第一级嵌套。此级别只能有一个语句。如果不需要分支或修饰符，则可以为没有子语句的条件运算符。除条件运算符外，此级别不使用连接号表示法。
子级别
二级到四级被视为子级别。子语句可以包括分支语句、条件修饰符或条件运算符。
**示例：嵌套级别**
以下示例演示了条件语句的最大级别数。
```
if:
and: #first level
- stringEquals: 'my_string' #second level
value: 'my_string'
- and: #also second level
- numberEquals: '1' #third level
value: 1
- not: #also third level
stringEquals: 'second_string' #fourth level
value: "diff_string"
```
**嵌套规则**
+ 子级的每个分支或修饰符都会启动一个新级别。
+ 每个级别都可缩进。
+ 最多可以有四个级别，包括父级别的一个语句、修饰符或运算符，以及最多三个其他级别。
## 条件语句示例
这组示例演示了条件语句的各个方面。
**分支：and**
`and` 分支语句对作为分支子级的表达式列表执行操作，所有这些表达式的计算结果都必须为 `true`。Image Builder 按照表达式在列表中出现的顺序计算表达式。如果任何表达式的计算结果为 `false`，则停止处理，该分支将视为 `false`。
以下示例的计算结果为 `true`，因为两个表达式的计算结果均为 `true`。
```
if:
and:
- stringEquals: 'test_string'
value: 'test_string'
- numberEquals: 1
value: 1
```
**分支：or**
`or` 分支语句对作为该分支子级的表达式列表执行操作，其中至少有一个表达式的计算结果必须为 `true`。Image Builder 按照表达式在列表中出现的顺序计算表达式。如果任何表达式的计算结果为 `true`，则停止处理，该分支将视为 `true`。
即使第一个表达式为 `false`，以下示例的计算结果仍为 `true`。
```
if:
or:
- stringEquals: 'test_string'
value: 'test_string_not_equal'
- numberEquals: 1
value: 1
```
**条件修饰符：not**
`not` 条件修饰符否定作为分支子级的条件语句。
当 `not` 修饰符否定 `stringEquals` 条件语句时，以下示例的计算结果为 `true`。
```
if:
not:
- stringEquals: 'test_string'
value: 'test_string_not_equal'
```
**条件语句：booleanEquals**
`booleanEquals` 比较运算符对布尔值进行比较，如果布尔值完全匹配，则返回 true。
以下示例可确定 `collectImageScanFindings` 是否启用。
```
if:
- booleanEquals: true
value: '$.imagebuilder.collectImageScanFindings'
```
**条件语句：stringEquals**
`stringEquals` 比较运算符对两个字符串进行比较，如果两个字符串完全匹配，则返回 true。如果其中一个值不是字符串，则 Image Builder 会在比较之前将其转换为字符串。
以下示例对平台系统变量进行了比较，以确定工作流是否在 Linux 平台上运行。
```
if:
- stringEquals: 'Linux'
value: '$.imagebuilder.Platform'
```
**条件语句：numberEquals**
`numberEquals` 比较运算符对两个数字进行比较，如果两个数字相等，则返回 true。要比较的数字必须为以下格式之一。
+ 整数
+ 浮点型
+ 与以下正则表达式模式相匹配的字符串：`^-?[0-9]+(\.)?[0-9]+$`。
以下示例比较的计算结果均为 `true`。
```
if:
# Value provider as a number
numberEquals: 1
value: '1'
# Comparison value provided as a string
numberEquals: '1'
value: 1
# Value provided as a string
numberEquals: 1
value: '1'
# Floats are supported
numberEquals: 5.0
value: 5.0
# Negative values are supported
numberEquals: -1
value: -1
```