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

# 建立 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 個字元之間。 可以包含英數字元 和 `_`。無空格。  | 
|  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` \$1 `Continue`  | 
|  rollbackEnabled  |  設定在發生失敗時是否復原步驟。您可以使用靜態布林值或解析為布林值的動態 JSONPath 變數。  |  Boolean  |  否  |  `true`  |  `true` \$1 `false` \$1 或 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
```

# 工作流程文件支援的步驟動作
<a name="wfdoc-step-actions"></a>

本節包含 Image Builder 支援的步驟動作詳細資訊。本節中使用的術語

AMI  
Amazon Machine Image

ARN  
Amazon Resource Name

**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
<a name="wfdoc-step-action-apply-image-configurations"></a>

此步驟動作會將各種組態和整合套用至分散式 AMIs，例如授權組態、啟動範本組態、S3 匯出組態、EC2 Fast Launch 組態和 Systems Manager 參數組態。組態僅適用於來源帳戶中的分散式映像，但可跨帳戶套用的 SSM 參數組態除外。

**預設逾時：**360 分鐘

**最大逾時：**720 分鐘

**回復：**此步驟動作沒有回復。

**輸入：**下表包含此步驟動作支援的輸入。


| 輸入名稱 | 說明 | Type | 必要 | 預設 | Constraints | 
| --- | --- | --- | --- | --- | --- | 
| region | 映像區域。 | String | 是 |  |  | 
| licenseConfigurationArns | 映像的授權組態 ARN。 | 陣列 | 否 |  |  | 
| launchTemplateConfigurations |  | 陣列 | 否 |  |  | 
| launchTemplateConfigurations：launchTemplateId | 要套用至映像的啟動範本 ID。 | String | 是，如果launchTemplateConfigurations已指定 |  |  | 
| launchTemplateConfigurations：accountId | 要套用至映像的啟動範本帳戶 IDs。 | String | 否 |  |  | 
| launchTemplateConfigurations：setDefaultVersion | 映像的啟動範本預設版本設定。 | Boolean | 否 |  |  | 
| s3ExportConfiguration |  | 陣列 | 否 |  |  | 
| s3ExportConfiguration：roleName | 映像的 S3 匯出組態角色名稱。 | String | 是，如果s3ExportConfiguration已指定 |  |  | 
| s3ExportConfiguration：diskImageFormat | 映像的 S3 匯出組態磁碟映像格式。 | String | 是，如果s3ExportConfiguration已指定 |  | 允許的值 - VMDK\$1RAW\$1VHD | 
| s3ExportConfiguration：s3Bucket | 映像的 S3 匯出組態儲存貯體名稱。 | String | 是，如果s3ExportConfiguration已指定 |  |  | 
| s3ExportConfiguration：s3Prefix | 映像的 S3 匯出組態儲存貯體字首。 | String | 否 |  |  | 
| fastLaunchConfigurations | 映像的 EC2 Fast Launch 組態。 | 陣列 | 否 |  |  | 
| fastLaunchConfigurations：已啟用 |  為映像啟用/停用 EC2 Fast Launch。 | Boolean | 是，如果fastLaunchConfigurations已指定 |  |  | 
| fastLaunchConfigurations：snapshotConfiguration |  為映像啟用/停用 EC2 Fast Launch。 | Map | 否 |  |  | 
| fastLaunchConfigurations：snapshotConfiguration：targetResourceCount | 映像的 EC2 Fast Launch 目標資源計數。 | Integer | 否 |  |  | 
| fastLaunchConfigurations：maxParallelLaunches | 映像的 EC2 Fast Launch 平行啟動上限。 | Integer | 否 |  |  | 
| fastLaunchConfigurations：launchTemplate |  |  | 否 |  |  | 
| fastLaunchConfigurations：launchTemplate：launchTemplateId | 映像的 EC2 Fast Launch 啟動範本 ID。 | String | 否 |  |  | 
| fastLaunchConfigurations：launchTemplate：launchTemplateName | 映像的 EC2 Fast Launch 啟動範本名稱。 | String | 否 |  |  | 
| fastLaunchConfigurations：launchTemplate：launchTemplateVersion | 映像的 EC2 Fast Launch 啟動範本版本。 | String | 否 |  |  | 
| ssmParameterConfigurations | 映像的 SSM 參數組態。 | Map | 否 |  |  | 
| ssmParameterConfigurations：amiAccountId | 映像的 SSM 參數 AMI 帳戶 ID。 | String | 否 |  |  | 
| ssmParameterConfigurations：parameterName | 映像的 SSM 參數名稱。 | String | 是，如果ssmParameterConfigurations已指定 |  |  | 
| ssmParameterConfigurations：dataType | 映像的 SSM 參數資料類型。 | String | 否 |  | 允許的值 - text\$1aws：ec2：image) | 

**輸出：**下表包含此步驟動作的輸出。


| 輸出名稱 | 說明 | Type | 
| --- | --- | --- | 
| configuredImages | 已設定映像的清單。 | 陣列 | 
| configuredImages：accountId | 分散式映像的目的地帳戶 ID。 | String | 
| configuredImages：name | AMI 的名稱。 | String | 
| configuredImages：amiId | 分散式映像的 AMI ID。 | String | 
| configuredImages：dateStarted | 分佈開始的 UTC 時間。 | String | 
| configuredImages：dateStopped | 分佈完成時的 UTC 時間。 | String | 
| configuredImages：step | 分佈停止的步驟。 | 已完成\$1AssociateLicensesRunning\$1UpdateLaunchTemplateRunning\$1PutSsmParametersRunning\$1UpdateFastLaunchConfiguration\$1ExportAmiQueued\$1ExportAmiRunning | 
| configuredImages：region | 分散式映像的色調 AWS  | String | 
| configuredImages：status | 分佈狀態。 | 已完成 \$1 失敗 \$1 取消 \$1 TimedOut | 
| configuredImages：errorMessage  | 錯誤訊息，如果有的話。 | String | 

**範例**

在工作流程文件中指定步驟動作。

```
- name: ApplyImageConfigurations
  action: ApplyImageConfigurations
  onFailure: Abort
  inputs:
    distributedImages.$: $.stepOutputs.DistributeImageStep.distributedImages
```

使用工作流程文件中步驟動作值的輸出。

```
$.stepOutputs.ApplyImageConfigurationsStep.configuredImages
```

## BootstrapInstanceForContainer
<a name="wfdoc-step-action-bootstrap-container"></a>

此步驟動作會執行服務指令碼，以使用執行容器工作流程的最低需求來引導執行個體。Image Builder 使用 Systems Manager API **sendCommand**中的 來執行此指令碼。如需詳細資訊，請參閱[AWS Systems Manager 執行命令](https://docs.aws.amazon.com/systems-manager/latest/userguide/execute-remote-commands.html)。

**注意**  
引導指令碼會安裝 AWS CLI 和 Docker 套件，這些套件是 Image Builder 成功建置 Docker 容器的先決條件。如果您未包含此步驟動作，映像建置可能會失敗。

**預設逾時：**60 分鐘

**最大逾時：**720 分鐘

**回復：**此步驟動作沒有回復。

**輸入：**下表包含此步驟動作支援的輸入。


| 輸入名稱 | 說明 | Type | 必要 | 預設 | Constraints | 
| --- | --- | --- | --- | --- | --- | 
| instanceId | 要引導的執行個體 ID。 | String | 是 |  | 這必須是啟動此工作流程執行個體之工作流程步驟的輸出執行個體 ID。 | 

**輸出：**下表包含此步驟動作的輸出。


| 輸出名稱 | 說明 | Type | 
| --- | --- | --- | 
| runCommandId | 在執行個體上執行sendCommand引導指令碼的 Systems Manager ID。 | String | 
| status | 從 Systems Manager 傳回的狀態sendCommand。 | String | 
| output | 從 Systems Manager 傳回的輸出sendCommand。 | String | 

**範例**

在工作流程文件中指定步驟動作。

```
- name: ContainerBootstrapStep
  action: BootstrapInstanceForContainer
  onFailure: Abort
  inputs:
      instanceId.$: $.stepOutputs.LaunchStep.instanceId
```

使用工作流程文件中步驟動作值的輸出。

```
$.stepOutputs.ContainerBootstrapStep.status
```

## CollectImageMetadata
<a name="wfdoc-step-action-collect-image-metadata"></a>

此步驟動作僅適用於建置工作流程。

EC2 Image Builder 會在啟動的 EC2 執行個體上執行 [AWS Systems Manager (Systems Manager) Agent](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 | 必要 | 預設 | Constraints | 
| --- | --- | --- | --- | --- | --- | 
| instanceId | 要套用中繼資料設定的建置執行個體。 | String | 是 |  | 這必須是啟動此工作流程建置執行個體之工作流程步驟的輸出執行個體 ID。 | 

**輸出：**下表包含此步驟動作的輸出。


| 輸出名稱 | 說明 | Type | 
| --- | --- | --- | 
| osVersion | 從建置執行個體收集的作業系統名稱和版本。 | String | 
| associationId | 用於庫存收集的 Systems Manager 關聯 ID。 | String | 

**範例**

在工作流程文件中指定步驟動作。

```
- name: CollectMetadataStep
  action: CollectImageMetadata
  onFailure: Abort
  inputs:
      instanceId: $.stepOutputs.LaunchStep.instanceId
```

使用工作流程文件中步驟動作的輸出。

```
$.stepOutputs.CollectMetadataStep.osVersion
```

## CollectImageScanFindings
<a name="wfdoc-step-action-collect-findings"></a>

如果您的帳戶已啟用 Amazon Inspector，且您的管道已啟用映像掃描，此步驟動作會收集 Amazon Inspector 為您的測試執行個體回報的映像掃描問題清單。此步驟動作不適用於建置工作流程。

**預設逾時：**120 分鐘

**最大逾時：**720 分鐘

**回復：**此步驟動作沒有回復。

**輸入：**下表包含此步驟動作支援的輸入。


| 輸入名稱 | 說明 | Type | 必要 | 預設 | Constraints | 
| --- | --- | --- | --- | --- | --- | 
| instanceId | 執行掃描之執行個體的 ID。 | String | 是 |  | 這必須是啟動此工作流程執行個體之工作流程步驟的輸出執行個體 ID。 | 

**輸出：**下表包含此步驟動作的輸出。


| 輸出名稱 | 說明 | Type | 
| --- | --- | --- | 
| runCommandId | sendCommand 執行指令碼以收集問題清單的 Systems Manager ID。 | String | 
| status | 從 Systems Manager 傳回的狀態sendCommand。 | String | 
| output | 從 Systems Manager 傳回的輸出sendCommand。 | String | 

**範例**

在工作流程文件中指定步驟動作。

```
- name: CollectFindingsStep
  action: CollectImageScanFindings
  onFailure: Abort
  inputs:
      instanceId.$: $.stepOutputs.LaunchStep.instanceId
```

使用工作流程文件中步驟動作值的輸出。

```
$.stepOutputs.CollectFindingsStep.status
```

## CreateImage
<a name="wfdoc-step-action-create-img-from-inst"></a>

此步驟動作會使用 Amazon EC2 `CreateImage` API 從執行中的執行個體建立映像。在建立程序期間，步驟動作會視需要等待，以確認資源已達到正確的狀態，再繼續執行。

**預設逾時：**720 分鐘

**最大逾時：**3 天

**回復：**此步驟動作沒有回復。

**輸入：**下表包含此步驟動作支援的輸入。


| 輸入名稱 | 說明 | Type | 必要 | 預設 | Constraints | 
| --- | --- | --- | --- | --- | --- | 
| instanceId | 要從中建立新映像的執行個體。 | String | 是 |  | 此步驟開始時，所提供執行個體 ID 的執行個體必須處於 running 狀態。 | 

**輸出：**下表包含此步驟動作的輸出。


| 輸出名稱 | 說明 | Type | 
| --- | --- | --- | 
| imageId | 建立之映像的 AMI ID。 | String | 

**範例**

在工作流程文件中指定步驟動作。

```
- name: CreateImageFromInstance
  action: CreateImage
  onFailure: Abort
  inputs:
      instanceId.$: "i-1234567890abcdef0"
```

使用工作流程文件中步驟動作值的輸出。

```
$.stepOutputs.CreateImageFromInstance.imageId
```

## DistributeImage
<a name="wfdoc-step-action-distribute-image"></a>

此步驟動作會將 AMI 分配至指定的區域和帳戶。它會根據 CreateImage 或 CreateImagePipeline APIs 的請求中提供的分佈組態，或工作流程中提供的自訂分佈設定，在目標區域和帳戶中建立 AMI 的副本，以覆寫分佈組態中的設定。

**預設逾時：**360 分鐘

**最大逾時：**720 分鐘

**回復：**此步驟動作沒有回復。

**輸入：**下表包含此步驟動作支援的輸入。


| 輸入名稱 | 說明 | Type | 必要 | 預設 | Constraints | 
| --- | --- | --- | --- | --- | --- | 
| region | 要分發映像的區域清單。 | String | 是 |  | 長度下限為 1。長度上限為 1024。 | 
| name | 分佈組態的名稱。 | String | 否 |  |  | 
| description | 分佈組態的分佈。 | String | 否 |  |  | 
| targetAccountIds | 要分發映像的帳戶 IDs。 | 陣列 | 否 |  |  | 
| amiTags | 分佈組態的標籤。 | Map | 否 |  |  | 
| kmsKeyId | 要套用至分散式映像的 KMS 金鑰。 | String | 否 |  |  | 

**輸出：**下表包含此步驟動作的輸出。


| 輸出名稱 | 說明 | Type | 
| --- | --- | --- | 
| distributedImages | 分散式映像的清單 | 陣列 | 
| distributedImages：region | 分散式映像的色調 AWS 區域。 | String | 
| distributedImages：name | AMI 的名稱。 | String | 
| distributedImages：amiId | 分散式映像的 AMI ID。 | String | 
| distributedImages：accountId | 分散式映像的目的地帳戶 ID。 | String | 
| distributedImages：dateStarted | 分佈開始的 UTC 時間。 | String | 
| distributedImages：dateStopped | 分佈完成時的 UTC 時間。 | String | 
| distributedImages：status | 分佈狀態。 | 已完成 \$1 失敗 \$1 取消 \$1 TimedOut | 
| distributedImages：step | 分佈停止的步驟。 | 已完成\$1CopyAmiRunning | 
| distributedImages：errorMessage  | 錯誤訊息，如果有的話。 | String | 

**範例**

在工作流程文件中指定步驟動作。

```
- 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
<a name="wfdoc-step-action-exec-components"></a>

此步驟動作會針對正在建置的目前映像，執行配方中指定的元件。建置工作流程會在建置執行個體上執行建置元件。測試工作流程只會在測試執行個體上執行測試元件。

Image Builder 使用 Systems Manager API **sendCommand**中的 來執行元件。如需詳細資訊，請參閱[AWS Systems Manager 執行命令](https://docs.aws.amazon.com/systems-manager/latest/userguide/execute-remote-commands.html)。

**預設逾時：**720 分鐘

**最大逾時：**1 天

**回復：**此步驟動作沒有回復。

**輸入：**下表包含此步驟動作支援的輸入。


| 輸入名稱 | 說明 | Type | 必要 | 預設 | Constraints | 
| --- | --- | --- | --- | --- | --- | 
| instanceId | 元件應執行的執行個體 ID。 | String | 是 |  | 這必須是啟動此工作流程執行個體之工作流程步驟的輸出執行個體 ID。 | 

**輸出：**下表包含此步驟動作的輸出。


| 輸出名稱 | 說明 | Type | 
| --- | --- | --- | 
| runCommandId | 在執行個體上執行sendCommand元件的 Systems Manager ID。 | String | 
| status | 從 Systems Manager 傳回的狀態sendCommand。 | String | 
| output | 從 Systems Manager 傳回的輸出sendCommand。 | String | 

**範例**

在工作流程文件中指定步驟動作。

```
- name: ExecComponentsStep
  action: ExecuteComponents
  onFailure: Abort
  inputs:
      instanceId: $.stepOutputs.LaunchStep.instanceId
```

使用工作流程文件中步驟動作的輸出。

```
$.stepOutputs.ExecComponentsStep.status
```

## ExecuteStateMachine
<a name="wfdoc-step-action-exec-state-machine"></a>

此步驟動作會從映像建置器工作流程開始執行 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 | 必要 | 預設 | Constraints | 
| --- | --- | --- | --- | --- | --- | 
| stateMachineArn | 要執行之 Step Functions 狀態機器的 ARN。 | String | 是 |  | 必須是有效的狀態機器 ARN。 | 
| input | 要提供給狀態機器的 JSON 輸入資料。 | String | 否 | \$1\$1 | 必須是有效的 JSON 字串，長度上限為：16 KiB。 | 

**輸出：**下表包含此步驟動作的輸出。


| 輸出名稱 | 說明 | Type | 
| --- | --- | --- | 
| executionArn | 狀態機器執行的 ARN。 | String | 
| output | 狀態機器執行的輸出。 | String | 

**所需的 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
<a name="wfdoc-step-action-launch-instance"></a>

此步驟動作會在 中啟動執行個體， AWS 帳戶 並等到 Systems Manager 代理程式在執行個體上執行，再繼續進行下一個步驟。啟動動作會使用配方中的設定，以及與映像相關聯的基礎設施組態資源。例如，要啟動的執行個體類型來自基礎設施組態。輸出是其啟動之執行個體的執行個體 ID。

`waitFor` 輸入會設定滿足步驟完成要求的條件。

**預設逾時：**75 分鐘

**最大逾時：**720 分鐘

**回復：**對於建置執行個體，回復會執行您在基礎設施組態資源中設定的動作。根據預設，如果映像建立失敗，組建執行個體會終止。不過，基礎設施組態中有一個設定來保留建置執行個體以進行故障診斷。

**輸入：**下表包含此步驟動作支援的輸入。


| 輸入名稱 | 說明 | Type | 必要 | 預設 | Constraints | 
| --- | --- | --- | --- | --- | --- | 
| imageIdOverride | 用來啟動執行個體的映像 | String | 否 |  組建階段：映像配方基礎映像 測試階段：從建置階段輸出 AMI  | 必須是有效的 AMI ID | 
| instanceTypesOverride | Image Builder 會嘗試清單中的每個執行個體類型，直到找到成功啟動的執行個體 | 字串的清單 | 否 | 基礎設施組態中指定的執行個體類型 | 必須是有效的執行個體類型 | 
| waitFor | 在完成工作流程步驟並繼續進行下一個步驟之前等待的條件 | String | 是 |  | Image Builder 支援 ssmAgent。 | 

**輸出：**下表包含此步驟動作的輸出。


| 輸出名稱 | 說明 | Type | 
| --- | --- | --- | 
| instanceId | 啟動之執行個體的執行個體 ID。 | String | 

**範例**

在工作流程文件中指定步驟動作。

```
- name: LaunchStep
  action: LaunchInstance
  onFailure: Abort
  inputs:
    waitFor: ssmAgent
```

使用工作流程文件中步驟動作的輸出。

```
$.stepOutputs.LaunchStep.instanceId
```

## ModifyImageAttributes
<a name="wfdoc-step-action-modify-image-attributes"></a>

此步驟動作會修改分散式 AMIs的屬性，例如啟動許可和其他 AMI 屬性。它在已分發至目標區域和帳戶的 AMIs 上運作。

**預設逾時：**120 分鐘

**最大逾時：**180 分鐘

**回復：**此步驟動作沒有回復。

**輸入：**下表包含此步驟動作支援的輸入。


| 輸入名稱 | 說明 | Type | 必要 | 預設 | Constraints | 
| --- | --- | --- | --- | --- | --- | 
| region | 影像的區域。 | String | 是 |  |  | 
| launchPermission |  |  | 否 |  |  | 
| launchPermission：userIds | 在映像的啟動許可中要修改的使用者 IDs。 | String | 否 |  |  | 
| launchPermission：userGroups | 在映像的啟動許可中要修改的使用者群組。 | String | 否 |  |  | 
| launchPermission：organizationArns | 在映像的啟動許可中要修改 AWS 的組織 ARNs。 | String | 否 |  |  | 
| launchPermission：organizationalUnitArns | 在映像的啟動許可中要修改 AWS 的組織單位 ARNs。 | String | 否 |  |  | 

**輸出：**下表包含此步驟動作的輸出。


| 輸出名稱 | 說明 | Type | 
| --- | --- | --- | 
| modifiedImages | 修改後的映像清單 | 陣列 | 
| modifiedImages：accountId | 分散式映像的目的地帳戶 ID。 | String | 
| modifiedImages：name | AMI 的名稱。 | String | 
| modifiedImages：amiId | 分散式映像的 AMI ID。 | String | 
| modifiedImages：dateStarted | 分佈開始的 UTC 時間。 | String | 
| modifiedImages：dateStopped | 分佈完成時的 UTC 時間。 | String | 
| modifiedImages：step | 分佈停止的步驟。 | 已完成\$1ModifyAmiRunning | 
| modifiedImages：region | 影像的色調 AWS 區域。 | String | 
| modifiedImages：status | 分佈狀態。 | 已完成 \$1 失敗 \$1 取消 \$1 TimedOut | 
| modifiedImages：errorMessage  | 錯誤訊息，如果有的話。 | String | 

**範例**

在工作流程文件中指定步驟動作。

```
- name: ModifyImageAttributes
  action: ModifyImageAttributes
  onFailure: Abort
  inputs:
    distributedImages.$: $.stepOutputs.DistributeImageStep.distributedImages
```

使用工作流程文件中步驟動作值的輸出。

```
$.stepOutputs.ModifyImageAttributesStep.modifiedImages
```

## RegisterImage
<a name="wfdoc-step-action-register-image"></a>

此步驟動作會使用 Amazon EC2 RegisterImage API 註冊新的 Amazon Machine Image (AMI)。 RegisterImage 它可讓您從現有的快照或一組快照建立 AMI，並指定各種影像屬性。

**預設逾時：**540 分鐘

**最大逾時：**720 分鐘

**回復：**此步驟動作沒有回復。

**輸入：**下表包含此步驟動作支援的輸入。


| 輸入名稱 | 說明 | Type | 必要 | 預設 | Constraints | 
| --- | --- | --- | --- | --- | --- | 
| 架構 | AMI 的架構。 | String | 否 |  | 有效值：i386、x86\$164、arm64、x86\$164\$1mac、arm64\$1mac | 
| blockDeviceMapping | AMI 的區塊型設備映射項目。 | 陣列 | 否 |  |  | 
| bootMode | AMI 的開機模式。 | String | 否 |  | 有效值： legacy-bios、uefi、uefi-preferred | 
| description | AMI 的說明。 | String | 否 |  |  | 
| enaSupport | 是否已啟用與 ENA 的增強型聯網。 | Boolean | 否 |  |  | 
| imageLocation | AMI 資訊清單的位置。 | String | 否 |  | S3-backed AMIs | 
| imdsSupport | IMDSv2 支援層級。 | String | 否 |  | 有效值：v2.0 | 
| includeSnapshotTags | 是否包含區塊型設備映射中定義之第一個快照的標籤。 | Boolean | 否 | FALSE |  設為 true 時，標籤會包含如下： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/imagebuilder/latest/userguide/wfdoc-step-actions.html)  | 
| kernelId | 要使用的核心 ID。 | String | 否 |  |  | 
| ramdiskId | 要使用的 RAM 磁碟 ID。 | String | 否 |  |  | 
| rootDeviceName | 根裝置的裝置名稱。 | String | 否 |  | 範例：/dev/sda1 | 
| sriovNetSupport | 使用 Intel 82599 VF 介面增強聯網。 | String | 否 |  |  | 
| tpmSupport | TPM 版本支援。 | String | 否 |  | 有效值：v2.0 | 
| uefiData | Base64-encoded UEFI 資料。 | String | 否 |  |  | 
| virtualizationType | 虛擬化類型。 | String | 否 |  | 有效值：hvm、paravirtual | 

**輸出：**下表包含此步驟動作的輸出。


| 輸出名稱 | 說明 | Type | 
| --- | --- | --- | 
| imageId | 已註冊映像的 AMI ID。 | String | 

**需要 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
<a name="wfdoc-step-action-run-command"></a>

此步驟動作會為您的工作流程執行命令文件。Image Builder 會使用 Systems Manager API **sendCommand**中的 為您執行。如需詳細資訊，請參閱[AWS Systems Manager 執行命令](https://docs.aws.amazon.com/systems-manager/latest/userguide/run-command.html)。

**預設逾時：**720 分鐘

**最大逾時：**720 分鐘

**回復：**此步驟動作沒有回復。

**輸入：**下表包含此步驟動作支援的輸入。


| 輸入名稱 | 說明 | Type | 必要 | 預設 | Constraints | 
| --- | --- | --- | --- | --- | --- | 
| instanceId | 執行命令文件的執行個體 ID。 | String | 是 |  | 這必須是啟動此工作流程執行個體之工作流程步驟的輸出執行個體 ID。 | 
| documentName | 要執行的 Systems Manager 命令文件名稱。 | String | 是 |  |  | 
| parameters | 命令文件所需任何參數的索引鍵值對清單。 | 字典 <string， list<string>> | 有條件 |  |  | 
| documentVersion | 要執行的命令文件版本。 | String | 否 | \$1DEFAULT |  | 

**輸出：**下表包含此步驟動作的輸出。


| 輸出名稱 | 說明 | Type | 
| --- | --- | --- | 
| runCommandId | 在執行個體上執行sendCommand命令文件的 Systems Manager ID。 | String | 
| status | 從 Systems Manager 傳回的狀態sendCommand。 | String | 
| output | 從 Systems Manager 傳回的輸出sendCommand。 | 字串清單 | 

**範例**

在工作流程文件中指定步驟動作。

```
- name: RunCommandDoc
  action: RunCommand
  onFailure: Abort
  inputs:
    documentName: SampleDocument
    parameters:
        osPlatform: 
          - "linux"
    instanceId.$: $.stepOutputs.LaunchStep.instanceId
```

使用工作流程文件中步驟動作值的輸出。

```
$.stepOutputs.RunCommandDoc.status
```

## RunSysPrep
<a name="wfdoc-step-action-run-sysprep"></a>

此步驟動作會使用 Systems Manager API **sendCommand**中的 ，在建置執行個體關閉快照之前執行 Windows 執行個體`AWSEC2-RunSysprep`的文件。這些動作遵循[AWS 強化和清理映像的最佳實務](https://aws.amazon.com/articles/public-ami-publishing-hardening-and-clean-up-requirements/)。

**預設逾時：**60 分鐘

**最大逾時：**720 分鐘

**回復：**此步驟動作沒有回復。

**輸入：**下表包含此步驟動作支援的輸入。


| 輸入名稱 | 說明 | Type | 必要 | 預設 | Constraints | 
| --- | --- | --- | --- | --- | --- | 
| instanceId | 要執行AWSEC2-RunSysprep文件的執行個體 ID。 | String | 是 |  | 這必須是啟動此工作流程執行個體之工作流程步驟的輸出執行個體 ID。 | 

**輸出：**下表包含此步驟動作的輸出。


| 輸出名稱 | 說明 | Type | 
| --- | --- | --- | 
| runCommandId | 在執行個體上執行sendCommandAWSEC2-RunSysprep文件的 Systems Manager ID。 | String | 
| status | 從 Systems Manager 傳回的狀態sendCommand。 | String | 
| output | 從 Systems Manager 傳回的輸出sendCommand。 | String | 

**範例**

在工作流程文件中指定步驟動作。

```
- name: RunSysprep
  action: RunSysPrep
  onFailure: Abort
  inputs:
      instanceId.$: $.stepOutputs.LaunchStep.instanceId
```

使用工作流程文件中步驟動作值的輸出。

```
$.stepOutputs.RunSysprep.status
```

## SanitizeInstance
<a name="wfdoc-step-action-sanitize-instance"></a>

此步驟動作會在建置執行個體關閉快照之前，為 Linux 執行個體執行建議的淨化指令碼。淨化指令碼有助於確保最終映像遵循安全最佳實務，並移除不應傳遞至快照的建置成品或設定。如需指令碼的詳細資訊，請參閱 [必要的建置後清除](security-best-practices.md#post-build-cleanup)。此步驟動作不適用於容器映像。

Image Builder 使用 Systems Manager API **sendCommand**中的 來執行此指令碼。如需詳細資訊，請參閱[AWS Systems Manager 執行命令](https://docs.aws.amazon.com/systems-manager/latest/userguide/execute-remote-commands.html)。

**預設逾時：**60 分鐘

**最大逾時：**720 分鐘

**回復：**此步驟動作沒有回復。

**輸入：**下表包含此步驟動作支援的輸入。


| 輸入名稱 | 說明 | Type | 必要 | 預設 | Constraints | 
| --- | --- | --- | --- | --- | --- | 
| instanceId | 要淨化的執行個體 ID。 | String | 是 |  | 這必須是啟動此工作流程執行個體之工作流程步驟的輸出執行個體 ID。 | 

**輸出：**下表包含此步驟動作的輸出。


| 輸出名稱 | 說明 | Type | 
| --- | --- | --- | 
| runCommandId | 在執行個體上執行sendCommand淨化指令碼的 Systems Manager ID。 | String | 
| status | 從 Systems Manager 傳回的狀態sendCommand。 | String | 
| output | 從 Systems Manager 傳回的輸出sendCommand。 | String | 

**範例**

在工作流程文件中指定步驟動作。

```
- name: SanitizeStep
  action: SanitizeInstance
  onFailure: Abort
  inputs:
      instanceId: $.stepOutputs.LaunchStep.instanceId
```

使用工作流程文件中步驟動作值的輸出。

```
$.stepOutputs.SanitizeStep.status
```

## TerminateInstance
<a name="wfdoc-step-action-terminate-instance"></a>

此步驟動作會使用做為輸入傳入的執行個體 ID 來終止執行個體。

**預設逾時：**30 分鐘

**最大逾時：**720 分鐘

**回復：**此步驟動作沒有回復。

**輸入：**下表包含此步驟動作支援的輸入。


| 輸入名稱 | 說明 | Type | 必要 | 預設 | Constraints | 
| --- | --- | --- | --- | --- | --- | 
| instanceId | 要終止的執行個體 ID。 | String | 是 |  |  | 

**輸出：**此步驟動作沒有輸出。

**範例**

在工作流程文件中指定步驟動作。

```
- name: TerminateInstance
  action: TerminateInstance
  onFailure: Continue
  inputs:
      instanceId.$: i-1234567890abcdef0
```

## WaitForAction
<a name="wfdoc-step-action-waitfor"></a>

此步驟動作會暫停執行中的工作流程，並等待從映像建置器 **SendWorkflowStepAction** API 動作接收外部動作。此步驟會將 EventBridge 事件發佈至具有詳細資訊類型 的預設 EventBridge 事件匯流排`EC2 Image Builder Workflow Step Waiting`。如果您提供 SNS 主題 ARN，步驟也可以傳送 SNS 通知，或者如果您提供 Lambda 函數名稱，也可以非同步叫用 Lambda 函數。

**預設逾時：**3 天

**最大逾時：**7 天

**回復：**此步驟動作沒有回復。

**輸入：**下表包含此步驟動作支援的輸入。


| 輸入名稱 | 說明 | Type | 必要 | 預設 | Constraints | 
| --- | --- | --- | --- | --- | --- | 
| snsTopicArn | 工作流程步驟待定時傳送通知的選用 SNS 主題 ARN。 | String | 否 |  |  | 
| lambdaFunctionName | Lambda 函數的選用名稱或 ARN，可在工作流程步驟待定時以非同步方式叫用。 | String | 否 |  |  | 
| payload | 用作 SNS 訊息和 Lambda 承載的 JSON 字串。如果提供，自訂承載會包裝在預設訊息/承載中，分別用於 SNS 和 Lambda。如果未提供， 會產生預設訊息/承載。 | String | 否 |  | 必須是有效的 JSON 字串，上限為 16 KiB | 

**輸出：**下表包含此步驟動作的輸出。


| 輸出名稱 | 說明 | Type | 
| --- | --- | --- | 
| 動作 | SendWorkflowStepAction API 動作傳回的動作。 | 字串 (RESUME 或 STOP) | 
| reason | 傳回動作的原因。 | String | 

**需要 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
<a name="wfdoc-step-action-wait-for-ssm-agent"></a>

在預期的無回應期間之後，此步驟動作會等待 EC2 執行個體變成可由 AWS Systems Manager 管理。對於已知執行個體中斷的工作流程特別重要，例如系統重新啟動、作業系統升級，或暫時中斷執行個體與 SSM 連線的平台特定操作。Image Builder 會監控執行個體，直到它重新取得 SSM 連線或逾時為止。

**預設逾時：**60 分鐘

**最大逾時：**180 分鐘

**回復：**此步驟動作沒有回復。

**輸入：**下表包含此步驟動作支援的輸入。


| 輸入名稱 | 說明 | Type | 必要 | 預設 | Constraints | 
| --- | --- | --- | --- | --- | --- | 
| instanceId | 要監控 SSM 連線的執行個體 ID。 | String | 是 |  | 必須是有效的 EC2 執行個體 ID | 

**輸出：**下表包含此步驟動作的輸出。


| 輸出名稱 | 說明 | Type | 
| --- | --- | --- | 
| status | SSM Agent 的連線狀態。 | String | 

**範例**

在工作流程文件中指定步驟動作。

```
- name: WaitForInstanceAfterReboot
  action: WaitForSSMAgent
  onFailure: Abort
  timeoutInSeconds: 900
  inputs:
    instanceId.$: $.stepOutputs.LaunchStep.instanceId
```

使用工作流程文件中步驟動作值的輸出。

```
$.stepOutputs.WaitForInstanceAfterReboot.Status
```

# 在工作流程文件中使用動態變數
<a name="wfdoc-dynamic-vars"></a>

您可以使用工作流程文件中的動態變數來表示影像建立程序在執行時間變化的值。動態變數的字串插補可讓您在 JSON 字串等結構化內容中嵌入 JSONPath 表達式。當您需要在複雜的承載中將執行時間值傳遞至 `ExecuteStateMachine`或 等步驟動作時，此功能特別有用`WaitForAction`。

若要對動態變數使用字串插補，請在字串內容`"{{...}}"`中以雙大括號包裝 JSONPath 運算式。只有以雙大括號包裝的 JSONPath 表達式才會處理為變數。任何未包裝在雙大括號中的 JSONPath 表達式都會視為常值字串內容。

**JSONPath 動態工作流程變數語法**

```
$.<document structure>.[<step name>.]<variable name>
```

動態變數值以 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 }}` - 從 CreateImageFromInstance 步驟解析為實際影像 ID
+ `{{ $.imagebuilder.dateTime }}` - 解決目前建置時間戳記的問題。[使用映像建置器系統變數](#wfdoc-ib-vars) 如需您可以使用的映像建置器系統變數清單，請參閱 。
+ `{{ $.stepOutputs.LaunchStep.instanceType }}` - 解析為 LaunchStep 中使用的執行個體類型

之類的常值字串`"region": "us-east-1"`保持不變。

**注意**  
字串插補適用於工作流程文件中的任何字串內容，包括使用 YAML 管道 (`|`) 運算子的多行字串。大括號需求可做為逸出機制，以清楚區分 JSONPath 變數和文字內容。

## 使用映像建置器系統變數
<a name="wfdoc-ib-vars"></a>

Image Builder 提供下列系統變數，您可以在工作流程文件中使用：


|  變數名稱  |  說明  |  Type  |  範例值  | 
| --- | --- | --- | --- | 
|  cloudWatchLogGroup  |  輸出日誌的 CloudWatch Logs 群組名稱。 格式：`/aws/imagebuilder/<recipe-name>`  |  String  |  `/aws/imagebuilder/sampleImageRecipe`  | 
|  cloudWatchLogStream  |  輸出日誌的 CloudWatch Logs 串流名稱。  |  String  |  *1.0.0/1*  | 
|  collectImageMetadata  |  指示 Image Builder 是否收集執行個體中繼資料的設定。  |  Boolean  |  `true` \$1 `false`  | 
|  collectImageScanFindings  |  可讓映像建置器收集映像掃描問題清單的設定的目前值。  |  Boolean  |  `true` \$1 `false`  | 
|  imageBuildNumber  |  映像的建置版本編號。  |  Integer  |  *1*  | 
|  imageId  |  基礎映像的 AMI ID。  |  String  |  *ami-1234567890abcdef1*  | 
|  imageName  |  影像的名稱。  |  String  |  *sampleImage*  | 
|  imageType  |  影像輸出類型。  |  String  |  `AMI` \$1 `Docker`  | 
|  imageVersionNumber  |  映像的版本編號。  |  String  |  *1.0.0*  | 
|  instanceProfileName  |  Image Builder 用來啟動建置和測試執行個體的執行個體描述檔角色名稱。  |  String  |  *SampleImageBuilderInstanceProfileRole*  | 
|  平台  |  建置映像的作業系統平台。  |  String  |  `Linux` \$1 `Windows` \$1 `MacOS`  | 
|  s3Logs  |  包含映像建置器寫入之 S3 日誌組態的 JSON 物件。  |  JSON 物件  |  \$1's3Logs'：\$1's3BucketName'： '*sample-bucket*'， 's3KeyPrefix'： '*ib-logs*'\$1\$1  | 
|  securityGroups  |  適用於建置和測試執行個體的安全群組 IDs。  |  列出 【字串】  |  *【sg-1234567890abcdef1、sg-11112222333344445】*  | 
|  sourceImageARN  |  工作流程用於建置和測試階段之映像建置器映像資源的 Amazon Resource Name (ARN)。  |  String  |  arn：aws：imagebuilder：*us-east-1*：*111122223333*：image/*sampleImage*/*1.0.0/1*  | 
|  subnetId  |  要啟動建置和測試執行個體的子網路 ID。  |  String  |  *subnet-1234567890abcdef1*  | 
|  terminateInstanceOnFailure  |  指示 Image Builder 在故障時終止執行個體或保留執行個體以進行故障診斷的設定的目前值。  |  Boolean  |  `true` \$1 `false`  | 
|  workflowPhase  |  正在執行工作流程的目前階段。  |  String  |  `Build` \$1 `Test`  | 
|  workingDirectory  |  工作目錄的路徑。  |  String  |  `/tmp`  | 

# 在工作流程步驟中使用條件式陳述式
<a name="wfdoc-conditional-statements"></a>

條件式陳述式以`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)。
+ 每個分支陳述式必須至少有一個子條件式陳述式，但不得超過十個。
+ 條件式修飾詞僅在一個子條件陳述式上運作。

## 條件式陳述式中的巢狀層級
<a name="wfdoc-conditional-structure"></a>

條件式陳述式在其自身區段中的多個層級運作。例如，`if`陳述式屬性會顯示在工作流程文件中與步驟名稱和動作相同的層級。這是條件式陳述式的基礎。

您最多可以指定四個層級的條件式陳述式，但父層級只能顯示一個陳述式。所有其他分支陳述式、條件修飾詞或條件運算子會從該處縮排，每個層級一個縮排。

下列大綱顯示條件式陳述式的巢狀層級數量上限。

```
base:
  parent: 
    - child (level 2)
        - child (level 3)
            child (level 4)
```

`if` 屬性  
`if` 屬性會將條件式陳述式指定為文件屬性。這是層級零。

父層級  
這是條件式陳述式的第一個巢狀層級。此層級只能有一個陳述式。如果您不需要分支或修飾詞，這可以是沒有子陳述式的條件式運算子。除了條件式運算子之外，此層級不會使用破折號表示法。

子層級  
層級 2 到 4 視為子層級。子陳述式可以包含分支陳述式、條件式修飾詞或條件式運算子。

**範例：巢狀層級**  
下列範例顯示條件式陳述式中的關卡數量上限。

```
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"
```

**巢狀化規則**
+ 子層級的每個分支或修飾詞都會啟動新的層級。
+ 每個關卡都會縮排。
+ 最多可以有四個層級，包括父層級的一個陳述式、修飾詞或運算子，以及最多三個額外的層級。

## 條件式陳述式範例
<a name="wfdoc-conditional-examples"></a>

此範例群組顯示條件式陳述式的各種層面。

**分支： 和**  
`and` 分支陳述式會在分支子項的表達式清單上運作，所有表達式都必須評估為 `true`。Image Builder 會依運算式出現在清單中的順序進行評估。如果有任何表達式評估為 `false`，則處理會停止，且分支會被視為 `false`。

下列範例會評估為 `true`，因為兩個表達式都會評估為 `true`。

```
if:
  and:
    - stringEquals: 'test_string'
      value: 'test_string'
    - numberEquals: 1
      value: 1
```

**分支： 或**  
`or` 分支陳述式會在分支的子系表達式清單上運作，其中至少有一個必須評估為 `true`。Image Builder 會依運算式出現在清單中的順序進行評估。如果任何表達式評估為 `true`，則處理會停止，且分支會被視為 `true`。

下列範例會評估為 `true`，即使第一個表達式是 `false`。

```
if:
  or:
    - stringEquals: 'test_string'
      value: 'test_string_not_equal'
    - numberEquals: 1
      value: 1
```

**條件式修飾詞：不是**  
`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。要比較的數字必須是下列其中一種格式。
+ Integer
+ Float
+ 符合下列規則運算式模式的字串：`^-?[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
```