本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 创建 YAML 工作流文档
<a name="image-workflow-create-document"></a>

YAML 格式定义文档为映像构建过程的构建和测试阶段配置输入、输出和工作流步骤。您可以从包含标准化步骤的模板开始，也可以从头开始定义自己的工作流。无论您使用模板还是从头开始，都可以自定义工作流以满足您的需求。

## YAML 工作流文档的结构
<a name="workflow-document-structure"></a>

Image Builder 用于执行映像构建和测试操作的 YAML 工作流文档的结构如下。
+ [工作流文档标识](#wfdoc-struct-ident)
+ [工作流文档输入参数](#wfdoc-struct-param)
+ [工作流文档步骤](#wfdoc-struct-step)
+ [工作流文档输出](#wfdoc-struct-output)

### 工作流文档标识
<a name="wfdoc-struct-ident"></a>

对工作流进行唯一标识。此部分可以包含以下属性。


|  字段  |  描述  |  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
```

### 工作流文档输入参数
<a name="wfdoc-struct-param"></a>

工作流文档的这一部分定义了调用方可以指定的输入参数。如果您没有任何参数，则可以省略此部分。如果您确实指定了参数，则每个参数可以包含以下属性。


|  字段  |  描述  |  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
```

### 工作流文档步骤
<a name="wfdoc-struct-step"></a>

为工作流指定最多 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 个字符之间。<br />可以包含字母数字字符和 `_`。不能包含空格。 | 
| 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` \| `Continue` | 
| rollbackEnabled | 配置发生故障时是否回滚该步骤。您可以使用静态布尔值或解析为布尔值的动态 JSONPath 变量。 | 布尔值 | 否 | `true` | `true` \| `false` \| 或者解析为真或假的 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"
```

### 工作流文档输出
<a name="wfdoc-struct-output"></a>

定义工作流的输出。每个输出都是一个键值对，可指定输出的名称和值。您可以使用输出在运行时导出后续工作流可以使用的数据。此部分是可选的。

您定义的每个输出都包含以下属性。


|  字段  |  描述  |  Type  |  必需  | 
| --- | --- | --- | --- | 
| name | 输出的名称。此名称在管道包含的工作流中必须具有唯一性。 | 字符串 | 是 | 
| 值 | 输出的值。字符串的值可以是动态变量，例如步骤操作的输出文件。有关更多信息，请参阅 [在工作流文档中使用动态变量](wfdoc-dynamic-vars.md)。 | 字符串 | 是 | 

**示例**

使用 `createProdImage` 步骤的步骤输出为工作流文档创建输出映像 ID。

```
outputs:
  - name: 'outputImageId'
    value: '$.stepOutputs.createProdImage.imageId'
```

请参阅下一个工作流中的工作流输出。

```
$.workflowOutputs.outputImageId
```