這是 AWS CDK v2 開發人員指南。較舊的 CDK v1 已於 2022 年 6 月 1 日進入維護，並於 2023 年 6 月 1 日結束支援。

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

# 使用 CloudFormation 參數取得 CloudFormation 值
<a name="get-cfn-param"></a>

在 AWS Cloud Development Kit (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 主控台中輸入參數的值時，就會顯示描述。如需可用類型的詳細資訊，請參閱[類型](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 主控台部署 generated 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 做為引數。

  以下是`MySecondStack`使用 部署 `mynewbucketname`做為 參數值的範例`bucketNameParam`：

  ```
  $ 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 部署](ref-cli-cmd-deploy.md)。