本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # CloudFormation 範本 Parameters 語法 使用選用的 `Parameters` 區段自訂您的範本。透過參數，您可以在每次建立或更新堆疊時將自訂值輸入至您的範本。透過在範本中使用參數，您能夠建立可重複使用且靈活的範本，這些範本可針對特定案例量身打造。 透過定義適當類型的參數，您可在使用主控台建立堆疊時，從現有資源的識別碼清單中選擇。如需詳細資訊，請參閱[使用 CloudFormation 提供的參數類型，在執行時期指定現有資源](cloudformation-supplied-parameter-types.md)。 參數是指定堆疊資源屬性值的常用方式。但是，有些設定可能依存於區域，或有些複雜，讓使用者因其他條件或依存項目而無法找出。在這些情況下，您可能要在範本本身中放入一些邏輯，讓使用者可以指定簡單的值 (或完全不指定)，以取得他們希望的結果，如透過映射來實現。如需詳細資訊，請參閱[CloudFormation 範本 Mappings 語法](mappings-section-structure.md)。 ## 語法 您可在範本的 `Parameters` 區段中宣告參數，該區段使用下列一般語法： ### JSON ``` "Parameters" : { "ParameterLogicalID" : { "Description": "Information about the parameter", "Type" : "DataType", "Default" : "value", "AllowedValues" : ["value1", "value2"] } } ``` ### YAML ``` Parameters: ParameterLogicalID: Description: Information about the parameter Type: DataType Default: value AllowedValues: - value1 - value2 ``` 參數包含定義其值的屬性清單以及針對其值的限制條件。唯一的必要屬性是 `Type`，可以是 `String`、`Number` 或 CloudFormation 提供的參數類型。您也可以新增 `Description` 屬性，描述您應該指定的值類型。您使用**建立堆疊**精靈中的範本時，**指定參數**頁面上會出現參數的名稱和描述。 **注意** 根據預設，CloudFormation 主控台會依據參數的邏輯 ID 字母順序來列出參數。若要覆寫此預設排序，並將相關參數分組在一起，您可在範本中使用 `AWS::CloudFormation::Interface` 中繼資料金鑰。如需詳細資訊，請參閱[使用 `AWS::CloudFormation::Interface` 中繼資料組織 CloudFormation 參數](aws-cloudformation-interface.md)。 針對有預設值的參數，除非使用者指定另一個值，否則 CloudFormation 會使用預設值。若您省略預設屬性，使用者必須指定該參數的值。但是，要求使用者輸入值並不能確保該值有效。若要驗證參數的值，您可以宣告限制條件或指定 AWS特定的參數類型。 對於沒有預設值的參數，使用者必須在建立堆疊時，指定金鑰名稱值。否則，CloudFormation 無法建立堆疊，且會擲出例外狀況： ``` Parameters: [KeyName] must have values ``` ## Properties `AllowedPattern` 規則表達式，代表 `String` 或 `CommaDelimitedList` 類型允許的模式。當套用於類型 `String` 參數時，模式必須匹配提供的整個參數值。當套用於類型 `CommaDelimitedList` 參數時，模式必須匹配清單中的每個值。 *必要*：否 `AllowedValues` 陣列，包含參數的允許值清單。當套用於類型 `String` 參數時，參數值必須是允許值之一。當套用於類型 `CommaDelimitedList` 參數時，清單中的每個值必須是指定的允許值之一。 *必要*：否 如果您使用 YAML，並且想要將 `Yes` 和 `No` 字串用於 `AllowedValues`，請使用單引號來防止 YAML 剖析器考慮這些布林值。 `ConstraintDescription` 字串，說明違反限制時的限制。例如，具有允許模式 `[A-Za-z0-9]+` 的參數會在使用者指定無效值時顯示下列錯誤訊息，但沒有限制描述： `Malformed input-Parameter MyParameter must match pattern [A-Za-z0-9]+` 透過新增限制描述，例如*只能包含字母 (大寫和小寫) 及數字*，您可以顯示下列自訂錯誤訊息： `Malformed input-Parameter MyParameter must only contain uppercase and lowercase letters and numbers` *必要*：否 `Default` 建立堆疊時，範本要在未指定值時使用的適當類型值。如果您定義參數的限制，則必須指定遵循這些限制的值。 *必要*：否 `Description` 多達 4000 個字元的字串，可說明參數。 *必要*：否 `MaxLength` 整數值，決定您想要針對 `String` 類型允許的最大字元數。 *必要*：否 `MaxValue` 數值，決定您想要針對 `Number` 類型允許的最大數值。 *必要*：否 `MinLength` 整數值，決定您想要針對 `String` 類型允許的最小字元數。 *必要*：否 `MinValue` 數值，決定您想要針對 `Number` 類型允許的最小數值。 *必要*：否 `NoEcho` 是否遮罩參數值以防止其在主控台、命令列工具或 API 中顯示。若您將 `NoEcho` 屬性設為 `true`，CloudFormation 會將任何描述堆疊或堆疊事件呼叫所傳回的參數值以星號 (\$1\$1\$1\$1\$1) 遮罩，但儲存在以下指定位置中的資訊除外。 *必要*：否 使用 `NoEcho` 屬性不會遮罩任何儲存在下列資訊中的資訊： + `Metadata` 範本區段。CloudFormation 不會轉換、修改或標記您在 `Metadata` 區段中包含的任何資訊。若要取得更多資訊，請參閱[中繼資料](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/metadata-section-structure.html)。 + `Outputs` 範本區段。如需詳細資訊，請參閱[輸出](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html)。 + 資源定義的 `Metadata` 屬性。如需詳細資訊，請參閱 [`Metadata` 屬性](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-attribute-metadata.html)。 我們強烈建議您不要使用這些機制來包含敏感資訊，例如密碼或秘密。 我們建議您不要直接在 CloudFormation 範本中嵌入敏感資訊，而是在堆疊範本中使用動態參數來參考在 CloudFormation 外部存放和管理的敏感資訊，例如在 AWS Systems Manager 參數存放區或 中 AWS Secrets Manager。 如需詳細資訊，請參閱[請勿在範本中內嵌認證](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/security-best-practices.html#creds)的最佳實務。 強烈建議不要在作為資源主要識別碼一部分的資源屬性中包含 `NoEcho` 參數或任何敏感資料。 形成主要資源識別碼的屬性中包含 `NoEcho` 參數時，CloudFormation 可使用主要資源識別碼中的*實際純文字值*。此資源 ID 可能會出現在任何衍生輸出或目的地中。 若要判斷哪些資源屬性組成資源類型的主要識別碼，請參閱 [AWS 資源和屬性類型參考](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-template-resource-type-ref.html)中該資源的資源參考文件。在 **Return values** (傳回值) 區段中，`Ref` 函數傳回值表示組成資源類型主要識別碼的資源屬性。 `Type` 參數的資料類型 (`DataType`)。 *必要*：是 CloudFormation 支援下列參數類型： `String` 常值字串。您可以使用下列屬性宣告限制條件：`MinLength`、`MaxLength`、`Default`、`AllowedValues` 和 `AllowedPattern`。 例如，使用者可以指定 `"MyUserName"`。 `Number` 整數或浮點數。CloudFormation 會將參數值驗證為數字；不過，當您在範本中的其他位置使用參數時 (例如，使用 `Ref` 內建函數)，參數值會變成字串。 您可以使用下列屬性宣告限制條件：`MinValue`、`MaxValue`、`Default` 和 `AllowedValues`。 例如，使用者可以指定 `"8888"`。 `List` 以逗號分隔的整數或浮點數陣列。CloudFormation 會將參數值驗證為數字；不過，當您在範本中的其他位置使用參數時 (例如，使用 `Ref` 內建函數)，參數值會變成字串清單。 例如，使用者可以指定 `"80,20"`，而 `Ref` 會產生 `["80","20"]`。 `CommaDelimitedList` 以逗號分隔的常值字串陣列。字串總數應該比逗號總數多一個。此外，還會裁剪每個成員字串的空格。 例如，使用者可以指定 `"test,dev,prod"`，而 `Ref` 會產生 `["test","dev","prod"]`。 AWS特定參數類型 AWS 值，例如 Amazon EC2 金鑰對名稱和 VPC IDs。如需詳細資訊，請參閱[在執行時期指定現有資源](cloudformation-supplied-parameter-types.md)。 Systems Manager 參數類型 對應至 Systems Manager 參數存放區中現有參數的參數。您可以將 Systems Manager 參數索引鍵指定為 Systems Manager 參數類型的值，而 CloudFormation 會擷取參數存放區中的最新值來用於堆疊。如需詳細資訊，請參閱[在執行時期指定現有資源](cloudformation-supplied-parameter-types.md)。 ## 參數的一般要求 以下是使用參數時適用的要求： + CloudFormation 範本中最多可以有 200 個參數。 + 每個參數都必須獲指定邏輯名稱 (也稱為邏輯 ID)，其必須為英數字元，而且在範本的所有邏輯名稱之間必須是唯一的。 + 每個參數都必須獲指派 CloudFormation 所支援的參數類型。如需詳細資訊，請參閱[類型](#parameters-section-structure-properties-type)。 + 每個參數在執行時期都必須獲指派值，以讓 CloudFormation 成功佈建堆疊。除非提供另一個值，否則您可以選擇性指定預設值以供 CloudFormation 使用。 + 參數必須在相同的範本內宣告和參考。您可以參考範本之 `Resources` 和 `Outputs` 區段中的參數。 ## 範例 **Topics** + [簡單字串參數](#parameters-section-structure-example-1) + [密碼參數](#parameters-section-structure-example-2) + [參考參數](#parameters-section-structure-example-3) + [逗號分隔清單參數](#parameters-section-structure-example-4) + [逗號分隔清單參數的傳回值](#parameters-section-structure-example-5) ### 簡單字串參數 下列範例宣告類型 `String` 名為 `InstanceTypeParameter` 的參數。此參數可讓您指定堆疊的 Amazon EC2 執行個體類型。若在堆疊建立或更新期間未提供任何值，CloudFormation 會使用預設值 `t2.micro`。 #### JSON ``` "Parameters" : { "InstanceTypeParameter" : { "Description" : "Enter t2.micro, m1.small, or m1.large. Default is t2.micro.", "Type" : "String", "Default" : "t2.micro", "AllowedValues" : ["t2.micro", "m1.small", "m1.large"] } } ``` #### YAML ``` Parameters: InstanceTypeParameter: Description: Enter t2.micro, m1.small, or m1.large. Default is t2.micro. Type: String Default: t2.micro AllowedValues: - t2.micro - m1.small - m1.large ``` ### 密碼參數 下列範例宣告類型 `String` 名為 `DBPwd` 的參數，沒有預設值。`NoEcho` 屬性設定為 `true`，以防止參數值在堆疊描述中顯示。可指定的最小長度為 `1`，而可指定的最大長度為 `41`。此模式允許大小寫字母字元和數字。此範例也說明 `AllowedPattern` 屬性使用規則表達式。 #### JSON ``` "Parameters" : { "DBPwd" : { "NoEcho" : "true", "Description" : "The database admin account password", "Type" : "String", "MinLength" : "1", "MaxLength" : "41", "AllowedPattern" : "^[a-zA-Z0-9]*$" } } ``` #### YAML ``` Parameters: DBPwd: NoEcho: true Description: The database admin account password Type: String MinLength: 1 MaxLength: 41 AllowedPattern: ^[a-zA-Z0-9]*$ ``` ### 參考參數 您可以使用 `Ref` 內建函數來參考參數，而 CloudFormation 使用參數值來佈建堆疊。您可以參考相同範本之 `Resources` 和 `Outputs` 區段中的參數。 在下列範例中，EC2 執行個體資源的 `InstanceType` 屬性參考 `InstanceTypeParameter` 參數值： #### JSON ``` "Ec2Instance" : { "Type" : "AWS::EC2::Instance", "Properties" : { "InstanceType" : { "Ref" : "InstanceTypeParameter" }, "ImageId" : "ami-0ff8a91507f77f867" } } ``` #### YAML ``` Ec2Instance: Type: AWS::EC2::Instance Properties: InstanceType: Ref: InstanceTypeParameter ImageId: ami-0ff8a91507f77f867 ``` ### 逗號分隔清單參數 當您需要為單一屬性提供多個值時，`CommaDelimitedList` 參數類型會非常實用。下列範例宣告名為 `DbSubnetIpBlocks` 的參數，預設值為三個以逗號分隔的 CIDR 區塊。 #### JSON ``` "Parameters" : { "DbSubnetIpBlocks": { "Description": "Comma-delimited list of three CIDR blocks", "Type": "CommaDelimitedList", "Default": "10.0.48.0/24, 10.0.112.0/24, 10.0.176.0/24" } } ``` #### YAML ``` Parameters: DbSubnetIpBlocks: Description: "Comma-delimited list of three CIDR blocks" Type: CommaDelimitedList Default: "10.0.48.0/24, 10.0.112.0/24, 10.0.176.0/24" ``` ### 逗號分隔清單參數的傳回值 若要參照的逗號分隔清單中的特定值，請在範本的 `Fn::Select` 區段中使用 `Resources` 內建函數。傳遞所要之物件的索引值和物件清單，如下列範例所示。 #### JSON ``` { "Parameters": { "VPC": { "Type": "String", "Default": "vpc-123456" }, "VpcAzs": { "Type": "CommaDelimitedList", "Default": "us-west-2a, us-west-2b, us-west-2c" }, "DbSubnetIpBlocks": { "Type": "CommaDelimitedList", "Default": "172.16.0.0/26, 172.16.0.64/26, 172.16.0.128/26" } }, "Resources": { "DbSubnet1": { "Type": "AWS::EC2::Subnet", "Properties": { "AvailabilityZone": { "Fn::Select": [ 0, { "Ref": "VpcAzs" } ] }, "VpcId": { "Ref": "VPC" }, "CidrBlock": { "Fn::Select": [ 0, { "Ref": "DbSubnetIpBlocks" } ] } } }, "DbSubnet2": { "Type": "AWS::EC2::Subnet", "Properties": { "AvailabilityZone": { "Fn::Sub": [ "${AWS::Region}${AZ}", { "AZ": { "Fn::Select": [ 1, { "Ref": "VpcAzs" } ] } } ] }, "VpcId": { "Ref": "VPC" }, "CidrBlock": { "Fn::Select": [ 1, { "Ref": "DbSubnetIpBlocks" } ] } } }, "DbSubnet3": { "Type": "AWS::EC2::Subnet", "Properties": { "AvailabilityZone": { "Fn::Sub": [ "${AWS::Region}${AZ}", { "AZ": { "Fn::Select": [ 2, { "Ref": "VpcAzs" } ] } } ] }, "VpcId": { "Ref": "VPC" }, "CidrBlock": { "Fn::Select": [ 2, { "Ref": "DbSubnetIpBlocks" } ] } } } } } ``` #### YAML ``` Parameters: VPC: Type: String Default: vpc-123456 VpcAzs: Type: CommaDelimitedList Default: us-west-2a, us-west-2b, us-west-2c DbSubnetIpBlocks: Type: CommaDelimitedList Default: 172.16.0.0/26, 172.16.0.64/26, 172.16.0.128/26 Resources: DbSubnet1: Type: AWS::EC2::Subnet Properties: AvailabilityZone: !Select - 0 - !Ref VpcAzs VpcId: !Ref VPC CidrBlock: !Select - 0 - !Ref DbSubnetIpBlocks DbSubnet2: Type: AWS::EC2::Subnet Properties: AvailabilityZone: !Sub - ${AWS::Region}${AZ} - AZ: !Select - 1 - !Ref VpcAzs VpcId: !Ref VPC CidrBlock: !Select - 1 - !Ref DbSubnetIpBlocks DbSubnet3: Type: AWS::EC2::Subnet Properties: AvailabilityZone: !Sub - ${AWS::Region}${AZ} - AZ: !Select - 2 - !Ref VpcAzs VpcId: !Ref VPC CidrBlock: !Select - 2 - !Ref DbSubnetIpBlocks ``` ## 相關資源 CloudFormation 也支援使用動態參考來動態指定屬性值。例如，您可能需要參考在 Systems Manager 參數存放區中儲存的安全字串。如需詳細資訊，請參閱[使用動態參考取得存放在其他服務中的值](dynamic-references.md)。 您也可以在 `Ref` 或 `Sub` 函數中，使用虛擬參數來動態填入值。如需詳細資訊，請參閱[使用虛擬參數取得 AWS 值](pseudo-parameter-reference.md)。