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

# 在自訂元件文件中使用變數
<a name="toe-user-defined-variables"></a>

變數提供一種方法，以有意義的名稱標記資料，可用於整個應用程式。您可以為複雜工作流程定義具有簡單且可讀取格式的自訂變數，並在 AWS TOE 元件的 YAML 應用程式元件文件中參考它們。

本節提供的資訊可協助您在 YAML 應用程式 AWS TOE 元件文件中定義元件的變數，包括語法、名稱限制條件和範例。

## 常數
<a name="user-defined-vars-constants"></a>

常數是不可變的變數，一旦定義就無法修改或覆寫。您可以使用 AWS TOE 文件 `constants`區段中的值來定義常數。

**常數名稱的規則**
+ 名稱長度必須介於 3 到 128 個字元之間。
+ 名稱只能包含英數字元 (a-z、A-Z、0-9)、破折號 (-) 或底線 (\$1)。
+ 名稱在文件中必須是唯一的。
+ 名稱必須指定為 YAML 字串。

**語法**

```
constants:
  - <name>:
      type: <constant type>
      value: <constant value>
```


| 金鑰名稱 | 必要 | 描述 | 
| --- | --- | --- | 
|  `name`  |  是  | 常數的名稱。文件必須是唯一的 （不得與任何其他參數名稱或常數相同）。 | 
| `value` | 是 | 常數的值。 | 
| `type` | 是 | 常數的類型。支援的類型為 string。 | 

**參考文件中的常數值**  
您可以在 YAML 文件內的步驟或迴圈輸入中參考常數，如下所示：
+ 常數參考區分大小寫，名稱必須完全相符。
+ 名稱必須括在雙大括號 `{{` *MyConstant* 內`}}`。
+ 大括號內允許空格，且會自動修剪。例如，下列所有參考都是有效的：

  `{{ MyConstant }}`, `{{ MyConstant}}`, `{{MyConstant }}`, `{{MyConstant}}`
+ YAML 文件中的參考必須指定為字串 （以單引號或雙引號括住）。

  例如： `- {{ MyConstant }}` 無效，因為它未被識別為字串。

  不過，下列參考皆有效： `- '{{ MyConstant }}'`和 `- "{{ MyConstant }}"`。

**範例**  
步驟輸入中參考的常數

```
name: Download AWS CLI version 2
schemaVersion: 1.0
constants:
  - Source:
      type: string
      value: https://awscli.amazonaws.com/AWSCLIV2.msi
phases:
  - name: build
    steps:
      - name: Download
        action: WebDownload
        inputs:
          - source: '{{ Source }}'
            destination: 'C:\Windows\Temp\AWSCLIV2.msi'
```

迴圈輸入中參考的常數

```
name: PingHosts
schemaVersion: 1.0
constants:
  - Hosts:
      type: string
      value: 127.0.0.1,amazon.com
phases:
  - name: build
    steps:
      - name: Ping
        action: ExecuteBash
        loop:
          forEach:
            list: '{{ Hosts }}'
            delimiter: ','
        inputs:
          commands:
            - ping -c 4 {{ loop.value }}
```

## Parameters
<a name="user-defined-vars-parameters"></a>

參數是可變變數，具有呼叫應用程式可在執行時間提供的設定。您可以在 YAML 文件的 `Parameters`區段中定義參數。

**參數名稱的規則**
+ 名稱長度必須介於 3 到 128 個字元之間。
+ 名稱只能包含英數字元 (a-z、A-Z、0-9)、破折號 (-) 或底線 (\$1)。
+ 名稱在文件中必須是唯一的。
+ 名稱必須指定為 YAML 字串。

### 語法
<a name="vars-parameters-syntax"></a>

```
parameters:
  - <name>:
      type: <parameter type>
      default: <parameter value>
      description: <parameter description>
```


| 金鑰名稱 | 必要 | 描述 | 
| --- | --- | --- | 
| `name` | 是 | 參數名稱。文件必須是唯一的 （不得與任何其他參數名稱或常數相同）。 | 
| `type` | 是 | 參數的資料類型。支援的類型包括：`string`。 | 
| `default` | 否 | 參數的預設值。 | 
| `description` | 否 | 描述 參數。 | 

### 參考文件中的參數值
<a name="vars-parameters-referencing"></a>

您可以在 YAML 文件內的步驟或迴圈輸入中參考參數，如下所示：
+ 參數參考區分大小寫，且名稱必須完全相符。
+ 名稱必須括在雙大括號 `{{` *MyParameter* 內`}}`。
+ 大括號內允許空格，且會自動修剪。例如，下列所有參考都是有效的：

  `{{ MyParameter }}`, `{{ MyParameter}}`, `{{MyParameter }}`, `{{MyParameter}}`
+ YAML 文件中的參考必須指定為字串 （以單引號或雙引號括住）。

  例如： `- {{ MyParameter }}` 無效，因為它未被識別為字串。

  不過，下列參考都有效： `- '{{ MyParameter }}'`和 `- "{{ MyParameter }}"`。

**範例**  
下列範例示範如何在 YAML 文件中使用參數：
+ 請參閱步驟輸入中的參數：

  ```
  name: Download AWS CLI version 2
  schemaVersion: 1.0
  parameters:
    - Source:
        type: string
        default: 'https://awscli.amazonaws.com/AWSCLIV2.msi'
        description: The AWS CLI installer source URL.
  phases:
    - name: build
      steps:
        - name: Download
          action: WebDownload
          inputs:
            - source: '{{ Source }}'
              destination: 'C:\Windows\Temp\AWSCLIV2.msi'
  ```
+ 請參閱迴圈輸入中的參數：

  ```
  name: PingHosts
  schemaVersion: 1.0
  parameters:
    - Hosts:
        type: string
        default: 127.0.0.1,amazon.com
        description: A comma separated list of hosts to ping.
  phases:
    - name: build
      steps:
        - name: Ping
          action: ExecuteBash
          loop:
            forEach:
              list: '{{ Hosts }}'
              delimiter: ','
          inputs:
            commands:
              - ping -c 4 {{ loop.value }}
  ```

### 在執行時間覆寫參數
<a name="vars-parameters-set-at-runtime"></a>

您可以從 AWS CLI 搭配索引鍵/值對使用 `--parameters`選項，在執行時間設定參數值。
+ 將參數鍵/值對指定為名稱和值，並以等號 (<name>=<value>) 分隔。
+ 多個參數必須以逗號分隔。
+ 在 YAML 元件文件中找不到的參數名稱會被忽略。
+ 參數名稱和值都是必要的。

**重要**  
元件參數是純文字值，並會登入 AWS CloudTrail。建議您使用 AWS Secrets Manager 或 AWS Systems Manager 參數存放區來存放秘密。如需 Secrets Manager 的詳細資訊，請參閱*AWS Secrets Manager 《 使用者指南*》中的[什麼是 Secrets Manager？](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)。如需 AWS Systems Manager 參數存放區的詳細資訊，請參閱*AWS Systems Manager 《 使用者指南*》中的[AWS Systems Manager 參數存放區](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)。

#### 語法
<a name="vars-runtime-parameters-syntax"></a>

```
--parameters name1=value1,name2=value2...
```


| CLI 選項 | 必要 | Description | 
| --- | --- | --- | 
| --parameters *name*=*value*，... | 否 | 此選項會取得索引鍵/值對的清單，並將參數名稱做為索引鍵。 | 

**範例**  
下列範例示範如何在 YAML 文件中使用參數：
+ `--parameter` 此選項中指定的參數鍵/值對無效：

  ```
  --parameters ntp-server=
  ```
+ 使用 中的 `--parameter`選項設定一個參數鍵/值對 AWS CLI：

  ```
  --parameters ntp-server=ntp-server-windows-qe.us-east1.amazon.com
  ```
+ 使用 中的 `--parameter`選項設定多個參數鍵值對 AWS CLI：

  ```
  --parameters ntp-server=ntp-server.amazon.com,http-url=https://internal-us-east1.amazon.com
  ```

## 使用 Systems Manager 參數存放區參數
<a name="toe-ssm-parameters"></a>

您可以在元件文件中參考 AWS Systems Manager 參數存放區參數 (SSM 參數），方法是使用 為變數加上字首`aws:ssm`。例如 

`{{ aws:ssm:/my/param }}` 解析為 SSM 參數 的值`/my/param`。

此功能支援下列 SSM 參數類型：
+ 字串 – 對應至 AWS TOE 字串類型。
+ StringList – 映射至 AWS TOE `stringList`類型。
+ SecureString – 對應至 AWS TOE 字串類型。

如需參數存放區的詳細資訊，請參閱*AWS Systems Manager 《 使用者指南*》中的[AWS Systems Manager 參數存放](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)區。

您也可以使用 SSM 參數 來參考 AWS Secrets Manager 秘密`SecureString`。例如：`{{ aws:ssm:/aws/reference/secretsmanager/test/test-secret }}`。如需詳細資訊，請參閱[參考 AWS Secrets Manager 參數存放區參數中的秘密](https://docs.aws.amazon.com/systems-manager/latest/userguide/integration-ps-secretsmanager.html)。

**重要**  
Image Builder 從其日誌中排除`SecureString`參數解析。不過，您也必須負責確保不會透過元件文件中發出的命令記錄敏感資訊。例如，如果您使用 `echo`命令搭配安全字串，命令會將純文字值寫入日誌。

### 所需的 IAM 許可
<a name="toe-ssm-parameters-permissions"></a>

若要在元件中使用 Systems Manager 參數，您的執行個體角色必須具有參數資源 ARN 的`ssm:GetParameter`許可。例如：

------
#### [ JSON ]

****  

```
{
	"Version":"2012-10-17",		 	 	 
	"Statement": [
		{
			"Effect": "Allow",
			"Action": "ssm:GetParameter",
			"Resource": "arn:aws:ssm:*:111122223333:parameter/ImageBuilder-*"
		}
	]
}
```

------

若要存取加密的值，您也需要下列許可：
+ `kms:Decrypt` 針對使用客戶受管加密的`SecureString`參數或 AWS Secrets Manager 值新增 AWS KMS key。
+ `secretsmanager:GetSecretValue` 如果您參考 Secrets Manager 秘密，請新增 。

### 參考元件文件中的 SSM 參數
<a name="toe-ssm-parameters-example"></a>

下列範例示範如何在元件中參考 Systems Manager 參數的 Systems Manager 參數存放區參數：

```
name: UseSSMParameterVariable
description: This is a sample component document that prints out the value of an SSM Parameter. Never do this for a SecureString parameter.
schemaVersion: 1.0

phases:
  - name: verify
    steps:
      - name: EchoParameterValue
        action: ExecuteBash
        inputs:
          commands:
            - echo "Log SSM parameter name: /my/test/param, value {{ aws:ssm:/my/test/param }}."
```

### SSM 參數的動態執行期變數解析
<a name="toe-dynamic-vars"></a>

AWSTOE 提供下列內建函數，您可以在變數參考內操作或轉換執行時間的值。

#### 解析函數
<a name="toe-function-resolve"></a>

`resolve` 函數會在另一個變數參考內解析變數參考，允許動態變數名稱參考。這在使用 SSM 參數時非常有用，其中部分參數路徑可能是可變的，並以文件參數的形式傳入。

`resolve` 函數僅支援 SSM 參數名稱部分的動態解析。

##### 語法
<a name="toe-function-resolve-syntax"></a>

`dynamic_variable` 下列範例中的 代表 SSM 參數的名稱，且必須是下列其中一項：
+ SSM 參數參考 （例如 `aws:ssm:/my/param`)
+ 元件文件參數參考 （例如 `parameter-name`)

```
{{ aws:ssm:resolve(dynamic_variable) }}
```

##### 範例：在執行時間解析 SSM 參數
<a name="toe-function-resolve-examples"></a>

下列範例示範如何在 YAML 元件文件中使用 `resolve`函數：

```
name: SsmParameterTest
description: This component verifies an SSM parameter variable reference with the echo command.
schemaVersion: 1.0

parameters:
  - parameter-name:
      type: string
      description: "test"

phases:
  - name: validate
    steps:
      - name: PrintDynamicVariable
        action: ExecuteBash
        inputs:
          commands:
            - echo "{{ aws:ssm:resolve(parameter-name) }}"
```