这是 AWS CDK v2 开发者指南。旧版 CDK v1 于 2022 年 6 月 1 日进入维护阶段，并于 2023 年 6 月 1 日终止支持。

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

# 使用 CloudFormation 参数获取 CloudFormation 值
<a name="get-cfn-param"></a>

在部署时，使用 AWS 云开发工具包 (AWS CDK) 应用程序中的 AWS CloudFormation 参数将自定义值输入到合成的 CloudFormation 模板中。

有关简介，请参阅[参数和 AWS CDK](parameters.md)。

## 在 CDK 应用程序中定义参数
<a name="parameters-define"></a>

使用 [https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CfnParameter.html](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CfnParameter.html) 类定义参数。您至少需要为大多数参数指定至少一个类型和描述，尽管两者在技术上都是可选的。当提示用户在 AWS CloudFormation 控制台中输入参数值时，就会显示描述。有关可用类型的更多信息，请参阅 [Types](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html#parameters-section-structure-properties-type)。

**注意**  
您可以在任何作用域内定义参数。但是，我们建议在堆栈级别定义参数，以便在重构代码时它们的逻辑 ID 不会发生变化。

**Example**  

```
const uploadBucketName = new CfnParameter(this, "uploadBucketName", {
  type: "String",
  description: "The name of the Amazon S3 bucket where uploaded files will be stored."});
```

```
const uploadBucketName = new CfnParameter(this, "uploadBucketName", {
  type: "String",
  description: "The name of the Amazon S3 bucket where uploaded files will be stored."});
```

```
upload_bucket_name = CfnParameter(self, "uploadBucketName", type="String",
    description="The name of the Amazon S3 bucket where uploaded files will be stored.")
```

```
CfnParameter uploadBucketName = CfnParameter.Builder.create(this, "uploadBucketName")
        .type("String")
        .description("The name of the Amazon S3 bucket where uploaded files will be stored")
        .build();
```

```
var uploadBucketName = new CfnParameter(this, "uploadBucketName", new CfnParameterProps
{
    Type = "String",
    Description = "The name of the Amazon S3 bucket where uploaded files will be stored"
});
```

## 使用参数
<a name="parameters-use"></a>

`CfnParameter` 实例通过[令牌](tokens.md)将其值公开给 CDK 应用程序。像所有令牌一样，参数的令牌在合成时进行解析。但是它会解析为对 AWS CloudFormation 模板（将在部署时解析）中定义的参数的引用，而不是对具体值的引用。

您可以将令牌作为 `Token` 类的实例进行检索，也可以检索为字符串、字符串列表或数字编码。您的选择取决于要与参数一起使用的类或方法所需的值类型。

**Example**  


| 属性 | 值种类 | 
| --- | --- | 
|   `value`   |   `Token` 类实例  | 
|   `valueAsList`   |  以字符串列表形式表示的令牌  | 
|   `valueAsNumber`   |  以数字形式表示的令牌  | 
|   `valueAsString`   |  以字符串形式表示的令牌  | 


| 属性 | 值种类 | 
| --- | --- | 
|   `value`   |   `Token` 类实例  | 
|   `valueAsList`   |  以字符串列表形式表示的令牌  | 
|   `valueAsNumber`   |  以数字形式表示的令牌  | 
|   `valueAsString`   |  以字符串形式表示的令牌  | 


| 属性 | 值种类 | 
| --- | --- | 
|   `value`   |   `Token` 类实例  | 
|   `value_as_list`   |  以字符串列表形式表示的令牌  | 
|   `value_as_number`   |  以数字形式表示的令牌  | 
|   `value_as_string`   |  以字符串形式表示的令牌  | 


| 属性 | 值种类 | 
| --- | --- | 
|   `getValue()`   |   `Token` 类实例  | 
|   `getValueAsList()`   |  以字符串列表形式表示的令牌  | 
|   `getValueAsNumber()`   |  以数字形式表示的令牌  | 
|   `getValueAsString()`   |  以字符串形式表示的令牌  | 


| 属性 | 值种类 | 
| --- | --- | 
|   `Value`   |   `Token` 类实例  | 
|   `ValueAsList`   |  以字符串列表形式表示的令牌  | 
|   `ValueAsNumber`   |  以数字形式表示的令牌  | 
|   `ValueAsString`   |  以字符串形式表示的令牌  | 

例如，要在 `Bucket` 定义中使用参数：

**Example**  

```
const bucket = new Bucket(this, "amzn-s3-demo-bucket",
  { bucketName: uploadBucketName.valueAsString});
```

```
const bucket = new Bucket(this, "amzn-s3-demo-bucket",
  { bucketName: uploadBucketName.valueAsString});
```

```
bucket = Bucket(self, "amzn-s3-demo-bucket",
    bucket_name=upload_bucket_name.value_as_string)
```

```
Bucket bucket = Bucket.Builder.create(this, "amzn-s3-demo-bucket")
        .bucketName(uploadBucketName.getValueAsString())
        .build();
```

```
var bucket = new Bucket(this, "amzn-s3-demo-bucket")
{
    BucketName = uploadBucketName.ValueAsString
};
```

## 部署包含参数的 CDK 应用程序
<a name="parameters-deploy"></a>

通过 AWS CloudFormation 控制台部署生成的 AWS CloudFormation 模板时，系统将提示您为每个参数提供值。

您也可以使用 CDK CLI `cdk deploy` 命令指定参数值，或在 CDK 项目的堆栈文件中提供参数值。

### 使用 cdk deploy 提供参数值
<a name="parameters-deploy-cli"></a>

使用 CDK CLI `cdk deploy` 命令进行部署时，可以在部署时使用 `--parameters` 选项提供参数值。

以下是 `cdk deploy` 命令结构的示例：

```
$ cdk deploy <stack-logical-id> --parameters <stack-name>:<parameter-name>=<parameter-value>
```

如果 CDK 应用程序包含单个堆栈，则无需在 `--parameters` 选项中提供堆栈逻辑 ID 参数或 `stack-name` 值。CDK CLI 将自动查找并提供这些值。以下是为 CDK 应用程序中单个堆栈的 `uploadBucketName` 参数指定 `uploadbucket` 值的示例：

```
$ cdk deploy --parameters <uploadBucketName>=<uploadbucket>
```

### 通过 cdk 部署为多堆栈应用程序提供参数值
<a name="parameters-deploy-cli-multi-stack"></a>

以下是 TypeScript 中包含两个 CDK 堆栈的示例 CDK 应用程序。每个堆栈都包含一个 Amazon S3 存储桶实例和用于设置 Amazon S3 存储桶名称的参数：

```
import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as s3 from 'aws-cdk-lib/aws-s3';

// Define the CDK app
const app = new cdk.App();

// First stack
export class MyFirstStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // Set a default parameter name
    const bucketNameParam = new cdk.CfnParameter(this, 'bucketNameParam', {
      type: 'String',
      default: 'amzn-s3-demo-bucket1'
    });

    // Define an S3 bucket
    new s3.Bucket(this, 'MyFirstBucket', {
      bucketName: bucketNameParam.valueAsString
    });
  }
}

// Second stack
export class MySecondStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // Set a default parameter name
    const bucketNameParam = new cdk.CfnParameter(this, 'bucketNameParam', {
      type: 'String',
      default: 'amzn-s3-demo-bucket2'
    });

    // Define an S3 bucket
    new s3.Bucket(this, 'MySecondBucket', {
      bucketName: bucketNameParam.valueAsString
    });
  }
}

// Instantiate the stacks
new MyFirstStack(app, 'MyFirstStack', {
  stackName: 'MyFirstDeployedStack',
});

new MySecondStack(app, 'MySecondStack', {
  stackName: 'MySecondDeployedStack',
});
```

对于包含多个堆栈的 CDK 应用程序，您可以执行以下操作：
+  **使用参数部署一个堆栈**：要从多堆栈应用程序部署单个堆栈，请提供堆栈逻辑 ID 作为参数。

  以下是使用 `mynewbucketname` 作为 `bucketNameParam` 的参数值部署 `MySecondStack` 的示例：

  ```
  $ cdk deploy <MySecondStack> --parameters <bucketNameParam>='<mynewbucketname>'
  ```
+  **部署所有堆栈并为每个堆栈指定参数值**：提供 `'*'` 通配符或 `--all` 选项，以部署所有堆栈。在单个命令中多次提供 `--parameters` 选项，以指定每个堆栈的参数值。以下是示例：

  ```
  $ cdk deploy <'*'> --parameters <MyFirstDeployedStack>:<bucketNameParam>='<mynewfirststackbucketname>' --parameters <MySecondDeployedStack>:<bucketNameParam>='<mynewsecondstackbucketname>'
  ```
+  **部署所有堆栈并为单个堆栈指定参数值**：提供 `'*'` 通配符或 `--all` 选项，以部署所有堆栈。然后，在 `--parameters` 选项中指定要为其定义参数的堆栈。以下是在 CDK 应用程序中部署所有堆栈并为 `MySecondDeployedStack` AWS CloudFormation 堆栈指定参数值的示例。所有其他堆栈都将部署并使用默认参数值：

  ```
  $ cdk deploy <'*'> --parameters <MySecondDeployedStack>:<bucketNameParam>='<mynewbucketname>'
  $ cdk deploy <--all> --parameters <MySecondDeployedStack>:<bucketNameParam>='<mynewbucketname>'
  ```

### 使用 `cdk deploy` 为包含嵌套堆栈的应用程序提供参数值
<a name="parameters-deploy-cli-nested-stack"></a>

开发包含嵌套堆栈的应用程序时，CDK CLI 的行为与多堆栈应用程序类似。主要区别在于，如果要部署所有嵌套堆栈，请使用 `'**'` 通配符。`'*'` 通配符会部署所有堆栈，但不会部署嵌套堆栈。`'**'` 通配符会部署所有堆栈，包括嵌套堆栈。

以下是在为一个嵌套堆栈指定参数值的同时部署嵌套堆栈的示例：

```
$ cdk deploy '**' --parameters <MultiStackCdkApp/SecondStack>:<bucketNameParam>='<mysecondstackbucketname>'
```

有关 `cdk deploy` 命令选项的更多信息，请参阅 [cdk deploy](ref-cli-cmd-deploy.md)。