本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 建立 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 | 工作流程文件的名稱。 | String | 否 | 
| description | 文件描述。 | String | 否 | 
| schemaVersion | 文件結構描述版本，目前為 1.0。 | String | 是 | 

**範例**

```
---
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  |  必要  |  Constraints  | 
| --- | --- | --- | --- | --- | 
| name | 參數名稱。 | String | 是 |  | 
| description | 參數描述。 | String | 否 |  | 
| 預設 | 如果未提供任何值，則為 參數的預設值。如果您未在參數定義中包含預設值，則在執行時間需要 參數值。 | 符合參數資料類型。 | 否 |  | 
| type | 參數的資料類型。如果您未在參數定義中包含資料類型，則參數類型預設為執行時間所需的字串值。 | String | 是 | 參數的資料類型必須是下列其中一項：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/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  |  必要  |  預設值  |  Constraints  | 
| --- | --- | --- | --- | --- | --- | 
| 動作 | 此步驟執行的工作流程動作。 | String | 是 |  | 必須是映像建置器工作流程文件的支援步驟動作。 | 
| `if`，後面接著一組修改`if`運算子的條件式陳述式。 | 條件式陳述式會將控制決策點的流程新增至工作流程步驟的內文。 | 口述 | 否 |  | Image Builder 支援以下條件式陳述式做為`if`運算子的修飾詞：[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/image-workflow-create-document.html) | 
| description | 步驟描述。 | String | 否 |  | 不允許空白字串。如果包含，長度必須為 1-1024 個字元。 | 
| inputs | 包含步驟動作需要執行的參數。您可以將索引鍵值指定為靜態值，或使用 JSONPath 變數解析為正確的資料類型。 | 口述 | 是 |  |  | 
| name | 步驟的名稱。此名稱在工作流程文件中必須是唯一的。 | String | 是 |  | 長度必須介於 3-128 個字元之間。<br />可以包含英數字元 和 `_`。無空格。 | 
| onFailure | 設定步驟失敗時要採取的動作，如下所示。[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/image-workflow-create-document.html) | String | 否 | `Abort` | `Abort` \| `Continue` | 
| rollbackEnabled | 設定在發生失敗時是否復原步驟。您可以使用靜態布林值或解析為布林值的動態 JSONPath 變數。 | Boolean | 否 | `true` | `true` \| `false` \| 或 JSONPath 變數，可解析為 true 或 false。 | 
| timeoutSeconds | 如果重試適用，步驟在失敗和重試之前執行的時間上限，以秒為單位。 | Integer | 否 | 視步驟動作的預設定義而定，如果適用的話。 | 不能超過步驟動作的逾時上限 | 
| waitSeconds | 步驟執行將暫停的時間，以秒為單位。 | Integer | 否 | 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 | 輸出的名稱。名稱在管道中包含的工作流程中必須是唯一的。 | String | 是 | 
| value | 輸出的值。字串的值可以是動態變數，例如來自步驟動作的輸出檔案。如需詳細資訊，請參閱[在工作流程文件中使用動態變數](wfdoc-dynamic-vars.md)。 | String | 是 | 

**範例**

使用步驟輸出為工作流程文件建立輸出映像 ID`createProdImage`。

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

請參閱下一個工作流程中的工作流程輸出。

```
$.workflowOutputs.outputImageId
```