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

# 在自定义组件文档中使用变量
<a name="toe-user-defined-variables"></a>

变量提供了一种以在整个应用程序中可使用的有意义的名称来标记数据的方法。您可以为复杂的工作流程定义格式简单易读的自定义变量，并在组件的 YAML 应用程序组件文档中引用它们。 AWSTOE 

本节提供的信息可帮助您在 YAML 应用程序 AWSTOE 组件文档中为组件定义变量，包括语法、名称约束和示例。

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

常量是不可变的变量，一旦定义就无法修改或覆盖。常量可以使用 AWSTOE 文档`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 }}
```

## 参数
<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>

您可以将中的`--parameters`选项与键值对 AWS CLI 一起使用，在运行时设置参数值。
+ 将参数键值对指定为名称和值，用等号 (=) 分隔 (<name>=<value>)。
+ 多个参数必须用逗号分隔。
+ 在 YAML 组件文档中找不到的参数名称将被忽略。
+ 参数名称和值都是必需的。

**重要**  
组件参数是纯文本值，并且已记录在 AWS CloudTrail中。我们建议您使用 AWS Secrets Manager 或 P AWS Systems Manager arameter Store 来存储您的密钥。有关 Secrets Manager 的更多信息，请参阅*AWS Secrets Manager 用户指南*中的[什么是 Secrets Manager?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)。有关 AWS Systems Manager Parameter Store 的更多信息，请参阅 *AWS Systems Manager 用户指南*中的 [AWS Systems Manager Parameter Store](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 选项 | 必需 | 说明 | 
| --- | --- | --- | 
| --参数 *name* =*value*，... | 否 | 此选项采用键/值对列表，以参数名称为键。 | 

**示例**  
以下示例显示如何在 YAML 文档中使用参数：
+ 此 `--parameter` 选项中指定的参数键值对无效：

  ```
  --parameters ntp-server=
  ```
+ 使用 AWS CLI中的 `--parameter` 选项设置一个参数键值对：

  ```
  --parameters ntp-server=ntp-server-windows-qe.us-east1.amazon.com
  ```
+ 使用 AWS CLI中的 `--parameter` 选项设置多个参数键值对：

  ```
  --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 参数类型：
+ 字符串-映射到 AWSTOE 字符串类型。
+ StringList — 映射到 AWSTOE `stringList`类型。
+ SecureString — 映射到 AWSTOE 字符串类型。

有关参数存储的更多信息，请参阅*AWS Systems Manager 用户指南*中的[AWS Systems Manager 参数存储](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)。

您也可以使用 SSM 参数`SecureString`引用 AWS Secrets Manager 密钥。例如：`{{ 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) }}"
```