這是新的 *CloudFormation 範本參考指南*。請更新您的書籤和連結。如需 CloudFormation 入門的說明，請參閱 [AWS CloudFormation 使用者指南](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)。本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 內部函數參考 CloudFormation 提供多個內建函數，可協助您管理您的堆疊。在範本中使用內部函數，將值指派給要到執行時間才能使用的屬性。 **注意** 您可以在範本的特定部分使用內部函數。目前，您可以在資源屬性、輸出、中繼資料屬性和更新政策屬性中使用內部函數。您也可以使用內部函數按條件建立堆疊資源。 **Topics** + [`Fn::Base64`](intrinsic-function-reference-base64.md) + [`Fn::Cidr`](intrinsic-function-reference-cidr.md) + [條件函數](intrinsic-function-reference-conditions.md) + [`Fn::FindInMap`](intrinsic-function-reference-findinmap.md) + [`Fn::ForEach`](intrinsic-function-reference-foreach.md) + [`Fn::GetAtt`](intrinsic-function-reference-getatt.md) + [`Fn::GetAZs`](intrinsic-function-reference-getavailabilityzones.md) + [`Fn::ImportValue`](intrinsic-function-reference-importvalue.md) + [`Fn::Join`](intrinsic-function-reference-join.md) + [`Fn::Length`](intrinsic-function-reference-length.md) + [`Fn::Select`](intrinsic-function-reference-select.md) + [`Fn::Split`](intrinsic-function-reference-split.md) + [`Fn::Sub`](intrinsic-function-reference-sub.md) + [`Fn::ToJsonString`](intrinsic-function-reference-ToJsonString.md) + [`Fn::Transform`](intrinsic-function-reference-transform.md) + [`Ref`](intrinsic-function-reference-ref.md) + [規則函數](intrinsic-function-reference-rules.md) # `Fn::Base64` 內部函數 `Fn::Base64` 會傳回輸入字串的 Base64 表示。此函數通常會用於使用 `UserData` 屬性的方式，將編碼資料傳遞給 Amazon EC2 執行個體。 ## 宣告 ### JSON ``` { "Fn::Base64" : valueToEncode } ``` ### YAML 完整函式名稱的語法： ``` Fn::Base64: valueToEncode ``` 短格式的語法： ``` !Base64 valueToEncode ``` **注意** 若您使用簡短格式並且立即在 `valueToEncode` 參數中包含另一個函數，請針對其中至少一個函數使用完整的函數名稱。例如，下列語法無效： ``` !Base64 !Sub string !Base64 !Ref logical_ID ``` 請改為針對至少其中一個函數使用完整的函數名稱，如以下範例所示： ``` !Base64 "Fn::Sub": string Fn::Base64: !Sub string ``` ## Parameters valueToEncode 您希望轉換成 Base64 的字串值。 ## 傳回值：以 Base64 表示的原始字串。 ## 範例 ### JSON ``` { "Fn::Base64" : "AWS CloudFormation" } ``` ### YAML ``` Fn::Base64: AWS CloudFormation ``` ## 支援的函數您可以在 `Fn::Base64` 函數內使用任何會傳回字串的函數。 # `Fn::Cidr` 內部函數 `Fn::Cidr` 傳回 CIDR 地址區塊的陣列。傳回的 CIDR 區塊數目取決於 `count` 參數。 ## 宣告 ### JSON ``` { "Fn::Cidr" : [ipBlock, count, cidrBits]} ``` ### YAML 完整函式名稱的語法： ``` Fn::Cidr: - ipBlock - count - cidrBits ``` 短格式的語法： ``` !Cidr [ ipBlock, count, cidrBits ] ``` ## Parameters ipBlock 要分割成較小 CIDR 區塊的使用者指定 CIDR 地址區塊。 count 要產生的 CIDR 數目。有效範圍介於 1 與 256 之間。 cidrBits CIDR 的子網路位元數。例如，此參數的值指定為 "8" 會建立遮罩為 "/24" 的 CIDR。子網路位元是倒轉的子網路遮罩。計算特定子網路位元所需的主機位元時，如果是 IPv4，請將 32 減去子網路位元，如果是 IPv6，則將 128 減去子網路位元。 ## 傳回值 CIDR 地址區塊的陣列。 ## 範例 ### 基本使用此範例從遮罩為 "/24" 的 CIDR 之內，建立子網路遮罩為 "/27" 的 6 個 CIDR。 #### JSON ``` { "Fn::Cidr" : [ "192.168.0.0/24", "6", "5"] } ``` #### YAML ``` !Cidr [ "192.168.0.0/24", 6, 5 ] ``` ### 建立已啟用 IPv6 的 VPC 此範例範本建立已啟用 IPv6 的子網路。 #### JSON ``` { "Resources": { "ExampleVpc": { "Type": "AWS::EC2::VPC", "Properties": { "CidrBlock": "10.0.0.0/16" } }, "IPv6CidrBlock": { "Type": "AWS::EC2::VPCCidrBlock", "Properties": { "AmazonProvidedIpv6CidrBlock": true, "VpcId": { "Ref": "ExampleVpc" } } }, "ExampleSubnet": { "Type": "AWS::EC2::Subnet", "DependsOn": "IPv6CidrBlock", "Properties": { "AssignIpv6AddressOnCreation": true, "CidrBlock": { "Fn::Select": [ 0, { "Fn::Cidr": [ { "Fn::GetAtt": [ "ExampleVpc", "CidrBlock" ] }, 1, 8 ] } ] }, "Ipv6CidrBlock": { "Fn::Select": [ 0, { "Fn::Cidr": [ { "Fn::Select": [ 0, { "Fn::GetAtt": [ "ExampleVpc", "Ipv6CidrBlocks" ] } ] }, 1, 64 ] } ] }, "VpcId": { "Ref": "ExampleVpc" } } } } } ``` #### YAML ``` Resources: ExampleVpc: Type: AWS::EC2::VPC Properties: CidrBlock: 10.0.0.0/16 IPv6CidrBlock: Type: AWS::EC2::VPCCidrBlock Properties: AmazonProvidedIpv6CidrBlock: true VpcId: !Ref ExampleVpc ExampleSubnet: Type: AWS::EC2::Subnet DependsOn: IPv6CidrBlock Properties: AssignIpv6AddressOnCreation: true CidrBlock: !Select - 0 - !Cidr - !GetAtt ExampleVpc.CidrBlock - 1 - 8 Ipv6CidrBlock: !Select - 0 - !Cidr - !Select - 0 - !GetAtt ExampleVpc.Ipv6CidrBlocks - 1 - 64 VpcId: !Ref ExampleVpc ``` ## 支援的函數您可以在 `Fn::Cidr` 函數中善用以下函數： + [`Fn::Select`](intrinsic-function-reference-select.md) + [`Ref`](intrinsic-function-reference-ref.md) # 條件函數可使用 `Fn::If` 或 `Fn::Equals` 等內建函數，根據條件式邏輯來建立和設定堆疊資源。這些條件會在堆疊建立或更新期間進行評估。定義所有條件之後，即可將其與範本之 `Resources` 和 `Outputs` 區段中的資源或資源屬性建立關聯。對於進階案例，可以使用 `Fn::And` 或 `Fn::Or` 函數來組合條件，或使用 `Fn::Not` 來否定條件的值。也可以建立巢狀條件，以建立更複雜的條件式邏輯。如果您是第一次在範本中使用條件，建議您先檢閱《AWS CloudFormation 使用者指南**》中的 [CloudFormation 範本條件語法](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/conditions-section-structure.html)主題。 **注意** 必須定義範本的 `Conditions` 區段中的所有條件，`Fn::If` 條件除外。可以在 `Metadata` 屬性、`UpdatePolicy` 屬性以及 `Resources` 和 `Outputs` 區段的屬性值中使用 `Fn::If` 條件。 **Topics** + [`Fn::And`](#intrinsic-function-reference-conditions-and) + [`Fn::Equals`](#intrinsic-function-reference-conditions-equals) + [`Fn::If`](#intrinsic-function-reference-conditions-if) + [`Fn::Not`](#intrinsic-function-reference-conditions-not) + [`Fn::Or`](#intrinsic-function-reference-conditions-or) + [支援的函數](#w2aac24c20c25) + [範例範本](#conditions-sample-templates) ## `Fn::And` 如果所有指定條件評估為 true，則傳回 `true`；如果其中任一條件評估為 false，則傳回 `false`。`Fn::And` 作為 AND 運算子使用。可納入的條件數目下限為 2，上限為 10。 ### 宣告 #### JSON ``` "Fn::And": [{condition}, {...}] ``` #### YAML 完整函式名稱的語法： ``` Fn::And: [condition] ``` 短格式的語法： ``` !And [condition] ``` ### Parameters condition 計算結果為 `true` 或 `false` 的條件。 ### `Fn::And` 使用範例如果參考安全群組名稱等於 `MyAndCondition`，並且 `sg-mysggroup` 計算為 true 時，下列的 `SomeOtherCondition` 會計算為 true： #### JSON ``` "MyAndCondition": { "Fn::And": [ {"Fn::Equals": ["sg-mysggroup", {"Ref": "ASecurityGroup"}]}, {"Condition": "SomeOtherCondition"} ] } ``` #### YAML ``` MyAndCondition: !And - !Equals ["sg-mysggroup", !Ref ASecurityGroup] - !Condition SomeOtherCondition ``` ## `Fn::Equals` 比較兩個值是否相等。若兩值相同，即傳回 `true`，反之則傳回 `false`。 ### 宣告 #### JSON ``` "Fn::Equals" : ["value_1", "value_2"] ``` #### YAML 完整函式名稱的語法： ``` Fn::Equals: [value_1, value_2] ``` 短格式的語法： ``` !Equals [value_1, value_2] ``` ### Parameters value 您希望比較的字串值。 ### `Fn::Equals` 使用範例若 `IsProduction` 參數的值等於 `EnvironmentType`，下列 `prod` 條件會評估為 true： #### JSON ``` "IsProduction" : { "Fn::Equals": [ {"Ref": "EnvironmentType"}, "prod" ] } ``` #### YAML ``` IsProduction: !Equals [!Ref EnvironmentType, prod] ``` ## `Fn::If` 如果指定的條件計算為 `true` 則傳回一個值；如果指定的條件計算為 `false` 則傳回另一個值。目前，CloudFormation 在範本中 `Resources` 區段和 `Outputs` 區段中的 `Metadata` 屬性、`UpdatePolicy` 屬性和屬性值中支援 `Fn::If` 內建函數。您可以使用 `AWS::NoValue` 虛擬參數作為傳回值來移除對應的屬性。 ### 宣告 #### JSON ``` "Fn::If": [condition_name, value_if_true, value_if_false] ``` #### YAML 完整函式名稱的語法： ``` Fn::If: [condition_name, value_if_true, value_if_false] ``` 短格式的語法： ``` !If [condition_name, value_if_true, value_if_false] ``` ### Parameters condition\$1name 條件區段中對條件的參考。使用條件的名稱來參考。 value\$1if\$1true 當指定的條件計算為 true 傳回的值。 value\$1if\$1false 當指定的條件計算為 `false` 傳回的值。 ### `Fn::If` 使用範例 **Topics** + [有條件地選擇資源](#w2aac24c20c19b9b5) + [條件式輸出](#w2aac24c20c19b9b7) + [條件式陣列值](#w2aac24c20c19b9b9) + [條件式屬性和屬性值](#w2aac24c20c19b9c11) + [條件式更新政策](#w2aac24c20c19b9c13) #### 有條件地選擇資源下列範例在 Amazon EC2 資源定義中使用 `Fn::If` 函數，以決定要與執行個體建立關聯的安全群組資源。如果 `CreateNewSecurityGroup` 條件評估為 true，CloudFormation 會使用 `NewSecurityGroup` (範本的其他位置建立的安全群組) 的參考值來指定 `SecurityGroupIds` 屬性。如果 `CreateNewSecurityGroup` 為 false，CloudFormation 會使用 `ExistingSecurityGroupId` 的參考值 (參考現有安全群組的參數)。 ##### JSON ``` "Resources": { "EC2Instance": { "Type": "AWS::EC2::Instance", "Properties": { "ImageId": "ami-0abcdef1234567890", "InstanceType": "t3.micro", "SecurityGroupIds": { "Fn::If": [ "CreateNewSecurityGroup", [{"Ref": "NewSecurityGroup"}], [{"Ref": "ExistingSecurityGroupId"}] ] }] } } } ``` ##### YAML ``` Resources: EC2Instance: Type: AWS::EC2::Instance Properties: ImageId: ami-0abcdef1234567890 InstanceType: t3.micro SecurityGroupIds: !If - CreateNewSecurityGroup - [!Ref NewSecurityGroup] - [!Ref ExistingSecurityGroupId] ``` #### 條件式輸出在範本的 `Output` 區段中，可以使用 `Fn::If` 函數來按條件輸出資訊。在下列程式碼片段中，如果 `CreateNewSecurityGroup` 條件評估為 true，則 CloudFormation 會輸出 `NewSecurityGroup` 資源的安全群組 ID。如果條件為 false，則 `ExistingSecurityGroup` 會輸出 CloudFormation 資源的安全群組 ID。 ##### JSON ``` "Outputs" : { "SecurityGroupId" : { "Description" : "Group ID of the security group used.", "Value" : { "Fn::If" : [ "CreateNewSecurityGroup", {"Ref" : "NewSecurityGroup"}, {"Ref" : "ExistingSecurityGroupId"} ] } } } ``` ##### YAML ``` Outputs: SecurityGroupId: Description: Group ID of the security group used. Value: !If [CreateNewSecurityGroup, !Ref NewSecurityGroup, !Ref ExistingSecurityGroupId] ``` #### 條件式陣列值下列範例使用 `Fn::If`，根據條件有條件地提供不同的陣列值。如果 `MoreThan2AZs` 條件評估為 true，則會使用三個公有子網路。否則，它只會使用兩個公有子網路。 ##### JSON ``` "Subnets": { "Fn::If": [ "MoreThan2AZs", [ {"Fn::ImportValue": "PublicSubnet01"}, {"Fn::ImportValue": "PublicSubnet02"}, {"Fn::ImportValue": "PublicSubnet03"} ], [ {"Fn::ImportValue": "PublicSubnet01"}, {"Fn::ImportValue": "PublicSubnet02"} ] ] } ``` ##### YAML ``` Subnets: Fn::If: - MoreThan2AZs - - Fn::ImportValue: PublicSubnet01 - Fn::ImportValue: PublicSubnet02 - Fn::ImportValue: PublicSubnet03 - - Fn::ImportValue: PublicSubnet01 - Fn::ImportValue: PublicSubnet02 ``` #### 條件式屬性和屬性值下列範例在 `Fn::If` 函數中使用 `AWS::NoValue` 虛擬參數。只有在提供快照 ID 時，該條件才會為 Amazon RDS 資料庫執行個體使用快照。若 `UseDBSnapshot` 條件評估為 true，CloudFormation 會對 `DBSnapshotIdentifier` 屬性使用 `DBSnapshotName` 參數值。若條件評估為 false，CloudFormation 即會移除 `DBSnapshotIdentifier` 屬性。它也會在 Amazon RDS 資料庫執行個體的 `AllocatedStorage` 屬性中使用 `Fn::If` 函數。如果 `IsProduction` 條件評估為 true，儲存體大小會設為 `100`。否則，它會設定為 `20`。 ##### JSON ``` "MyDatabase" : { "Type" : "AWS::RDS::DBInstance", "Properties": { "DBInstanceClass": "db.t3.micro", "AllocatedStorage": { "Fn::If": [ "IsProduction", 100, 20 ] }, "Engine" : "MySQL", "EngineVersion" : "5.5", "MasterUsername" : { "Ref" : "DBUser" }, "MasterUserPassword" : { "Ref" : "DBPassword" }, "DBParameterGroupName" : { "Ref" : "MyRDSParamGroup" }, "DBSnapshotIdentifier" : { "Fn::If" : [ "UseDBSnapshot", {"Ref" : "DBSnapshotName"}, {"Ref" : "AWS::NoValue"} ] } } } ``` ##### YAML ``` MyDatabase: Type: AWS::RDS::DBInstance Properties: DBInstanceClass: db.t3.micro AllocatedStorage: !If [IsProduction, 100, 20] Engine: MySQL EngineVersion: 5.5 MasterUsername: !Ref DBUser MasterUserPassword: !Ref DBPassword DBParameterGroupName: !Ref MyRDSParamGroup DBSnapshotIdentifier: !If [UseDBSnapshot, !Ref DBSnapshotName, !Ref "AWS::NoValue"] ``` #### 條件式更新政策下列程式碼片段只有在 `RollingUpdates` 條件評估為 true 時，才會提供 Auto Scaling 更新政策。如果條件評估為 false，則 CloudFormation 會移除 `AutoScalingRollingUpdate` 更新政策。 ##### JSON ``` "UpdatePolicy": { "Fn::If": [ "RollingUpdates", { "AutoScalingRollingUpdate": { "MaxBatchSize": 2, "MinInstancesInService": 2, "PauseTime": "PT0M30S" } }, { "Ref": "AWS::NoValue" } ] } ``` ##### YAML ``` UpdatePolicy: !If - RollingUpdates - AutoScalingRollingUpdate: MaxBatchSize: 2 MinInstancesInService: 2 PauseTime: PT0M30S - !Ref "AWS::NoValue" ``` ## `Fn::Not` 若條件評估為 `false`，則傳回 `true`，若條件評估為 `true`，則傳回 `false`。`Fn::Not` 作為 NOT 運算子使用。 ### 宣告 #### JSON ``` "Fn::Not": [{condition}] ``` #### YAML 完整函式名稱的語法： ``` Fn::Not: [condition] ``` 短格式的語法： ``` !Not [condition] ``` ### Parameters condition 計算為 `Fn::Equals` 或 `true` 的條件 (例如 `false`)。 ### `Fn::Not` 使用範例若 `EnvCondition` 參數的值等於 `EnvironmentType`，下列 `prod` 條件會評估為 true： #### JSON ``` "MyNotCondition" : { "Fn::Not" : [{ "Fn::Equals" : [ {"Ref" : "EnvironmentType"}, "prod" ] }] } ``` #### YAML ``` MyNotCondition: !Not [!Equals [!Ref EnvironmentType, prod]] ``` ## `Fn::Or` 如果任一指定條件評估為 true，則傳回 `true`；如果所有條件評估為 false，則傳回 `false`。`Fn::Or` 作為 OR 運算子使用。可納入的條件數目下限為 2，上限為 10。 ### 宣告 #### JSON ``` "Fn::Or": [{condition}, {...}] ``` #### YAML 完整函式名稱的語法： ``` Fn::Or: [condition, ...] ``` 短格式的語法： ``` !Or [condition, ...] ``` ### Parameters condition 計算結果為 `true` 或 `false` 的條件。 ### `Fn::Or` 使用範例如果參考安全群組名稱等於 `MyOrCondition`，或 `sg-mysggroup` 計算為 true 時，下列的 `SomeOtherCondition` 會計算為 true： #### JSON ``` "MyOrCondition" : { "Fn::Or" : [ {"Fn::Equals" : ["sg-mysggroup", {"Ref" : "ASecurityGroup"}]}, {"Condition" : "SomeOtherCondition"} ] } ``` #### YAML ``` MyOrCondition: !Or [!Equals [sg-mysggroup, !Ref ASecurityGroup], Condition: SomeOtherCondition] ``` ## 支援的函數您可以在 `Fn::If` 條件中使用下列函數： + `Fn::Base64` + `Fn::FindInMap` + `Fn::GetAtt` + `Fn::GetAZs` + `Fn::If` + `Fn::Join` + `Fn::Select` + `Fn::Sub` + `Ref` 您可以在所有其他條件函數中使用下列函數，例如 `Fn::Equals` 和 `Fn::Or`： + `Fn::FindInMap` + `Ref` + 其他條件函數 ## 範例範本 ### 按條件為生產、開發或測試堆疊來建立資源在某些情況下，建議您建立類似但略有不同的堆疊。例如，您可能有一個讓您用於生產應用程式的範本。您想要建立相同的生產堆疊，所以您可以使用它來進行開發或測試。不過，針對開發和測試，您不一定需要包含在生產層級堆疊中的所有額外容量。反之，您可以使用環境類型輸入參數，按條件建立特定於資源生產、開發或測試的堆疊資源，如下例所示：您可以為 `prod` 參數指定 `dev`、`test` 或 `EnvType`。針對每種環境類型，範本都會指定不同的執行個體類型。執行個體類型可以從大型、運算優化執行個體，到小型一般用途執行個體類型。為了按條件指定執行個體類型，範本會在範本的 `Conditions` 區段中定義兩個條件：`CreateProdResources` (如果 `EnvType` 參數值等於 `prod`，它會評估為 true) 和 `CreateDevResources` (如果參數值等於 `dev`，它會評估為 true)。在 `InstanceType` 屬性中，範本會巢狀化兩個 `Fn::If` 內部函數來判斷要使用哪個執行個體類型。如果 `CreateProdResources` 條件為 true，則執行個體類型為 `c5.xlarge`。如果條件為 false，則計算 `CreateDevResources` 條件。如果 `CreateDevResources` 條件為 true，則執行個體類型為 `t3.medium`；否則執行個體類型為 `t3.small`。除了執行個體類型之外，生產環境也會為執行個體建立並連接一個 Amazon EC2 磁碟區。`MountPoint` 和 `NewVolume` 資源與 `CreateProdResources` 條件相關聯，因此僅在條件計算為 true 時才會建立資源。 **Example JSON** ``` { "AWSTemplateFormatVersion" : "2010-09-09", "Parameters" : { "EnvType" : { "Description" : "Environment type.", "Default" : "test", "Type" : "String", "AllowedValues" : ["prod", "dev", "test"], "ConstraintDescription" : "must specify prod, dev, or test." } }, "Conditions" : { "CreateProdResources" : {"Fn::Equals" : [{"Ref" : "EnvType"}, "prod"]}, "CreateDevResources" : {"Fn::Equals" : [{"Ref" : "EnvType"}, "dev"]} }, "Resources" : { "EC2Instance" : { "Type" : "AWS::EC2::Instance", "Properties" : { "ImageId" : "ami-1234567890abcdef0", "InstanceType" : { "Fn::If" : [ "CreateProdResources", "c5.xlarge", {"Fn::If" : [ "CreateDevResources", "t3.medium", "t3.small" ]} ]} } }, "MountPoint" : { "Type" : "AWS::EC2::VolumeAttachment", "Condition" : "CreateProdResources", "Properties" : { "InstanceId" : { "Ref" : "EC2Instance" }, "VolumeId" : { "Ref" : "NewVolume" }, "Device" : "/dev/sdh" } }, "NewVolume" : { "Type" : "AWS::EC2::Volume", "Condition" : "CreateProdResources", "Properties" : { "Size" : "100", "AvailabilityZone" : { "Fn::GetAtt" : [ "EC2Instance", "AvailabilityZone" ]} } } } } ``` **Example YAML** ``` AWSTemplateFormatVersion: "2010-09-09" Parameters: EnvType: Description: Environment type. Default: test Type: String AllowedValues: [prod, dev, test] ConstraintDescription: must specify prod, dev, or test. Conditions: CreateProdResources: !Equals [!Ref EnvType, prod] CreateDevResources: !Equals [!Ref EnvType, "dev"] Resources: EC2Instance: Type: AWS::EC2::Instance Properties: ImageId: ami-1234567890abcdef0 InstanceType: !If [CreateProdResources, c5.xlarge, !If [CreateDevResources, t3.medium, t3.small]] MountPoint: Type: AWS::EC2::VolumeAttachment Condition: CreateProdResources Properties: InstanceId: !Ref EC2Instance VolumeId: !Ref NewVolume Device: /dev/sdh NewVolume: Type: AWS::EC2::Volume Condition: CreateProdResources Properties: Size: 100 AvailabilityZone: !GetAtt EC2Instance.AvailabilityZone ``` **注意** 如需使用條件來建立資源的更複雜範例，請參閱 [`Condition` 屬性](aws-attribute-condition.md) 主題。 # `Fn::FindInMap` 內部函數 `Fn::FindInMap` 傳回對應 `Mappings` 區段中所宣告之兩個層級映射之索引鍵的值。 ## 宣告 ### JSON ``` { "Fn::FindInMap" : [ "MapName", "TopLevelKey", "SecondLevelKey"] } ``` ### YAML 完整函式名稱的語法： ``` Fn::FindInMap: [ MapName, TopLevelKey, SecondLevelKey ] ``` 短格式的語法： ``` !FindInMap [ MapName, TopLevelKey, SecondLevelKey ] ``` **注意** 您無法以短形式巢套兩個函數的兩個執行個體。 ## Parameters MapName 在 Mappings 區段中宣告的映射邏輯名稱，包含索引鍵和值。 TopLevelKey 最上層的索引鍵名稱。其值為鍵/值對的清單。 SecondLevelKey 第二層的索引鍵名稱，設定為指派給 `TopLevelKey` 之清單中的其中一個索引鍵。 ## 傳回值指派給 `SecondLevelKey` 的值。 ## 範例以下範例會示範 `Fn::FindInMap` 函數的使用方式。 **Topics** + [使用具有區域特定值的 Fn::FindInMap](#intrinsic-function-reference-findinmap-region-example) + [將 Fn::FindInMap 用於環境特定的組態](#intrinsic-function-reference-findinmap-environment-example) ### 使用具有區域特定值的 Fn::FindInMap 下列範例示範如何在包含兩個映射的範本中使用 `Fn::FindInMap`：`AWSInstanceType2Arch` 和 `AWSRegionArch2AMI`。它還包含 `InstanceType` 參數，可讓您在 `t3.micro` 和 `t4g.nano` 之間進行選擇。預設值為 `t3.micro`，但可以在堆疊建立期間覆寫它。 `Fn::FindInMap` 首先會根據選取的執行個體類型決定架構 (`HVM64` 或 `ARM64`)，然後在目前的 AWS 區域中查詢該架構的正確 AMI ID。 **注意** 這些範例中顯示的 AMI ID 是用作示範用途的預留位置。盡可能考慮使用 AWS Systems Manager 參數的動態參考作為 `Mappings` 區段的替代方案。若要避免在每次要使用變更的 AMI 時，使用新 ID 更新所有範本，請在建立或更新堆疊時，使用 AWS Systems Manager 參數擷取最新的 AMI ID。Systems Manager 中也提供最新版本的常用 AMI 作為公有參數。如需詳細資訊，請參閱[使用動態參考取得存放在其他服務中的值](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/dynamic-references.html)。 #### JSON ``` { "AWSTemplateFormatVersion": "2010-09-09", "Parameters": { "InstanceType": { "Description": "The EC2 instance type", "Type": "String", "AllowedValues": [ "t3.micro", "t4g.nano" ], "Default": "t3.micro" } }, "Mappings": { "AWSInstanceType2Arch": { "t3.micro": { "Arch": "HVM64" }, "t4g.nano": { "Arch": "ARM64" } }, "AWSRegionArch2AMI": { "us-east-1" : { "HVM64" : "ami-12345678901234567", "ARM64" : "ami-23456789012345678" }, "us-west-1" : { "HVM64" : "ami-34567890123456789", "ARM64" : "ami-45678901234567890" }, "eu-west-1" : { "HVM64" : "ami-56789012345678901", "ARM64" : "ami-67890123456789012" }, "ap-southeast-1" : { "HVM64" : "ami-78901234567890123", "ARM64" : "ami-89012345678901234" }, "ap-northeast-1" : { "HVM64" : "ami-90123456789012345", "ARM64" : "ami-01234567890123456" } } }, "Resources" : { "MyEC2Instance" : { "Type" : "AWS::EC2::Instance", "Properties" : { "InstanceType" : { "Ref": "InstanceType" }, "ImageId" : { "Fn::FindInMap" : [ "AWSRegionArch2AMI", { "Ref": "AWS::Region" }, { "Fn::FindInMap": [ "AWSInstanceType2Arch", { "Ref": "InstanceType" }, "Arch" ]}] } } } } } ``` #### YAML ``` AWSTemplateFormatVersion: 2010-09-09 Parameters: InstanceType: Description: The EC2 instance type Type: String AllowedValues: - t3.micro - t4g.nano Default: t3.micro Mappings: AWSInstanceType2Arch: t3.micro: Arch: HVM64 t4g.nano: Arch: ARM64 AWSRegionArch2AMI: us-east-1: HVM64: ami-12345678901234567 ARM64: ami-23456789012345678 us-west-1: HVM64: ami-34567890123456789 ARM64: ami-45678901234567890 eu-west-1: HVM64: ami-56789012345678901 ARM64: ami-67890123456789012 ap-southeast-1: HVM64: ami-78901234567890123 ARM64: ami-89012345678901234 ap-northeast-1: HVM64: ami-90123456789012345 ARM64: ami-01234567890123456 Resources: myEC2Instance: Type: AWS::EC2::Instance Properties: InstanceType: !Ref InstanceType ImageId: Fn::FindInMap: - AWSRegionArch2AMI - Ref: AWS::Region - Fn::FindInMap: - AWSInstanceType2Arch - Ref: InstanceType - Arch ``` ### 將 Fn::FindInMap 用於環境特定的組態以下範例說明如何將 `Fn::FindInMap` 用於具有 `Mappings` 區段的範本，該區段包含單一映射 `SecurityGroups`。它也包含 `EnvironmentType` 參數，可讓您指定環境是 `Dev` 還是 `Prod`。預設為 `Dev`，但可以在堆疊建立期間覆寫它。 `Fn::FindInMap` 根據 `EnvironmentType` 參數傳回適當的 `SecurityGroupIds`。然後，`Fn::Split` 會將逗號分隔的安全群組 ID 字串分割為清單，這是 [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ec2-instance.html#cfn-ec2-instance-securitygroupids](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ec2-instance.html#cfn-ec2-instance-securitygroupids) 的預期格式。如果您在 `EnvironmentType` 設定為 `Dev` 的情況下部署此堆疊，則 `EC2Instance` 的 `SecurityGroupIds` 將為 `sg-12345678`。如果將 `EnvironmentType` 設定為 `Prod`，則會使用 `sg-abcdef01` 和 `sg-ghijkl23`。 #### JSON ``` { "AWSTemplateFormatVersion": "2010-09-09", "Parameters":{ "EnvironmentType":{ "Description":"The environment type (Dev or Prod)", "Type":"String", "Default":"Dev", "AllowedValues":[ "Dev", "Prod" ] } }, "Mappings":{ "SecurityGroups":{ "Dev":{ "SecurityGroupIds":"sg-12345678" }, "Prod":{ "SecurityGroupIds":"sg-abcdef01,sg-ghijkl23" } } }, "Resources":{ "Ec2Instance":{ "Type":"AWS::EC2::Instance", "Properties":{ "ImageId": "{{resolve:ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64}}", "InstanceType": "t2.micro", "SecurityGroupIds":{ "Fn::Split":[ ",", { "Fn::FindInMap":[ "SecurityGroups", { "Ref":"EnvironmentType" }, "SecurityGroupIds" ] } ] } } } } } ``` #### YAML ``` AWSTemplateFormatVersion: 2010-09-09 Parameters: EnvironmentType: Description: The environment type (Dev or Prod) Type: String Default: Dev AllowedValues: - Dev - Prod Mappings: SecurityGroups: Dev: SecurityGroupIds: sg-12345678 Prod: SecurityGroupIds: sg-abcdef01,sg-ghijkl23 Resources: Ec2Instance: Type: AWS::EC2::Instance Properties: ImageId: '{{resolve:ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64}}' InstanceType: t2.micro SecurityGroupIds: Fn::Split: - "," - Fn::FindInMap: [ SecurityGroups, !Ref EnvironmentType, SecurityGroupIds ] ``` ## 支援的函數您可以在 `Fn::FindInMap` 函數中善用以下函數： + `Fn::FindInMap` + `Ref` ## 相關資源若要在 `Fn::FindInMap` 函數中使用其他內建函數或預設值，則必須在範本中宣告 `AWS::LanguageExtensions` 轉換。如需詳細資訊，請參閱[`Fn::FindInMap enhancements`](intrinsic-function-reference-findinmap-enhancements.md)。當您開發使用 `Fn::FindInMap` 函數的範本時，這些相關主題會很有幫助。 + [`Fn::Sub`](intrinsic-function-reference-sub.md) + **《AWS CloudFormation 使用者指南》中的 [CloudFormation 範本 Mappings 語法](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/mappings-section-structure.html) # `Fn::ForEach` `Fn::ForEach` 內建函數接受集合和片段，並將集合中的項目套用至所提供片段中的識別符。`Fn::ForEach` 可能包含其他內建函數 (包括 `Fn::ForEach` 本身)，並可在 `Conditions`、`Outputs` 和 `Resources` (包括資源屬性) 區段中使用。它無法在下列任何區段中使用：`AWSTemplateFormatVersion`、`Description`、`Metadata`、`Transform`、`Parameters`、`Mappings`、`Rules` 或 `Hooks` 區段。如果在範本中使用 `Fn::ForEach` 內建函數，也必須使用 [`AWS::LanguageExtensions` 轉換程序](transform-aws-languageextensions.md)。使用 `Fn::ForEach` 內部函數不會更改配額，這些配額將套用到所產生的範本。配額包括範本的大小上限和範本中的資源數量上限。如需詳細資訊，請參閱*AWS CloudFormation 《使用者指南*》中的[了解 CloudFormation 配額](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cloudformation-limits.html)。 ## 宣告 ### JSON ``` "Fn::ForEach::LoopLogicalName": [ "Identifier", ["Value1","Value2"], // Collection {"OutputKey": {OutputValue}} ] ``` ### YAML ``` 'Fn::ForEach::LoopLogicalName': - Identifier - - Value1 # Collection - Value2 - 'OutputKey': OutputValue ``` ## Parameters *迴圈邏輯名稱* 迴圈的邏輯 ID。名稱在範本中必須是唯一的，且不能與範本 `Resources` 區段中的任何邏輯 ID 值衝突。轉換後的輸出中沒有此名稱。它用於 CloudFormation 範本本身的內部參考。 *識別符* 在 `OutputKey` 和 `OutputValue` 參數中取代的預留位置識別符。在 `OutputKey` 和 `OutputValue` 參數中，`${Identifier}` 或 `&{Identifier}` 的全部執行個體將被取代為來自 `Collection` 參數的值。 *收集* 要逐一查看的值的集合。這可以是此參數中的陣列，也可以是 `CommaDelimitedList` 的 [`Ref`](intrinsic-function-reference-ref.md)。使用 `&{Identifier}` 時，可以在 `Collection` 中傳入非英數字元。 *輸出金鑰* 轉換範本中的金鑰。`${Identifier}` 或 `&{Identifier}` 必須包含在 `OutputKey` 參數中。例如，如果在範本的 `Resources` 區段中使用 `Fn::ForEach`，則這是每項資源的邏輯 ID。 `&{}` 語法允許在 `OutputKey` 參數內使用 `Collection` 中的非英數字元。如需相關範例，請參閱 [在 `Fn::ForEach` 的 `Collection` 內傳遞非英數字元](intrinsic-function-reference-foreach-example-resource.md#intrinsic-function-reference-foreach-example-non-alphanumeric)。 *輸出值* 在轉換後的範本中針對 `Collection` 參數中的每個項目複寫的值。例如，如果 `Fn::ForEach` 在範本的 `Resources` 區段中使用，則這是重複用來設定每項資源的範本片段。 ## 傳回值展開的物件包含為集合中每個項目重複一次的物件片段，片段中的識別碼被來自集合的項目替換。 ## 支援的函數您可以在 `Fn::ForEach` 中使用以下函數。 + 條件函數： + [`Fn::And`](intrinsic-function-reference-conditions.md#intrinsic-function-reference-conditions-and) + [`Fn::Equals`](intrinsic-function-reference-conditions.md#intrinsic-function-reference-conditions-equals) + [`Fn::If`](intrinsic-function-reference-conditions.md#intrinsic-function-reference-conditions-if) + [`Fn::Not`](intrinsic-function-reference-conditions.md#intrinsic-function-reference-conditions-not) + [`Fn::Or`](intrinsic-function-reference-conditions.md#intrinsic-function-reference-conditions-or) + [`Fn::Base64`](intrinsic-function-reference-base64.md) + [`Fn::FindInMap`](intrinsic-function-reference-findinmap.md) + [`Fn::GetAtt`](intrinsic-function-reference-getatt.md) + [`Fn::GetAZs`](intrinsic-function-reference-getavailabilityzones.md) + [`Fn::ImportValue`](intrinsic-function-reference-importvalue.md) + [`Fn::Join`](intrinsic-function-reference-join.md) + [`Fn::Length`](intrinsic-function-reference-length.md) + [`Fn::Transform`](intrinsic-function-reference-transform.md) + [`Fn::Select`](intrinsic-function-reference-select.md) + [`Fn::Sub`](intrinsic-function-reference-sub.md) + [`Fn::ToJsonString`](intrinsic-function-reference-ToJsonString.md) + [`Ref`](intrinsic-function-reference-ref.md) ## 範例可以在 [範例](intrinsic-function-reference-foreach-examples.md) 中找到 `Conditions`、`Outputs`和 `Resources` 區段的範例。 # 範例 **Topics** + [`Resources` 區段中的 `Fn::ForEach` 範例](intrinsic-function-reference-foreach-example-resource.md) + [`Outputs` 區段中的 `Fn::ForEach` 範例](intrinsic-function-reference-foreach-example-outputs.md) + [`Conditions` 區段中的 `Fn::ForEach` 範例](intrinsic-function-reference-foreach-example-conditions.md) # `Resources` 區段中的 `Fn::ForEach` 範例這些範例會示範如何使用 `Resources` 區段中的 `Fn::ForEach` 內部函數。如需有關此區段的詳細資訊，請參閱《AWS CloudFormation 使用者指南》**中的[資源](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resources-section-structure.html)。 **Topics** + [複寫 Amazon SNS 資源](#intrinsic-function-reference-foreach-example-replicate-resource) + [複寫 Amazon DynamoDB 資源](#intrinsic-function-reference-foreach-example-replicate-ddb-resource) + [複寫多項資源](#intrinsic-function-reference-foreach-example-replicate-multiple-resources) + [使用巢狀 `Fn::ForEach` 迴圈來複寫多項資源](#intrinsic-function-reference-foreach-example-nested-loop-resources) + [為 Amazon EC2 資源參考複寫的屬性](#intrinsic-function-reference-foreach-example-reference-replicated-resource) + [為 Amazon EC2 資源複寫屬性](#intrinsic-function-reference-foreach-example-replicate-resource-properties) + [在 `Fn::ForEach` 的 `Collection` 內傳遞非英數字元](#intrinsic-function-reference-foreach-example-non-alphanumeric) ## 複寫 Amazon SNS 資源此範例程式碼片段會傳回四個 Amazon SNS 主題的清單，其中的邏輯 ID 對應集合中的項目 (`Success`、`Failure`、`Timeout`、`Unknown`)，且匹配的 `TopicName` 和 `FifoTopic` 設為 `true`。 **注意** 對於需要使用 FIFO 和標準主題的範本，可以使用 `DisplayName` 屬性而非 `TopicName`。這可讓 CloudFormation 在 `FifoTopic` 為 `true` 時自動產生帶有適當 `.fifo` 尾碼的主題名稱。只需在 `Properties` 區段中將 `TopicName` 取代為 `DisplayName: !Ref TopicName`。 ### JSON ``` { "AWSTemplateFormatVersion": "2010-09-09", "Transform": "AWS::LanguageExtensions", "Resources": { "Fn::ForEach::Topics": [ "TopicName", ["Success", "Failure", "Timeout", "Unknown"], { "SnsTopic${TopicName}": { "Type": "AWS::SNS::Topic", "Properties": { "TopicName": {"Fn::Sub": "${TopicName}.fifo"}, "FifoTopic": true } } } ] } } ``` ### YAML ``` AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Resources: 'Fn::ForEach::Topics': - TopicName - [Success, Failure, Timeout, Unknown] - 'SnsTopic${TopicName}': Type: AWS::SNS::Topic Properties: TopicName: !Sub '${TopicName}.fifo' FifoTopic: true ``` 轉換後範本將等同於下列範本： ``` AWSTemplateFormatVersion: 2010-09-09 Resources: SnsTopicSuccess: Type: AWS::SNS::Topic Properties: TopicName: Success.fifo FifoTopic: true SnsTopicFailure: Type: AWS::SNS::Topic Properties: TopicName: Failure.fifo FifoTopic: true SnsTopicTimeout: Type: AWS::SNS::Topic Properties: TopicName: Timeout.fifo FifoTopic: true SnsTopicUnknown: Type: AWS::SNS::Topic Properties: TopicName: Unknown.fifo FifoTopic: true ``` ## 複寫 Amazon DynamoDB 資源此範例程式碼片段會建立四項具有 `Points`、`Score` 等名稱的 [AWS::DynamoDB::Table](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-dynamodb-table.html) 資源。 ### JSON ``` { "AWSTemplateFormatVersion": "2010-09-09", "Transform": "AWS::LanguageExtensions", "Resources": { "Fn::ForEach::Tables": [ "TableName", ["Points", "Score", "Name", "Leaderboard"], { "DynamoDB${TableName}": { "Type": "AWS::DynamoDB::Table", "Properties": { "TableName": { "Ref": "TableName" }, "AttributeDefinitions": [ { "AttributeName": "id", "AttributeType": "S" } ], "KeySchema": [ { "AttributeName": "id", "KeyType": "HASH" } ], "ProvisionedThroughput": { "ReadCapacityUnits": "5", "WriteCapacityUnits": "5" } } } } ] } } ``` ### YAML ``` AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Resources: 'Fn::ForEach::Tables': - TableName - [Points, Score, Name, Leaderboard] - 'DynamoDB${TableName}': Type: AWS::DynamoDB::Table Properties: TableName: !Ref TableName AttributeDefinitions: - AttributeName: id AttributeType: S KeySchema: - AttributeName: id KeyType: HASH ProvisionedThroughput: ReadCapacityUnits: '5' WriteCapacityUnits: '5' ``` 轉換後範本將等同於下列範本： ``` AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Resources: DynamoDBPoints: Type: AWS::DynamoDB::Table Properties: TableName: Points AttributeDefinitions: - AttributeName: id AttributeType: S KeySchema: - AttributeName: id KeyType: HASH ProvisionedThroughput: ReadCapacityUnits: '5' WriteCapacityUnits: '5' DynamoDBScore: Type: AWS::DynamoDB::Table Properties: TableName: Score AttributeDefinitions: - AttributeName: id AttributeType: S KeySchema: - AttributeName: id KeyType: HASH ProvisionedThroughput: ReadCapacityUnits: '5' WriteCapacityUnits: '5' DynamoDBName: Type: AWS::DynamoDB::Table Properties: TableName: Name AttributeDefinitions: - AttributeName: id AttributeType: S KeySchema: - AttributeName: id KeyType: HASH ProvisionedThroughput: ReadCapacityUnits: '5' WriteCapacityUnits: '5' DynamoDBLeaderboard: Type: AWS::DynamoDB::Table Properties: TableName: Leaderboard AttributeDefinitions: - AttributeName: id AttributeType: S KeySchema: - AttributeName: id KeyType: HASH ProvisionedThroughput: ReadCapacityUnits: '5' WriteCapacityUnits: '5' ``` ## 複寫多項資源此範例會使用 `"{ResourceType}${Identifier}"` 的命名慣例，建立多個 [AWS::EC2::NatGateway](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ec2-natgateway.html) 和 [AWS::EC2::EIP](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ec2-eip.html) 執行個體。您可以在一個 `Fn::ForEach` 迴圈下宣告多種資源類型，以利用單一識別碼。在 `Mappings` 區段中為集合中的每項元素定義唯一值，其中的 [`Fn::FindInMap`](intrinsic-function-reference-findinmap.md) 內建函數被用於參考對應的值。如果 `Fn::FindInMap` 找不到對應的識別碼，則 `Condition` 屬性將不會被設為 `!Ref AWS:::NoValue`。 ### JSON ``` { "AWSTemplateFormatVersion": "2010-09-09", "Transform": "AWS::LanguageExtensions", "Conditions": { "TwoNatGateways": {"Fn::Equals": [{"Ref": "AWS::Region"}, "us-east-1"]}, "ThreeNatGateways": {"Fn::Equals": [{"Ref": "AWS::Region"}, "us-west-2"]} }, "Mappings": { "NatGateway": { "Condition": { "B": "TwoNatGateways", "C": "ThreeNatGateways" } } }, "Resources": { "VPC": { "Type": "AWS::EC2::VPC", "Properties": {"CidrBlock": "10.0.0.0/16"} }, "PublicSubnetA": { "Type": "AWS::EC2::Subnet", "Properties": { "VpcId": {"Ref": "VPC"}, "CidrBlock": "10.0.1.0/24", "AvailabilityZone": {"Fn::Select": [0, {"Fn::GetAZs": ""}]} } }, "PublicSubnetB": { "Type": "AWS::EC2::Subnet", "Properties": { "VpcId": {"Ref": "VPC"}, "CidrBlock": "10.0.2.0/24", "AvailabilityZone": {"Fn::Select": [1, {"Fn::GetAZs": ""}]} } }, "PublicSubnetC": { "Type": "AWS::EC2::Subnet", "Properties": { "VpcId": {"Ref": "VPC"}, "CidrBlock": "10.0.3.0/24", "AvailabilityZone": {"Fn::Select": [2, {"Fn::GetAZs": ""}]} } }, "Fn::ForEach::NatGatewayAndEIP": [ "Identifier", [ "A", "B", "C" ], { "NatGateway${Identifier}": { "Type": "AWS::EC2::NatGateway", "Properties": { "AllocationId": {"Fn::GetAtt": [{"Fn::Sub": "NatGatewayAttachment${Identifier}"}, "AllocationId"]}, "SubnetId": {"Ref": {"Fn::Sub": "PublicSubnet${Identifier}"}} }, "Condition": {"Fn::FindInMap": ["NatGateway", "Condition", {"Ref": "Identifier"}, {"DefaultValue": {"Ref": "AWS::NoValue"}}]} }, "NatGatewayAttachment${Identifier}": { "Type": "AWS::EC2::EIP", "Properties": { "Domain": "vpc" }, "Condition": {"Fn::FindInMap": ["NatGateway", "Condition", {"Ref": "Identifier"}, {"DefaultValue": {"Ref": "AWS::NoValue"}}]} } } ] } } ``` ### YAML ``` AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Conditions: TwoNatGateways: !Equals [!Ref "AWS::Region", "us-east-1"] ThreeNatGateways: !Equals [!Ref "AWS::Region", "us-west-2"] Mappings: NatGateway: Condition: B: TwoNatGateways C: ThreeNatGateways Resources: VPC: Type: AWS::EC2::VPC Properties: CidrBlock: 10.0.0.0/16 PublicSubnetA: Type: AWS::EC2::Subnet Properties: VpcId: !Ref VPC CidrBlock: 10.0.1.0/24 AvailabilityZone: !Select [0, !GetAZs ""] PublicSubnetB: Type: AWS::EC2::Subnet Properties: VpcId: !Ref VPC CidrBlock: 10.0.2.0/24 AvailabilityZone: !Select [1, !GetAZs ""] PublicSubnetC: Type: AWS::EC2::Subnet Properties: VpcId: !Ref VPC CidrBlock: 10.0.3.0/24 AvailabilityZone: !Select [2, !GetAZs ""] Fn::ForEach::NatGatewayAndEIP: - Identifier - - A - B - C - NatGateway${Identifier}: Type: AWS::EC2::NatGateway Properties: AllocationId: !GetAtt - !Sub NatGatewayAttachment${Identifier} - AllocationId SubnetId: !Ref Fn::Sub: PublicSubnet${Identifier} Condition: !FindInMap - NatGateway - Condition - !Ref Identifier - DefaultValue: !Ref AWS::NoValue NatGatewayAttachment${Identifier}: Type: AWS::EC2::EIP Properties: Domain: vpc Condition: !FindInMap - NatGateway - Condition - !Ref Identifier - DefaultValue: !Ref AWS::NoValue ``` 轉換後範本將等同於下列範本： ``` AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Conditions: TwoNatGateways: !Equals [!Ref "AWS::Region", "us-east-1"] ThreeNatGateways: !Equals [!Ref "AWS::Region", "us-west-2"] Resources: VPC: Type: AWS::EC2::VPC Properties: CidrBlock: 10.0.0.0/16 PublicSubnetA: Type: AWS::EC2::Subnet Properties: VpcId: !Ref VPC CidrBlock: 10.0.1.0/24 AvailabilityZone: !Select [0, !GetAZs ""] PublicSubnetB: Type: AWS::EC2::Subnet Properties: VpcId: !Ref VPC CidrBlock: 10.0.2.0/24 AvailabilityZone: !Select [1, !GetAZs ""] PublicSubnetC: Type: AWS::EC2::Subnet Properties: VpcId: !Ref VPC CidrBlock: 10.0.3.0/24 AvailabilityZone: !Select [2, !GetAZs ""] NatGatewayA: Type: AWS::EC2::NatGateway Properties: AllocationId: !GetAtt - NatGatewayAttachmentA - AllocationId SubnetId: !Ref PublicSubnetA NatGatewayB: Type: AWS::EC2::NatGateway Properties: AllocationId: !GetAtt - NatGatewayAttachmentB - AllocationId SubnetId: !Ref PublicSubnetB Condition: TwoNatGateways NatGatewayC: Type: AWS::EC2::NatGateway Properties: AllocationId: !GetAtt - NatGatewayAttachmentC - AllocationId SubnetId: !Ref PublicSubnetC Condition: ThreeNatGateways NatGatewayAttachmentA: Type: AWS::EC2::EIP Properties: Domain: vpc NatGatewayAttachmentB: Type: AWS::EC2::EIP Properties: Domain: vpc Condition: TwoNatGateways NatGatewayAttachmentC: Type: AWS::EC2::EIP Properties: Domain: vpc Condition: ThreeNatGateways ``` ## 使用巢狀 `Fn::ForEach` 迴圈來複寫多項資源此範例使用巢狀 `Fn::ForEach` 迴圈來相互映射三個資源 ([AWS::EC2::NetworkAcl](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ec2-natgateway.html)、[AWS::EC2::Subnet](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ec2-subnet.html) 和 [AWS::EC2::SubnetNetworkAclAssociation](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ec2-subnetnetworkaclassociation.html))。 ### JSON ``` { "AWSTemplateFormatVersion": "2010-09-09", "Transform": "AWS::LanguageExtensions", "Resources": { "VPC": { "Type": "AWS::EC2::VPC", "Properties": { "CidrBlock": "10.0.0.0/16", "EnableDnsSupport": "true", "EnableDnsHostnames": "true" } }, "Fn::ForEach::SubnetResources": [ "Prefix", [ "Transit", "Public" ], { "Nacl${Prefix}Subnet": { "Type": "AWS::EC2::NetworkAcl", "Properties": { "VpcId": { "Ref": "VPC" } } }, "Fn::ForEach::LoopInner": [ "Suffix", [ "A", "B", "C" ], { "${Prefix}Subnet${Suffix}": { "Type": "AWS::EC2::Subnet", "Properties": { "VpcId": { "Ref": "VPC" } } }, "Nacl${Prefix}Subnet${Suffix}Association": { "Type": "AWS::EC2::SubnetNetworkAclAssociation", "Properties": { "SubnetId": { "Ref": { "Fn::Sub": "${Prefix}Subnet${Suffix}" } }, "NetworkAclId": { "Ref": { "Fn::Sub": "Nacl${Prefix}Subnet" } } } } } ] } ] } } ``` ### YAML ``` AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Resources: VPC: Type: AWS::EC2::VPC Properties: CidrBlock: 10.0.0.0/16 EnableDnsSupport: 'true' EnableDnsHostnames: 'true' 'Fn::ForEach::SubnetResources': - Prefix - [Transit, Public] - 'Nacl${Prefix}Subnet': Type: AWS::EC2::NetworkAcl Properties: VpcId: !Ref 'VPC' 'Fn::ForEach::LoopInner': - Suffix - [A, B, C] - '${Prefix}Subnet${Suffix}': Type: AWS::EC2::Subnet Properties: VpcId: !Ref 'VPC' 'Nacl${Prefix}Subnet${Suffix}Association': Type: AWS::EC2::SubnetNetworkAclAssociation Properties: SubnetId: !Ref 'Fn::Sub': '${Prefix}Subnet${Suffix}' NetworkAclId: !Ref 'Fn::Sub': 'Nacl${Prefix}Subnet' ``` 轉換後範本將等同於下列範本： ``` AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Resources: VPC: Type: AWS::EC2::VPC Properties: CidrBlock: 10.0.0.0/16 EnableDnsSupport: 'true' EnableDnsHostnames: 'true' NaclTransitSubnet: Type: AWS::EC2::NetworkAcl Properties: VpcId: !Ref VPC TransitSubnetA: Type: AWS::EC2::Subnet Properties: VpcId: !Ref VPC NaclTransitSubnetAAssociation: Type: AWS::EC2::SubnetNetworkAclAssociation Properties: SubnetId: !Ref TransitSubnetA NetworkAclId: !Ref NaclTransitSubnet TransitSubnetB: Type: AWS::EC2::Subnet Properties: VpcId: !Ref VPC NaclTransitSubnetBAssociation: Type: AWS::EC2::SubnetNetworkAclAssociation Properties: SubnetId: !Ref TransitSubnetB NetworkAclId: !Ref NaclTransitSubnet TransitSubnetC: Type: AWS::EC2::Subnet Properties: VpcId: !Ref VPC NaclTransitSubnetCAssociation: Type: AWS::EC2::SubnetNetworkAclAssociation Properties: SubnetId: !Ref TransitSubnetC NetworkAclId: !Ref NaclTransitSubnet NaclPublicSubnet: Type: AWS::EC2::NetworkAcl Properties: VpcId: !Ref VPC PublicSubnetA: Type: AWS::EC2::Subnet Properties: VpcId: !Ref VPC NaclPublicSubnetAAssociation: Type: AWS::EC2::SubnetNetworkAclAssociation Properties: SubnetId: !Ref PublicSubnetA NetworkAclId: !Ref NaclPublicSubnet PublicSubnetB: Type: AWS::EC2::Subnet Properties: VpcId: !Ref VPC NaclPublicSubnetBAssociation: Type: AWS::EC2::SubnetNetworkAclAssociation Properties: SubnetId: !Ref PublicSubnetB NetworkAclId: !Ref NaclPublicSubnet PublicSubnetC: Type: AWS::EC2::Subnet Properties: VpcId: !Ref VPC NaclPublicSubnetCAssociation: Type: AWS::EC2::SubnetNetworkAclAssociation Properties: SubnetId: !Ref PublicSubnetC NetworkAclId: !Ref NaclPublicSubnet ``` ## 為 Amazon EC2 資源參考複寫的屬性此範例使用 `Fn::ForEach` 內建函數來參考複寫的 [AWS::EC2::Instance](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ec2-instance.html) 資源。 ### JSON ``` { "AWSTemplateFormatVersion": "2010-09-09", "Transform": "AWS::LanguageExtensions", "Mappings": { "Instances": { "InstanceType": { "B": "m5.4xlarge", "C": "c5.2xlarge" }, "ImageId": {"A": "ami-id1"} } }, "Resources": { "Fn::ForEach::Instances": [ "Identifier", [ "A", "B", "C" ], { "Instance${Identifier}": { "Type": "AWS::EC2::Instance", "Properties": { "InstanceType": {"Fn::FindInMap": ["Instances", "InstanceType", {"Ref": "Identifier"}, {"DefaultValue": "m5.xlarge"}]}, "ImageId": {"Fn::FindInMap": ["Instances", "ImageId", {"Ref": "Identifier"}, {"DefaultValue": "ami-id-default"}]} } } } ] }, "Outputs": { "SecondInstanceId": { "Description": "Instance Id for InstanceB", "Value": {"Ref": "InstanceB"} }, "SecondPrivateIp": { "Description": "Private IP for InstanceB", "Value": { "Fn::GetAtt": [ "InstanceB", "PrivateIp" ] } } } } ``` ### YAML ``` AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Mappings: Instances: InstanceType: B: m5.4xlarge C: c5.2xlarge ImageId: A: ami-id1 Resources: 'Fn::ForEach::Instances': - Identifier - [A, B, C] - 'Instance${Identifier}': Type: AWS::EC2::Instance Properties: InstanceType: !FindInMap [Instances, InstanceType, !Ref 'Identifier', {DefaultValue: m5.xlarge}] ImageId: !FindInMap [Instances, ImageId, !Ref 'Identifier', {DefaultValue: ami-id-default}] Outputs: SecondInstanceId: Description: Instance Id for InstanceB Value: !Ref 'InstanceB' SecondPrivateIp: Description: Private IP for InstanceB Value: !GetAtt [InstanceB, PrivateIp] ``` 轉換後範本將等同於下列範本： ``` AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Resources: InstanceA: Type: AWS::EC2::Instance Properties: InstanceType: m5.xlarge ImageId: ami-id1 InstanceB: Type: AWS::EC2::Instance Properties: InstanceType: m5.4xlarge ImageId: ami-id-default InstanceC: Type: AWS::EC2::Instance Properties: InstanceType: c5.2xlarge ImageId: ami-id-default Outputs: SecondInstanceId: Description: Instance Id for InstanceB Value: !Ref InstanceB SecondPrivateIp: Description: Private IP for InstanceB Value: !GetAtt [InstanceB, PrivateIp] ``` ## 為 Amazon EC2 資源複寫屬性此範例使用 `Fn::ForEach` 內建函數將 `ImageId`、`InstanceType` 和 `AvailabilityZone` 等部分屬性重複到 [AWS::EC2::Instance](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ec2-instance.html) 資源。 ### JSON ``` { "AWSTemplateFormatVersion": "2010-09-09", "Transform": "AWS::LanguageExtensions", "Mappings": { "InstanceA": { "Properties": { "ImageId": "ami-id1", "InstanceType": "m5.xlarge" } }, "InstanceB": { "Properties": { "ImageId": "ami-id2" } }, "InstanceC": { "Properties": { "ImageId": "ami-id3", "InstanceType": "m5.2xlarge", "AvailabilityZone": "us-east-1a" } } }, "Resources": { "Fn::ForEach::Instances": [ "InstanceLogicalId", [ "InstanceA", "InstanceB", "InstanceC" ], { "${InstanceLogicalId}": { "Type": "AWS::EC2::Instance", "Properties": { "DisableApiTermination": true, "UserData": { "Fn::Base64": { "Fn::Join": [ "", [ "#!/bin/bash\n", "yum update -y\n", "yum install -y httpd.x86_64\n", "systemctl start httpd.service\n", "systemctl enable httpd.service\n", "echo \"Hello World from $(hostname -f)\" > /var/www/html/index.html\n" ] ] } }, "Fn::ForEach::Properties": [ "PropertyName", [ "ImageId", "InstanceType", "AvailabilityZone" ], { "${PropertyName}": { "Fn::FindInMap": [ { "Ref": "InstanceLogicalId" }, "Properties", { "Ref": "PropertyName"}, { "DefaultValue": { "Ref": "AWS::NoValue" } } ] } } ] } } } ] } } ``` ### YAML ``` AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Mappings: InstanceA: Properties: ImageId: ami-id1 InstanceType: m5.xlarge InstanceB: Properties: ImageId: ami-id2 InstanceC: Properties: ImageId: ami-id3 InstanceType: m5.2xlarge AvailabilityZone: us-east-1a Resources: 'Fn::ForEach::Instances': - InstanceLogicalId - [InstanceA, InstanceB, InstanceC] - '${InstanceLogicalId}': Type: AWS::EC2::Instance Properties: DisableApiTermination: true UserData: Fn::Base64: !Sub | #!/bin/bash yum update -y yum install -y httpd.x86_64 systemctl start httpd.service systemctl enable httpd.service echo "Hello World from $(hostname -f)" > /var/www/html/index.html 'Fn::ForEach::Properties': - PropertyName - [ImageId, InstanceType, AvailabilityZone] - '${PropertyName}': 'Fn::FindInMap': - Ref: 'InstanceLogicalId' - Properties - Ref: 'PropertyName' - {DefaultValue: !Ref 'AWS::NoValue'} ``` 轉換後範本將等同於下列範本： ``` AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Resources: InstanceA: Type: AWS::EC2::Instance Properties: DisableApiTermination: true UserData: Fn::Base64: !Sub | #!/bin/bash yum update -y yum install -y httpd.x86_64 systemctl start httpd.service systemctl enable httpd.service echo "Hello World from $(hostname -f)" > /var/www/html/index.html ImageId: ami-id1 InstanceType: m5.xlarge InstanceB: Type: AWS::EC2::Instance Properties: DisableApiTermination: true UserData: Fn::Base64: !Sub | #!/bin/bash yum update -y yum install -y httpd.x86_64 systemctl start httpd.service systemctl enable httpd.service echo "Hello World from $(hostname -f)" > /var/www/html/index.html ImageId: ami-id2 InstanceC: Type: AWS::EC2::Instance Properties: DisableApiTermination: true UserData: Fn::Base64: !Sub | #!/bin/bash yum update -y yum install -y httpd.x86_64 systemctl start httpd.service systemctl enable httpd.service echo "Hello World from $(hostname -f)" > /var/www/html/index.html ImageId: ami-id3 InstanceType: m5.2xlarge AvailabilityZone: us-east-1a ``` ## 在 `Fn::ForEach` 的 `Collection` 內傳遞非英數字元此範例使用 `&{}` 語法，允許 IP 位址中的非英數字元 (`.` 和 `/`) 在 `Collection` 內傳遞。 ### JSON ``` { "AWSTemplateFormatVersion": "2010-09-09", "Transform": "AWS::LanguageExtensions", "Parameters": { "IpAddresses": { "Type": "CommaDelimitedList", "Default": "10.0.2.0/24,10.0.3.0/24,10.0.4.0/24" } }, "Resources": { "VPC": { "Type": "AWS::EC2::VPC", "Properties": { "CidrBlock": "10.0.0.0/16", "EnableDnsSupport": "true", "EnableDnsHostnames": "true" } }, "Fn::ForEach::Subnets": [ "CIDR", { "Ref": "IpAddresses" }, { "Subnet&{CIDR}": { "Type": "AWS::EC2::Subnet", "Properties": { "VpcId": { "Ref": "VPC" }, "CidrBlock": { "Ref": "CIDR" } } } } ] } } ``` ### YAML ``` AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Parameters: IpAddresses: Type: CommaDelimitedList Default: '10.0.2.0/24,10.0.3.0/24,10.0.4.0/24' Resources: VPC: Type: AWS::EC2::VPC Properties: CidrBlock: 10.0.0.0/16 EnableDnsSupport: 'true' EnableDnsHostnames: 'true' 'Fn::ForEach::Subnets': - CIDR - !Ref IpAddresses - 'Subnet&{CIDR}': Type: AWS::EC2::Subnet Properties: VpcId: !Ref VPC CidrBlock: !Ref CIDR ``` 轉換後範本將等同於下列範本： ``` AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Parameters: IpAddresses: Type: CommaDelimitedList Default: '10.0.2.0/24,10.0.3.0/24,10.0.4.0/24' Resources: VPC: Type: AWS::EC2::VPC Properties: CidrBlock: 10.0.0.0/16 EnableDnsSupport: 'true' EnableDnsHostnames: 'true' Subnet1002024: Type: AWS::EC2::Subnet Properties: VpcId: !Ref VPC CidrBlock: 10.0.2.0/24 Subnet1003024: Type: AWS::EC2::Subnet Properties: VpcId: !Ref VPC CidrBlock: 10.0.3.0/24 Subnet1004024: Type: AWS::EC2::Subnet Properties: VpcId: !Ref VPC CidrBlock: 10.0.4.0/24 ``` # `Outputs` 區段中的 `Fn::ForEach` 範例這些範例會示範如何使用 `Outputs` 區段中的 `Fn::ForEach` 內部函數。如需有關此區段的詳細資訊，請參閱《AWS CloudFormation 使用者指南》**中的[輸出](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html)。 **Topics** + [參考複寫的 `AWS::S3::Bucket` 資源](#intrinsic-function-reference-foreach-example-replicate-outputs) + [參考複寫的 `AWS::EC2::Instance` 資源](#intrinsic-function-reference-foreach-example-replicate-conditions) ## 參考複寫的 `AWS::S3::Bucket` 資源此範例會使用 `Outputs` 區段中的巢狀 `Fn::ForEach` 迴圈，來縮短範本長度。 ### JSON ``` { "AWSTemplateFormatVersion": "2010-09-09", "Transform": "AWS::LanguageExtensions", "Resources": { "Fn::ForEach::Buckets": [ "Identifier", [ "A", "B", "C" ], { "S3Bucket${Identifier}": { "Type": "AWS::S3::Bucket", "Properties": { "AccessControl": "PublicRead", "MetricsConfigurations": [ { "Id": {"Fn::Sub": "EntireBucket${Identifier}"} } ], "WebsiteConfiguration": { "IndexDocument": "index.html", "ErrorDocument": "error.html", "RoutingRules": [ { "RoutingRuleCondition": { "HttpErrorCodeReturnedEquals": "404", "KeyPrefixEquals": "out1/" }, "RedirectRule": { "HostName": "ec2-11-22-333-44.compute-1.amazonaws.com", "ReplaceKeyPrefixWith": "report-404/" } } ] } }, "DeletionPolicy": "Retain", "UpdateReplacePolicy": "Retain" } } ] }, "Outputs": { "Fn::ForEach::BucketOutputs": [ "Identifier", [ "A", "B", "C" ], { "Fn::ForEach::GetAttLoop": [ "Property", [ "Arn", "DomainName", "WebsiteURL" ], { "S3Bucket${Identifier}${Property}": { "Value": {"Fn::GetAtt": [{"Fn::Sub": "S3Bucket${Identifier}"}, {"Ref": "Property"}]} } } ] } ] } } ``` ### YAML ``` AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Resources: 'Fn::ForEach::Buckets': - Identifier - [A, B, C] - 'S3Bucket${Identifier}': Type: AWS::S3::Bucket Properties: AccessControl: PublicRead MetricsConfigurations: - Id: !Sub 'EntireBucket${Identifier}' WebsiteConfiguration: IndexDocument: index.html ErrorDocument: error.html RoutingRules: - RoutingRuleCondition: HttpErrorCodeReturnedEquals: '404' KeyPrefixEquals: out1/ RedirectRule: HostName: ec2-11-22-333-44.compute-1.amazonaws.com ReplaceKeyPrefixWith: report-404/ DeletionPolicy: Retain UpdateReplacePolicy: Retain Outputs: 'Fn::ForEach::BucketOutputs': - Identifier - [A, B, C] - 'Fn::ForEach::GetAttLoop': - Property - [Arn, DomainName, WebsiteURL] - 'S3Bucket${Identifier}${Property}': Value: !GetAtt [!Sub 'S3Bucket${Identifier}', !Ref Property] ``` 轉換後範本將等同於下列範本： ``` AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Resources: S3BucketA: Type: AWS::S3::Bucket Properties: AccessControl: PublicRead MetricsConfigurations: - Id: EntireBucketA WebsiteConfiguration: IndexDocument: index.html ErrorDocument: error.html RoutingRules: - RoutingRuleCondition: HttpErrorCodeReturnedEquals: '404' KeyPrefixEquals: out1/ RedirectRule: HostName: ec2-11-22-333-44.compute-1.amazonaws.com ReplaceKeyPrefixWith: report-404/ DeletionPolicy: Retain UpdateReplacePolicy: Retain S3BucketB: Type: AWS::S3::Bucket Properties: AccessControl: PublicRead MetricsConfigurations: - Id: EntireBucketB WebsiteConfiguration: IndexDocument: index.html ErrorDocument: error.html RoutingRules: - RoutingRuleCondition: HttpErrorCodeReturnedEquals: '404' KeyPrefixEquals: out1/ RedirectRule: HostName: ec2-11-22-333-44.compute-1.amazonaws.com ReplaceKeyPrefixWith: report-404/ DeletionPolicy: Retain UpdateReplacePolicy: Retain S3BucketC: Type: AWS::S3::Bucket Properties: AccessControl: PublicRead MetricsConfigurations: - Id: EntireBucketC WebsiteConfiguration: IndexDocument: index.html ErrorDocument: error.html RoutingRules: - RoutingRuleCondition: HttpErrorCodeReturnedEquals: '404' KeyPrefixEquals: out1/ RedirectRule: HostName: ec2-11-22-333-44.compute-1.amazonaws.com ReplaceKeyPrefixWith: report-404/ DeletionPolicy: Retain UpdateReplacePolicy: Retain Outputs: S3BucketAArn: Value: !GetAtt [S3BucketA, Arn] S3BucketADomainName: Value: !GetAtt [S3BucketA, DomainName] S3BucketAWebsiteURL: Value: !GetAtt [S3BucketA, WebsiteURL] S3BucketBArn: Value: !GetAtt [S3BucketB, Arn] S3BucketBDomainName: Value: !GetAtt [S3BucketB, DomainName] S3BucketBWebsiteURL: Value: !GetAtt [S3BucketB, WebsiteURL] S3BucketCArn: Value: !GetAtt [S3BucketC, Arn] S3BucketCDomainName: Value: !GetAtt [S3BucketC, DomainName] S3BucketCWebsiteURL: Value: !GetAtt [S3BucketC, WebsiteURL] ``` ## 參考複寫的 `AWS::EC2::Instance` 資源此範例使用產生的邏輯 ID，在 `Resources` 區段中參考複寫的資源。 ### JSON ``` { "AWSTemplateFormatVersion": "2010-09-09", "Transform": "AWS::LanguageExtensions", "Mappings": { "Instances": { "InstanceType": { "B": "m5.4xlarge", "C": "c5.2xlarge" }, "ImageId": {"A": "ami-id1"} } }, "Resources": { "Fn::ForEach::Instances": [ "Identifier", [ "A", "B", "C" ], { "Instance${Identifier}": { "Type": "AWS::EC2::Instance", "Properties": { "InstanceType": {"Fn::FindInMap": ["Instances", "InstanceType", {"Ref": "Identifier"}, {"DefaultValue": "m5.xlarge"}]}, "ImageId": {"Fn::FindInMap": ["Instances", "ImageId", {"Ref": "Identifier"}, {"DefaultValue": "ami-id-default"}]} } } } ] }, "Outputs": { "SecondInstanceId": { "Description": "Instance Id for InstanceB", "Value": {"Ref": "InstanceB"} }, "SecondPrivateIp": { "Description": "Private IP for InstanceB", "Value": { "Fn::GetAtt": [ "InstanceB", "PrivateIp" ] } } } } ``` ### YAML ``` AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Mappings: Instances: InstanceType: B: m5.4xlarge C: c5.2xlarge ImageId: A: ami-id1 Resources: 'Fn::ForEach::Instances': - Identifier - [A, B, C] - 'Instance${Identifier}': Type: AWS::EC2::Instance Properties: InstanceType: !FindInMap [Instances, InstanceType, !Ref Identifier, DefaultValue: m5.xlarge] ImageId: !FindInMap [Instances, ImageId, !Ref Identifier, DefaultValue: ami-id-default] Outputs: SecondInstanceId: Description: Instance Id for InstanceB Value: !Ref InstanceB SecondPrivateIp: Description: Private IP for InstanceB Value: !GetAtt [InstanceB, PrivateIp] ``` 轉換後範本將等同於下列範本： ``` AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Resources: InstanceA: Type: AWS::EC2::Instance Properties: InstanceType: m5.xlarge ImageId: ami-id1 InstanceB: Type: AWS::EC2::Instance Properties: InstanceType: m5.4xlarge ImageId: ami-id-default InstanceC: Type: AWS::EC2::Instance Properties: InstanceType: c5.2xlarge ImageId: ami-id-default Outputs: SecondInstanceId: Description: Instance Id for InstanceB Value: !Ref InstanceB SecondPrivateIp: Description: Private IP for InstanceB Value: !GetAtt [InstanceB, PrivateIp] ``` # `Conditions` 區段中的 `Fn::ForEach` 範例這些範例會示範如何使用 `Conditions` 區段中的 `Fn::ForEach` 內部函數。如需有關此區段的詳細資訊，請參閱《AWS CloudFormation 使用者指南》**中的[條件](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/conditions-section-structure.html)。 **重要** `Conditions` 必須是列出的第二個屬性，或更高版本。如果 `Conditions` 是 `Fn::ForEach` 的範本片段參數中列出的第一個屬性，則堆疊建立將會失敗。 ``` Resources: 'Fn::ForEach::Topics': - LogicalId - !Ref TopicList - '${LogicalId}': Condition: !Sub 'TopicCondition${LogicalId}' Type: AWS::SNS::Topic Properties: TopicName: !Sub 'My${LogicalId}' ``` `Conditions` 必須以第二個金鑰 (或更高版本) 來新增，才能順利建立堆疊： ``` Resources: 'Fn::ForEach::Topics': - LogicalId - !Ref TopicList - '${LogicalId}': Type: AWS::SNS::Topic Condition: !Sub 'TopicCondition${LogicalId}' Properties: TopicName: !Sub 'My${LogicalId}' ``` **Topics** + [複寫單一條件](#intrinsic-function-reference-foreach-example-replicated-single-condition) ## 複寫單一條件此範例會使用 `Conditions` 區段中的 `Fn::ForEach` 內部函數，來複寫具有不同屬性的多個類似條件。 ### JSON ``` { "AWSTemplateFormatVersion": "2010-09-09", "Transform": "AWS::LanguageExtensions", "Parameters": { "ParamA": { "Type": "String", "AllowedValues": [ "true", "false" ] }, "ParamB": { "Type": "String", "AllowedValues": [ "true", "false" ] }, "ParamC": { "Type": "String", "AllowedValues": [ "true", "false" ] }, "ParamD": { "Type": "String", "AllowedValues": [ "true", "false" ] } }, "Conditions": { "Fn::ForEach::CheckTrue": [ "Identifier", ["A", "B", "C", "D"], { "IsParam${Identifier}Enabled": { "Fn::Equals": [ {"Ref": {"Fn::Sub": "Param${Identifier}"}}, "true" ] } } ] }, "Resources": { "WaitConditionHandle": { "Type": "AWS::CloudFormation::WaitConditionHandle" } } } ``` ### YAML ``` AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Parameters: ParamA: Type: String AllowedValues: - 'true' - 'false' ParamB: Type: String AllowedValues: - 'true' - 'false' ParamC: Type: String AllowedValues: - 'true' - 'false' ParamD: Type: String AllowedValues: - 'true' - 'false' Conditions: 'Fn::ForEach::CheckTrue': - Identifier - [A, B, C, D] - 'IsParam${Identifier}Enabled': !Equals - !Ref 'Fn::Sub': 'Param${Identifier}' - 'true' Resources: WaitConditionHandle: Type: AWS::CloudFormation::WaitConditionHandle ``` 轉換後範本將等同於下列範本： ``` AWSTemplateFormatVersion: 2010-09-09 Parameters: ParamA: Type: String AllowedValues: - 'true' - 'false' ParamB: Type: String AllowedValues: - 'true' - 'false' ParamC: Type: String AllowedValues: - 'true' - 'false' ParamD: Type: String AllowedValues: - 'true' - 'false' Conditions: IsParamAEnabled: !Equals - !Ref ParamA - 'true' IsParamBEnabled: !Equals - !Ref ParamB - 'true' IsParamCEnabled: !Equals - !Ref ParamC - 'true' IsParamDEnabled: !Equals - !Ref ParamD - 'true' Resources: WaitConditionHandle: Type: AWS::CloudFormation::WaitConditionHandle ``` # `Fn::GetAtt` `Fn::GetAtt` 內部函數從範本中的資源傳回屬性值。 ## 宣告 ### JSON ``` { "Fn::GetAtt" : [ "logicalNameOfResource", "attributeName" ] } ``` ### YAML 完整函式名稱的語法： ``` Fn::GetAtt: [ logicalNameOfResource, attributeName ] ``` 短格式的語法： ``` !GetAtt logicalNameOfResource.attributeName ``` ## Parameters `logicalNameOfResource` 其中包含您所需屬性之資源的邏輯名稱 (也稱為*邏輯 ID*)。 `attributeName` 您需要的資源特定屬性的名稱。有關該資源類型可用屬性的詳細資訊，請參閱該資源的參考頁面。 ## 傳回值屬性值。如需有關資源的 `GetAtt` 傳回值的詳細資訊，請參閱 [資源和屬性參考](aws-template-resource-type-ref.md) 中資源文件。 ## 範例 ### 傳回屬性值下列範例會傳回一個字串，其中包含負載平衡器的 DNS 名稱，邏輯名稱為 `myELB`。 #### JSON ``` "Fn::GetAtt" : [ "myELB" , "DNSName" ] ``` #### YAML ``` !GetAtt myELB.DNSName ``` #### 傳回多個屬性值以下範例會傳回負載平衡器的 `SourceSecurityGroup.OwnerAlias` 和 `SourceSecurityGroup.GroupName`，邏輯名稱為 `myELB`。 ##### JSON ``` { "AWSTemplateFormatVersion": "2010-09-09", "Resources": { "myELB": { "Type": "AWS::ElasticLoadBalancing::LoadBalancer", "Properties": { "AvailabilityZones": [ "eu-west-1a" ], "Listeners": [ { "LoadBalancerPort": "80", "InstancePort": "80", "Protocol": "HTTP" } ] } }, "myELBIngressGroup": { "Type": "AWS::EC2::SecurityGroup", "Properties": { "GroupDescription": "ELB ingress group", "SecurityGroupIngress": [ { "IpProtocol": "tcp", "FromPort": 80, "ToPort": 80, "SourceSecurityGroupOwnerId": { "Fn::GetAtt": [ "myELB", "SourceSecurityGroup.OwnerAlias" ] }, "SourceSecurityGroupName": { "Fn::GetAtt": [ "myELB", "SourceSecurityGroup.GroupName" ] } } ] } } } } ``` ##### YAML ``` AWSTemplateFormatVersion: 2010-09-09 Resources: myELB: Type: AWS::ElasticLoadBalancing::LoadBalancer Properties: AvailabilityZones: - eu-west-1a Listeners: - LoadBalancerPort: '80' InstancePort: '80' Protocol: HTTP myELBIngressGroup: Type: AWS::EC2::SecurityGroup Properties: GroupDescription: ELB ingress group SecurityGroupIngress: - IpProtocol: tcp FromPort: 80 ToPort: 80 SourceSecurityGroupOwnerId: !GetAtt myELB.SourceSecurityGroup.OwnerAlias SourceSecurityGroupName: !GetAtt myELB.SourceSecurityGroup.GroupName ``` #### 使用 `Fn::GetAtt` 函數內的 `Fn::Sub` **注意** 使用 `AWS::LanguageExtensions` 轉換時，您可以搭配其他內建函數使用 `Fn::GetAtt`。如需支援的函數，請參閱 [支援的函數](#getatt-supported-functions)。下列範例顯示如何在範本的 `Outputs` 區段中搭配使用 `Fn::GetAtt`、[`Fn::Sub`](intrinsic-function-reference-sub.md) 和 [`Fn::ForEach`](intrinsic-function-reference-foreach.md)，以縮短範本的長度並降低詳細程度。在 `Fn::GetAtt` 中使用 `Fn::Sub`，以允許範本包含一個可在 `Fn::ForEach` 呼叫每次重複時參考不同儲存貯體的內部函數。 ##### JSON ``` { "AWSTemplateFormatVersion": "2010-09-09", "Transform": "AWS::LanguageExtensions", "Mappings": { "Buckets": { "Properties": { "Identifiers": ["A", "B", "C"] } } }, "Resources": { "Fn::ForEach::Buckets": [ "Identifier", {"Fn::FindInMap": ["Buckets", "Properties", "Identifiers"]}, { "S3Bucket${Identifier}": { "Type": "AWS::S3::Bucket", "Properties": { "AccessControl": "PublicRead", "MetricsConfigurations": [ { "Id": {"Fn::Sub": "EntireBucket${Identifier}"} } ], "WebsiteConfiguration": { "IndexDocument": "index.html", "ErrorDocument": "error.html", "RoutingRules": [ { "RoutingRuleCondition": { "HttpErrorCodeReturnedEquals": "404", "KeyPrefixEquals": "out1/" }, "RedirectRule": { "HostName": "ec2-11-22-333-44.compute-1.amazonaws.com", "ReplaceKeyPrefixWith": "report-404/" } } ] } }, "DeletionPolicy": "Retain", "UpdateReplacePolicy": "Retain" } } ] }, "Outputs": { "Fn::ForEach::BucketOutputs": [ "Identifier", {"Fn::FindInMap": ["Buckets", "Properties", "Identifiers"]}, { "Fn::ForEach::GetAttLoop": [ "Property", ["Arn", "DomainName", "WebsiteURL"], { "S3Bucket${Identifier}${Property}": { "Value": { "Fn::GetAtt": [{"Fn::Sub": "S3Bucket${Identifier}"}, {"Ref": "Property"}] } } } ] } ] } } ``` ##### YAML ``` AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Mappings: Buckets: Properties: Identifiers: - A - B - C Resources: 'Fn::ForEach::Buckets': - Identifier - Fn::FindInMap: - Buckets - Properties - Identifiers - 'S3Bucket${Identifier}': Type: AWS::S3::Bucket Properties: AccessControl: PublicRead MetricsConfigurations: - Id: Fn::Sub: 'EntireBucket${Identifier}' WebsiteConfiguration: IndexDocument: index.html ErrorDocument: error.html RoutingRules: - RoutingRuleCondition: HttpErrorCodeReturnedEquals: '404' KeyPrefixEquals: out1/ RedirectRule: HostName: ec2-11-22-333-44.compute-1.amazonaws.com ReplaceKeyPrefixWith: report-404/ DeletionPolicy: Retain UpdateReplacePolicy: Retain Outputs: 'Fn::ForEach::BucketOutputs': - Identifier - Fn::FindInMap: - Buckets - Properties - Identifiers - 'Fn::ForEach::GetAttLoop': - Property - - Arn - DomainName - WebsiteURL - 'S3Bucket${Identifier}${Property}': Value: !GetAtt - !Sub 'S3Bucket${Identifier}' - !Ref Property ``` ## 支援的函數當使用 [AWS::LanguageExtensions 轉換](transform-aws-languageextensions.md)時，可以使用 `Fn::GetAtt` 函數內的以下函數。對於 `Fn::GetAtt` 邏輯資源名稱或 `Fn::GetAtt` 屬性名稱都是如此。 + [`Fn::Base64`](intrinsic-function-reference-base64.md) + [`Fn::FindInMap`](intrinsic-function-reference-findinmap.md) + [`Fn::If`](intrinsic-function-reference-conditions.md#intrinsic-function-reference-conditions-if) + [`Fn::Join`](intrinsic-function-reference-join.md) + [`Fn::Sub`](intrinsic-function-reference-sub.md) + [`Fn::ToJsonString`](intrinsic-function-reference-ToJsonString.md) + [`Ref`](intrinsic-function-reference-ref.md) 當未使用 `AWS::LanguageExtensions` 轉換時： + `Fn::GetAtt` 屬性名稱只能使用 [`Ref`](intrinsic-function-reference-ref.md) 函數。 + `Fn::GetAtt` 邏輯資源名稱無法使用函數。您必須指定資源的邏輯 ID 字串。 # `Fn::GetAZs` `Fn::GetAZs` 內部函數會傳回陣列，以按字母順序列出指定區域的可用區域。由於客戶可以存取不同可用區域，因此 `Fn::GetAZs` 內部函數可讓範本作者撰寫範本來因應呼叫使用者的存取。如此一來，您就不需要將特定區域的可用區域完整清單寫死。 **重要** `Fn::GetAZs` 函數只會傳回具有預設子網路的可用區域；在沒有任何可用區域具備預設子網路的情況下，則會傳回所有可用區域。與 `describe-availability-zones` AWS CLI 命令的回應類似，不保證`Fn::GetAZs`函數的結果順序，並且可能會在新增新的可用區域時變更。 IAM 許可為了使用 `Fn::GetAZs` 函數，您需要具備的許可取決於 Amazon EC2 執行個體的啟動平台而定。針對這兩種平台，您需要 Amazon EC2 `DescribeAvailabilityZones` 和 `DescribeAccountAttributes` 動作的許可。針對 EC2-VPC，您也需要 Amazon EC2 `DescribeSubnets` 動作的許可。 ## 宣告 ### JSON ``` { "Fn::GetAZs" : "region" } ``` ### YAML 完整函式名稱的語法： ``` Fn::GetAZs: region ``` 短格式的語法： ``` !GetAZs region ``` ## Parameters region 您想要取得其可用區域的區域名稱。您可以使用 `AWS::Region` 虛擬參數來指定建立堆疊的區域。指定空白字串就相當於指定 `AWS::Region`。 ## 傳回值區域的可用區域清單。 ## 範例 ### 評估區域針對這些範例，CloudFormation 會依據下列陣列評估 `Fn::GetAZs` — 假設使用者已在 `us-east-1` 區域中建立堆疊： `[ "us-east-1a", "us-east-1b", "us-east-1c", "us-east-1d", "us-east-1e" ]` #### JSON ``` 1. { "Fn::GetAZs" : "" } 2. { "Fn::GetAZs" : { "Ref" : "AWS::Region" } } 3. { "Fn::GetAZs" : "us-east-1" } ``` #### YAML ``` 1. Fn::GetAZs: "" 2. Fn::GetAZs: 3. Ref: "AWS::Region" 4. Fn::GetAZs: us-east-1 ``` ### 指定子網路的可用區域下列範例使用 `Fn::GetAZs` 指定子網路的可用區域： #### JSON ``` "mySubnet" : { "Type" : "AWS::EC2::Subnet", "Properties" : { "VpcId" : { "Ref" : "VPC" }, "CidrBlock" : "10.0.0.0/24", "AvailabilityZone" : { "Fn::Select" : [ 0, { "Fn::GetAZs" : "" } ] } } } ``` #### YAML ``` mySubnet: Type: AWS::EC2::Subnet Properties: VpcId: !Ref VPC CidrBlock: 10.0.0.0/24 AvailabilityZone: Fn::Select: - 0 - Fn::GetAZs: "" ``` ### 使用簡短格式 YAML 的巢狀函數下列範例說明以簡短格式 YAML 使用巢狀內部函數的有效模式。您不可以連續巢狀短格式函數，因此類似 `!GetAZs !Ref` 的模式是無效的。 #### YAML ``` 1. AvailabilityZone: !Select 2. - 0 3. - !GetAZs 4. Ref: 'AWS::Region' ``` #### YAML ``` 1. AvailabilityZone: !Select 2. - 0 3. - Fn::GetAZs: !Ref 'AWS::Region' ``` ## 支援的函數您可以在 `Ref` 函數中使用 `Fn::GetAZs` 函數。 # `Fn::ImportValue` 內部函數會`Fn::ImportValue`傳回另一個堆疊匯出的輸出值。此函數通常可用來建立跨堆疊參考。如需詳細資訊，請參閱**《AWS CloudFormation 使用者指南》中的[逐步解說：參考其他 CloudFormation 堆疊中的資源輸出](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/walkthrough-crossstackref.html)。在下列範本程式碼片段的範例中，堆疊 A 會匯出 VPC 安全群組值，而堆疊 B 則會匯入該數值。 **注意** 下列限制適用於跨堆疊參考：對於每個名稱 AWS 帳戶，`Export`名稱在區域中必須是唯一的。您無法跨區域建立跨堆疊參考。您可以使用內部函數 `Fn::ImportValue`，僅匯入已在同一區域內匯出的值。對於輸出，`Export` 的 `Name` 屬性值無法使用依賴某個資源的 `Ref` 或者 `GetAtt` 函數。同樣，`ImportValue` 函數不能包含依賴某個資源的 `Ref` 或 `GetAtt` 函數。當其他堆疊匯入輸出值之後，您就無法刪除匯出輸出值的堆疊，也無法修改匯出的輸出值。您必須先移除所有匯入，之後才可以刪除匯出堆疊或修改輸出值。 ## JSON 堆疊 A 匯出結果 ``` "Outputs" : { "PublicSubnet" : { "Description" : "The subnet ID to use for public web servers", "Value" : { "Ref" : "PublicSubnet" }, "Export" : { "Name" : {"Fn::Sub": "${AWS::StackName}-SubnetID" }} }, "WebServerSecurityGroup" : { "Description" : "The security group ID to use for public web servers", "Value" : { "Fn::GetAtt" : ["WebServerSecurityGroup", "GroupId"] }, "Export" : { "Name" : {"Fn::Sub": "${AWS::StackName}-SecurityGroupID" }} } } ``` ## YAML 堆疊 A 匯出結果 ``` Outputs: PublicSubnet: Description: The subnet ID to use for public web servers Value: Ref: PublicSubnet Export: Name: 'Fn::Sub': '${AWS::StackName}-SubnetID' WebServerSecurityGroup: Description: The security group ID to use for public web servers Value: 'Fn::GetAtt': - WebServerSecurityGroup - GroupId Export: Name: 'Fn::Sub': '${AWS::StackName}-SecurityGroupID' ``` ## JSON 堆疊 B 匯入結果 ``` "Resources" : { "WebServerInstance" : { "Type" : "AWS::EC2::Instance", "Properties" : { "InstanceType" : "t2.micro", "ImageId" : "ami-a1b23456", "NetworkInterfaces" : [{ "GroupSet" : [{"Fn::ImportValue" : {"Fn::Sub" : "${NetworkStackNameParameter}-SecurityGroupID"}}], "AssociatePublicIpAddress" : "true", "DeviceIndex" : "0", "DeleteOnTermination" : "true", "SubnetId" : {"Fn::ImportValue" : {"Fn::Sub" : "${NetworkStackNameParameter}-SubnetID"}} }] } } } ``` ## YAML 堆疊 B 匯入結果 ``` Resources: WebServerInstance: Type: AWS::EC2::Instance Properties: InstanceType: t2.micro ImageId: ami-a1b23456 NetworkInterfaces: - GroupSet: - Fn::ImportValue: 'Fn::Sub': '${NetworkStackNameParameter}-SecurityGroupID' AssociatePublicIpAddress: 'true' DeviceIndex: '0' DeleteOnTermination: 'true' SubnetId: Fn::ImportValue: 'Fn::Sub': '${NetworkStackNameParameter}-SubnetID' ``` ## 宣告 ### JSON ``` { "Fn::ImportValue" : sharedValueToImport } ``` ### YAML 您可以使用完整的函數名稱： ``` Fn::ImportValue: sharedValueToImport ``` 或者，您也可以使用較短的名稱： ``` !ImportValue sharedValueToImport ``` **重要** 若 `!ImportValue` 包含簡短格式的 `!Sub`，則您將無法使用它的簡短格式。 ``` # do not use !ImportValue !Sub '${NetworkStack}-SubnetID' ``` 對此，您必須使用完整的函數名稱，如下所示： ``` Fn::ImportValue: !Sub "${NetworkStack}-SubnetID" ``` ## Parameters sharedValueToImport 您想要匯入的堆疊輸出值。 ## 傳回值堆疊的輸出值。 ## 範例 ### JSON ``` { "Fn::ImportValue" : {"Fn::Sub": "${NetworkStackNameParameter}-SubnetID" } } ``` ### YAML ``` Fn::ImportValue: !Sub "${NetworkStackName}-SecurityGroupID" ``` ## 支援的函數您可以在 `Fn::ImportValue` 函數中善用以下函數，但您無法使用某個資源決定這些函數值。 + `Fn::Base64` + `Fn::FindInMap` + `Fn::If` + `Fn::Join` + `Fn::Select` + `Fn::Sub` + `Ref` # `Fn::Join` 透過 `Fn::Join` 內部函數，即可將一組值附加至單一值，並以指定的分隔符號隔開。如果分隔符號是空白字串，系統即會串連這一組值，而不使用分隔符號。 ## 宣告 ### JSON ``` { "Fn::Join" : [ "delimiter", [ comma-delimited list of values ] ] } ``` ### YAML 完整函式名稱的語法： ``` Fn::Join: [ delimiter, [ comma-delimited list of values ] ] ``` 短格式的語法： ``` !Join [ delimiter, [ comma-delimited list of values ] ] ``` ## Parameters 分隔符號要在片段之間執行的值。分隔符號僅會出現在片段之間，且不會終止最後的值。 ListOfValues 要合併的數值清單。 ## 傳回值合併的字串。 ## 範例 ### 聯結簡單的字串陣列以下範例傳回：`"a:b:c"`。 #### JSON ``` "Fn::Join" : [ ":", [ "a", "b", "c" ] ] ``` #### YAML ``` !Join [ ":", [ a, b, c ] ] ``` ### 使用搭配參數的 Ref 函數進行聯結以下範例會使用 `Fn::Join` 來建構字串值，且將搭配 `Ref` 函數、`AWS::Partition` 參數和 `AWS::AccountId` 虛擬參數一起使用。 #### JSON ``` { "Fn::Join": [ "", [ "arn:", { "Ref": "AWS::Partition" }, ":s3:::elasticbeanstalk-*-", { "Ref": "AWS::AccountId" } ] ] } ``` #### YAML ``` !Join - '' - - 'arn:' - !Ref AWS::Partition - ':s3:::elasticbeanstalk-*-' - !Ref AWS::AccountId ``` **注意** 如需了解類似功能，另請參閱 [`Fn::Sub`](intrinsic-function-reference-sub.md) 函數。 ## 支援的函數對於 `Fn::Join` 分隔符號，您不能使用任何函數。您必須指定一個字串值。對於值的 `Fn::Join` 清單，您可以使用下列函數： + `Fn::Base64` + `Fn::FindInMap` + `Fn::GetAtt` + `Fn::GetAZs` + `Fn::If` + `Fn::ImportValue` + `Fn::Join` + `Fn::Split` + `Fn::Select` + `Fn::Sub` + `Ref` # `Fn::Length` `Fn::Length` 內部函數會傳回陣列或用以傳回陣列的內部函數中的元素數量。 **重要** 您必須使用 [`AWS::LanguageExtensions` 轉換程序](transform-aws-languageextensions.md) 才能使用 `Fn::Length` 內部函數。 ## 宣告 ### JSON ``` { "Fn::Length" : IntrinsicFunction } ``` ``` { "Fn::Length" : Array } ``` ### YAML ``` Fn::Length : IntrinsicFunction ``` ``` Fn::Length : Array ``` ## Parameters `IntrinsicFunction` 此內部函數會傳回要從中傳回多個元素的陣列。 `Array` 要從中傳回元素數量的陣列。 ## 傳回值傳回陣列的內部函數中的元素數量，或傳遞至內部函數的陣列中的元素數量。 ## 範例 ### 傳回用以傳回陣列的內部函數中的元素數量此範例程式碼片段會傳回用以傳回陣列的內部函數中的元素數量。該函數會傳回 3。 #### JSON ``` { //... "Transform": "AWS::LanguageExtensions" //... "Fn::Length" : { "Fn::Split": ["|", "a|b|c"] } //... } ``` #### YAML ``` Transform: 'AWS::LanguageExtensions' #... Fn::Length: !Split ["|", "a|b|c"] #... ``` ### 傳回參考清單參數類型的 Ref 內部函數中的元素數量此範例程式碼片段會傳回參考清單參數類型的 `Ref` 內部函數中的元素數量。如果名稱為 `ListParameter` 的參數是一個包含 3 個元素的清單，則函數會傳回 3。 #### JSON ``` { //... "Transform": "AWS::LanguageExtensions" //... "Fn::Length": { "Ref": "ListParameter" } //... } ``` #### YAML ``` Transform: 'AWS::LanguageExtensions' #... Fn::Length: !Ref ListParameter #... ``` ### 傳回陣列中的元素數量此範例程式碼片段會傳回傳遞至內部函數的陣列中的元素數量。該函數會傳回 3。 #### JSON ``` 1. { 2. //... 3. "Transform": "AWS::LanguageExtensions" 4. //... 5. "Fn::Length": [ 6. 1, 7. {"Ref": "ParameterName"}, 8. 3 9. ] 10. //... 11. } ``` #### YAML ``` Transform: 'AWS::LanguageExtensions' #... Fn::Length: - 1 - !Ref ParameterName - 3 #... ``` ## 支援的函數您可以在 `Fn::Length` 內部函數或陣列中使用下列函數： + `Condition Functions` + `Fn::Base64` + `Fn::FindInMap` + `Fn::Join` + `Fn::Length` + `Fn::Select` + `Fn::Split` + `Fn::Sub` + `Fn::ToJsonString` + `Ref` # `Fn::Select` 內部函數 `Fn::Select` 會依據索引從物件清單傳回單一物件。 **重要** `Fn::Select` 不會檢查空值或索引是否超出陣列邊界。上述兩個情況都將會導致堆疊錯誤，因此您應該確定您選擇的索引是有效的，而且清單包含非空值。 ## 宣告 ### JSON ``` { "Fn::Select" : [ index, listOfObjects ] } ``` ### YAML 完整函式名稱的語法： ``` Fn::Select: [ index, listOfObjects ] ``` 短格式的語法： ``` !Select [ index, listOfObjects ] ``` ## Parameters index 要擷取之物件的索引。這必須是從 0 至 N-1 的值，其中 N 代表陣列中的元素數目。 listOfObjects 要從中選取的物件清單。此清單不得為空，也不能有空項目。 ## 傳回值選取的物件。 ## 範例 ### 基本範例以下範例傳回：`"grapes"`。 #### JSON ``` { "Fn::Select" : [ "1", [ "apples", "grapes", "oranges", "mangoes" ] ] } ``` #### YAML ``` !Select [ "1", [ "apples", "grapes", "oranges", "mangoes" ] ] ``` ### 逗號分隔清單參數類型您可以使用 `Fn::Select` 從 `CommaDelimitedList` 參數選取物件。您可以使用 `CommaDelimitedList` 參數來結合相關參數的值，這可減少範本中的參數總數。例如，以下參數指定以逗號分隔的三個 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" ``` 若要指定三個 CIDR 區塊其中之一，請使用相同範本之 Resource (資源) 區段中的 `Fn::Select`，如以下範例程式碼片段所示： #### JSON ``` "Subnet0": { "Type": "AWS::EC2::Subnet", "Properties": { "VpcId": { "Ref": "VPC" }, "CidrBlock": { "Fn::Select" : [ "0", {"Ref": "DbSubnetIpBlocks"} ] } } } ``` #### YAML ``` Subnet0: Type: AWS::EC2::Subnet Properties: VpcId: !Ref VPC CidrBlock: !Select [ 0, !Ref DbSubnetIpBlocks ] ``` ### 使用簡短格式 YAML 的巢狀函數以下範例說明以 `!Select` 短格式使用巢狀內部函數的有效模式。您不可以連續巢狀短格式函數，因此類似 `!GetAZs !Ref` 的模式是無效的。 #### YAML ``` AvailabilityZone: !Select - 0 - !GetAZs Ref: 'AWS::Region' ``` #### YAML ``` AvailabilityZone: !Select - 0 - Fn::GetAZs: !Ref 'AWS::Region' ``` ## 支援的函數對於 `Fn::Select` 索引值，您可以使用 `Ref` 和 `Fn::FindInMap` 函數。對於 `Fn::Select` 物件清單，您可以使用下列函數： + `Fn::FindInMap` + `Fn::GetAtt` + `Fn::GetAZs` + `Fn::If` + `Fn::Split` + `Ref` # `Fn::Split` 若要將字串分割為字串值的清單，讓您可以從產生的字串清單中選取元素，請使用 `Fn::Split` 內部函數。以分隔符號指定分割的位置，例如 `,` (逗號)。在您分割一個字串之後，請使用 [`Fn::Select`](intrinsic-function-reference-select.md) 函數提取特定元素。例如，如果以逗號分隔的子網路 ID 字串匯入至您的堆疊範本，您可以在每個逗號處分割字串。從子網路 ID 清單，使用 `Fn::Select` 內部函數指定資源的子網路 ID。 ## 宣告 ### JSON ``` { "Fn::Split" : [ "delimiter", "source string" ] } ``` ### YAML 完整函式名稱的語法： ``` Fn::Split: [ delimiter, source string ] ``` 短格式的語法： ``` !Split [ delimiter, source string ] ``` ## Parameters 您必須同時指定兩個參數。分隔符號字串值，決定來源字串分割的位置。來源字串要分割的字串值。 ## 傳回值字串值清單。 ## 範例以下範例將示範 `Fn::Split` 函數的行為。 ### 簡單清單以下範例將在每個垂直線 (`|`) 分割字串。函數傳回 `["a", "b", "c"]`。 #### JSON ``` { "Fn::Split" : [ "|" , "a|b|c" ] } ``` #### YAML ``` !Split [ "|" , "a|b|c" ] ``` ### 包含空字串值的清單如果您以連續分隔符號分割字串，產生的清單將包含空白字串。以下範例顯示包含兩個連續分隔符號與一個附加分隔符號的字串如何進行分割。函數傳回 `["a", "", "c", ""]`。 #### JSON ``` { "Fn::Split" : [ "|" , "a||c|" ] } ``` #### YAML ``` !Split [ "|" , "a||c|" ] ``` ### 分割匯入的輸出值以下範例將匯入的輸出值進行分割，然後從產生的子網路 ID 清單中選取第三個元素，如 `Fn::Select` 函數所指定。 #### JSON ``` { "Fn::Select" : [ "2", { "Fn::Split": [",", {"Fn::ImportValue": "AccountSubnetIDs"}]}] } ``` #### YAML ``` !Select [2, !Split [",", !ImportValue AccountSubnetIDs]] ``` ## 支援的函數對於 `Fn::Split` 分隔符號，您不能使用任何函數。您必須指定一個字串值。對於值的 `Fn::Split` 清單，您可以使用下列函數： + `Fn::Base64` + `Fn::FindInMap` + `Fn::GetAtt` + `Fn::GetAZs` + `Fn::If` + `Fn::ImportValue` + `Fn::Join` + `Fn::Select` + `Fn::Sub` + `Ref` # `Fn::Sub` 透過內部函數 `Fn::Sub`，即可用您指定的值替代輸入字串中的變數。您可以在範本中善用此函數，進而建構命令或輸出，其中包含建立或更新堆疊後才可供使用的數值。 ## 宣告以下各節會顯示該函數的語法。 ### JSON ``` { "Fn::Sub" : [ String, { Var1Name: Var1Value, Var2Name: Var2Value } ] } ``` 如果您僅有更換 `String` 參數中的範本參數、資源邏輯 ID 或資源屬性，則不需指定變數映射。 ``` { "Fn::Sub" : String } ``` ### YAML 完整函式名稱的語法： ``` Fn::Sub: - String - Var1Name: Var1Value Var2Name: Var2Value ``` 短格式的語法： ``` !Sub - String - Var1Name: Var1Value Var2Name: Var2Value ``` 如果您僅有更換 `String` 參數中的範本參數、資源邏輯 ID 或資源屬性，則不需指定變數映射。完整函式名稱的語法： ``` Fn::Sub: String ``` 短格式的語法： ``` !Sub String ``` ## Parameters `String` 包含變數的字串，CloudFormation 會在執行時期以相關的數值來替代這些變數。請使用 `${MyVarName}` 格式編寫變數；變數可以指定為範本參數名稱、資源邏輯 ID、資源屬性，或索引鍵/值映射中的變數。如果您僅指定範本參數名稱、資源邏輯 ID 與資源屬性，便不需指定索引鍵/值映射。如果您是指定範本參數名稱或資源邏輯 ID (例如 `${InstanceTypeParameter}`)，CloudFormation 所傳回的值會與使用 `Ref` 內部函數時相同。如果您是指定資源屬性 (例如 `${MyInstance.PublicIp}`)，CloudFormation 所傳回的值會與使用 `Fn::GetAtt` 內部函數時相同。如需逐字寫入貨幣符號與大括號 (`${}`)，請在左大括號後面加入驚嘆號 (`!`)，例如 `${!Literal}`。CloudFormation 會將此文字解析為 `${Literal}`。如果您使用的是啟動範本，請在貨幣符號之前新增反斜線 `\`，例如 `\${!Literal}`，否則常值會解析為空字串。 `VarName` `String` 參數中包含的變數名稱。 `VarValue` CloudFormation 在執行時間要用來替代相關變數名稱的值。 ## 傳回值 CloudFormation 將傳回原始字串，並更換所有變數的值。 ## 範例以下範例會示範 `Fn::Sub` 函數的使用方式。 ### 使用不帶鍵值映射的 `Fn::Sub` 在此簡單範例中，會使用 `AWS::StackName` 虛擬參數來動態建立 `InstanceSecurityGroup` 資源的說明。例如，如果堆疊名稱為 "VPC-EC2-ALB-Stack"，則產生的說明為 "SSH security group for VPC-EC2-ALB-Stack"。 #### JSON ``` "InstanceSecurityGroup" : { "Type" : "AWS::EC2::SecurityGroup", "Properties" : { "GroupDescription" : {"Fn::Sub": "SSH security group for ${AWS::StackName}"} }} ``` #### YAML ``` InstanceSecurityGroup: Type: AWS::EC2::SecurityGroup Properties: GroupDescription: !Sub "SSH security group for ${AWS::StackName}" ``` ### 使用帶鍵值映射的 `Fn::Sub` 在此範例中，會使用鍵/值映射來動態建立 `WWWBucket` 資源的名稱。`Fn::Sub` 函數會將輸入字串 `www.${Domain}` 中的 `${Domain}` 替換為 `Ref` 函數的值，該函數參考相同堆疊範本中定義的 `RootDomainName` 參數。例如，如果根網域名稱為 "mydomain.com"，則此資源的結果名稱為 "www.mydomain.com"。 #### JSON ``` "WWWBucket":{ "Type":"AWS::S3::Bucket", "Properties":{ "BucketName":{ "Fn::Sub":[ "www.${Domain}", { "Domain":{ "Ref":"RootDomainName" } } ] } } } ``` #### YAML ``` WWWBucket: Type: AWS::S3::Bucket Properties: BucketName: !Sub - 'www.${Domain}' - Domain: !Ref RootDomainName ``` ### 使用多個變數來建構 ARN 以下範例會搭配使用 `Fn::Sub` 與 `AWS::Region` 和 `AWS::AccountId` 虛擬參數以及 `vpc` 資源邏輯 ID，以建立 VPC 的 Amazon Resource Name (ARN)。 #### JSON ``` { "Fn::Sub": "arn:aws:ec2:${AWS::Region}:${AWS::AccountId}:vpc/${vpc}" } ``` #### YAML ``` !Sub 'arn:aws:ec2:${AWS::Region}:${AWS::AccountId}:vpc/${vpc}' ``` ### 在使用者資料指令碼中傳遞參數值以下範例會使用 `Fn::Sub`，進而將 `AWS::StackName` 與 `AWS::Region` 虛擬參數替換成執行期的實際堆疊名稱和區域。 #### JSON 為確保易讀性，JSON 範例會使用 `Fn::Join` 函數來分隔每個命令，而不是在單一字串值中指定整個使用者資料指令碼。 ``` "UserData": { "Fn::Base64": { "Fn::Join": ["\n", [ "#!/bin/bash -xe", "yum update -y aws-cfn-bootstrap", { "Fn::Sub": "/opt/aws/bin/cfn-init -v --stack ${AWS::StackName} --resource LaunchConfig --configsets wordpress_install --region ${AWS::Region}" }, { "Fn::Sub": "/opt/aws/bin/cfn-signal -e $? --stack ${AWS::StackName} --resource WebServerGroup --region ${AWS::Region}" }]] }} ``` #### YAML YAML 範例則會使用常值區塊來指定使用者資料指令碼。 ``` UserData: Fn::Base64: !Sub | #!/bin/bash -xe yum update -y aws-cfn-bootstrap /opt/aws/bin/cfn-init -v --stack ${AWS::StackName} --resource LaunchConfig --configsets wordpress_install --region ${AWS::Region} /opt/aws/bin/cfn-signal -e $? --stack ${AWS::StackName} --resource WebServerGroup --region ${AWS::Region} ``` ### 使用映射來指定條件值在此範例中，透過將 `log_group_name` 變數替換為 `Fn::FindInMap` 函數中的結果值來動態建立 `myLogGroup` 資源的名稱。 #### JSON ``` { "Mappings": { "LogGroupMapping": { "Test": { "Name": "test_log_group" }, "Prod": { "Name": "prod_log_group" } } }, "Resources": { "myLogGroup": { "Type": "AWS::Logs::LogGroup", "Properties": { "LogGroupName": { "Fn::Sub": [ "cloud_watch_${log_group_name}", { "log_group_name": { "Fn::FindInMap": [ "LogGroupMapping", "Test", "Name" ] } } ] } } } } } ``` #### YAML ``` Mappings: LogGroupMapping: Test: Name: test_log_group Prod: Name: prod_log_group Resources: myLogGroup: Type: AWS::Logs::LogGroup Properties: LogGroupName: !Sub - 'cloud_watch_${log_group_name}' - log_group_name: !FindInMap - LogGroupMapping - Test - Name ``` ## 支援的函數對於 `String` 參數，您不能使用任何函數。您必須指定一個字串值。對於 `VarName` 和 `VarValue` 參數，您可以使用下列函數： + [`Fn::Base64`](intrinsic-function-reference-base64.md) + [`Fn::FindInMap`](intrinsic-function-reference-findinmap.md) + [`Fn::GetAtt`](intrinsic-function-reference-getatt.md) + [`Fn::GetAZs`](intrinsic-function-reference-getavailabilityzones.md) + [`Fn::If`](intrinsic-function-reference-conditions.md#intrinsic-function-reference-conditions-if) + [`Fn::ImportValue`](intrinsic-function-reference-importvalue.md) + [`Fn::Join`](intrinsic-function-reference-join.md) + [`Fn::Select`](intrinsic-function-reference-select.md) + [`Fn::Sub`](#intrinsic-function-reference-sub) + [`Ref`](intrinsic-function-reference-ref.md) # `Fn::ToJsonString` `Fn::ToJsonString` 內部函數會將物件或陣列轉換為其對應的 JSON 字串。 **重要** 您必須使用 [`AWS::LanguageExtensions` 轉換程序](transform-aws-languageextensions.md) 才能使用 `Fn::ToJsonString` 內部函數。 ## 宣告 ### JSON ``` { "Fn::ToJsonString": Object } ``` ``` { "Fn::ToJsonString": Array } ``` ### YAML ``` Fn::ToJsonString: Object ``` ``` Fn::ToJsonString: Array ``` ## Parameters `Object` 要轉換為 JSON 字串的物件。 `Array` 要轉換為 JSON 字串的陣列。 ## 傳回值已轉換為 JSON 字串的物件或陣列。 ## 範例 ### 將物件轉換為 JSON 字串此範例程式碼片段會將傳遞至內部函數的物件轉換為 JSON 字串。 #### JSON ``` { //... "Transform": "AWS::LanguageExtensions" //... "Fn::ToJsonString": { "key1": "value1", "key2": { "Ref": "ParameterName" } } //... } ``` #### YAML ``` Transform: 'AWS::LanguageExtensions' #... Fn::ToJsonString: key1: value1 key2: !Ref ParameterName #... ``` 在這兩個範例中，如果 `Ref` 至 `ParameterName` 解析為 `resolvedValue`，則函數會解析為下列 JSON 字串： ``` "{\"key1\":\"value1\",\"key2\":\"resolvedValue\"}" ``` ### 將陣列轉換為 JSON 字串此範例程式碼片段會將傳遞至內部函數的陣列轉換為 JSON 字串。 #### JSON ``` { //... "Transform": "AWS::LanguageExtensions" //... "Fn::ToJsonString": [{ "key1": "value1", "key2": { "Ref": "ParameterName" } }] //... } ``` #### YAML ``` Transform: 'AWS::LanguageExtensions' #... Fn::ToJsonString: - key1: value1 key2: !Ref ParameterName #... ``` 在這兩個範例中，如果 `Ref` 至 `ParameterName` 解析為 `resolvedValue`，則函數會解析為下列 JSON 字串： ``` "[{\"key1\":\"value1\"},{\"key2\":\"resolvedValue\"}]" ``` ## 支援的函數您可以在 `Fn::ToJsonString` 內部函數或陣列中使用下列函數： + `Fn::Base64` + `Fn::FindInMap` + `Fn::GetAtt` + `Fn::GetAZs` + `Fn::If` + `Fn::ImportValue` + `Fn::Join` + `Fn::Length` + `Fn::Select` + `Fn::Split` + `Fn::Sub` + `Fn::ToJsonString` + `Ref` # `Fn::Transform` 內部函數 `Fn::Transform` 指定在堆疊範本的一部分執行自訂處理的巨集。巨集可讓您在範本上執行自訂處理，例如尋找和取代操作這種簡單動作，乃至於全部範本的大規模轉換。如需詳細資訊，請參閱《AWS CloudFormation 使用者指南》**中的[使用 CloudFormation 巨集對範本執行自訂處理](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-macros.html)。您也可以使用 `Fn::Transform` 呼叫 [`AWS::Include` 轉換程序](transform-aws-include.md) 轉換，這是由託管的巨集 CloudFormation。 ## 宣告 ### JSON 完整函式名稱的語法： ``` { "Fn::Transform": { "Name": "macro name", "Parameters": { "Key": "value" } } } ``` 短格式的語法： ``` { "Transform": { "Name": "macro name", "Parameters": { "Key": "value" } } } ``` ### YAML 完整函式名稱的語法： ``` Fn::Transform: Name : macro name Parameters : Key : value ``` 短格式的語法： ``` !Transform Name: macro name Parameters: Key: value ``` ## Parameters `Name` 您要執行處理的巨集名稱。 `Parameters` 要傳遞到巨集的清單參數 (以鍵值組指定)。 ## 傳回值要納入所處理堆疊範本中的已處理範本程式碼片段。 ## 範例以下範例呼叫 `AWS::Include` 轉換，其中指定將擷取範本程式碼片段的來源位置傳入 `InputValue` 參數中。 ### JSON ``` { "Fn::Transform": { "Name": "AWS::Include", "Parameters": { "Location": { "Ref": "InputValue" } } } } ``` ### YAML ``` Fn::Transform: Name: AWS::Include Parameters: Location: !Ref InputValue ``` ## 支援的函數無。 CloudFormation 以文字字串將 `Fn::Transform` 包含的任何內部函數呼叫傳遞至指定的巨集。 # `Ref` 內建函數 `Ref` 會傳回指定參數、資源或其他內建函數的值。此函數通常用於在 CloudFormation 範本內的資源之間建立參考。 ## 宣告 ### JSON ``` { "Ref" : "logicalName" } ``` ``` { "Ref" : "IntrinsicFunction" } ``` ### YAML 完整函式名稱的語法： ``` Ref: logicalName ``` ``` Ref: IntrinsicFunction ``` 短格式的語法： ``` !Ref logicalName ``` ``` !Ref IntrinsicFunction ``` ## Parameters logicalName 您要參照的資源或參數之邏輯名稱。 IntrinsicFunction 解析為有效字串的內部函數。它應該包含對參數或識別碼的參考，並且不應包含資源邏輯識別碼。 ## 傳回值 `Ref` 的傳回值取決於所參考實體的類型： + 當您指定參數的邏輯名稱時，它會傳回參數值。如需詳細資訊，請參閱 [CloudFormation 範本 Parameters 語法](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html)。 + 當您指定資源的邏輯名稱時，它會傳回您用來識別該資源的值。通常，這是資源名稱。但是，針對某些資源，將會傳回一個識別碼，它對於該資源而言有其他重要的意義。例如，`AWS::EC2::EIP` 資源會傳回 IP 位址，而 `AWS::EC2::Instance` 會傳回執行個體 ID。如需有關資源的 `Ref` 傳回值的詳細資訊，請參閱 [資源和屬性參考](aws-template-resource-type-ref.md) 中該資源的文件。 + 當您指定內部函數時，它會傳回該函數的輸出。 ## 範例 ### 建立資源之間的參考下列彈性 IP 位址的資源宣告需要 EC2 執行個體的執行個體 ID。它使用 `Ref` 函數來指定範本中其他位置宣告之 `MyEC2Instance` 資源的執行個體 ID。 #### JSON ``` { "AWSTemplateFormatVersion":"2010-09-09", "Resources":{ ... "MyEIP":{ "Type":"AWS::EC2::EIP", "Properties":{ "InstanceId":{ "Ref":"MyEC2Instance" } } } } } ``` #### YAML ``` AWSTemplateFormatVersion: 2010-09-09 Resources: ... MyEIP: Type: AWS::EC2::EIP Properties: InstanceId: !Ref MyEC2Instance ``` ### 將資源識別符傳回為堆疊輸出下列範例示範如何使用 `Ref` 函數將邏輯名稱為 `MyBucket` 的 Amazon S3 儲存貯體的名稱傳回為堆疊輸出。 #### JSON ``` { "AWSTemplateFormatVersion":"2010-09-09", "Resources":{ "MyBucket":{ "Type":"AWS::S3::Bucket", "Properties":{ "BucketName":{ "Fn::Sub": "${AWS::StackName}-mybucket" } } } }, "Outputs":{ "BucketNameOutput":{ "Description":"The name of the S3 bucket", "Value":{ "Ref":"MyBucket" } } } } ``` #### YAML ``` AWSTemplateFormatVersion: 2010-09-09 Resources: MyBucket: Type: AWS::S3::Bucket Properties: BucketName: !Sub ${AWS::StackName}-mybucket Outputs: BucketNameOutput: Description: The name of the S3 bucket Value: !Ref MyBucket ``` ### 使用 `Ref` 函數內的 `Fn::Join` 內建函數 **注意** 使用 `AWS::LanguageExtensions` 轉換時，您可以搭配其他內建函數使用 `Ref`。如需支援的函數，請參閱 [支援的函數](#ref-supported-functions)。下列範例示範如何使用 `Fn::Sub` 內建函數、條件和 `Stage` 參數輸入來設定資源的識別符。然後，`Ref` 和 `Fn::GetAtt` 函數會根據階段來參考適當的值。`Fn::Sub` 首先與 `Fn::GetAtt` 搭配使用，以獲取適當 Amazon SQS 佇列的 ARN，進而設定 Amazon CloudWatch 警示的維度。接下來，[`Fn::Join`](intrinsic-function-reference-join.md) 會與 `Ref` 搭配使用，以建立 `AlarmActions` 屬性的 SNS 主題名稱。 #### JSON ``` { "AWSTemplateFormatVersion": "2010-09-09", "Transform": "AWS::LanguageExtensions", "Parameters": { "Stage": { "Type": "String", "Default": "Dev", "AllowedValues": [ "Dev", "Prod" ] } }, "Conditions": { "isProd": { "Fn::Equals": [ {"Ref": "Stage"}, "Prod" ] }, "isDev": { "Fn::Equals": [ {"Ref": "Stage"}, "Dev" ] } }, "Resources": { "DevQueue": { "Type": "AWS::SQS::Queue", "Condition": "isDev", "Properties": { "QueueName": {"Fn::Sub": "My${Stage}Queue"} } }, "ProdQueue": { "Type": "AWS::SQS::Queue", "Condition": "isProd", "Properties": { "QueueName": {"Fn::Sub": "My${Stage}Queue"} } }, "DevTopic": { "Condition": "isDev", "Type": "AWS::SNS::Topic" }, "ProdTopic": { "Condition": "isProd", "Type": "AWS::SNS::Topic" }, "MyAlarm": { "Type": "AWS::CloudWatch::Alarm", "Properties": { "AlarmDescription": "Alarm if queue depth grows beyond 10 messages", "Namespace": "AWS/SQS", "MetricName": "ApproximateNumberOfMessagesVisible", "Dimensions":[ { "Name": {"Fn::Sub": "${Stage}Queue"}, "Value": {"Fn::GetAtt": [{"Fn::Sub": "${Stage}Queue"}, "QueueName"]} } ], "Statistic": "Sum", "Period": 300, "EvaluationPeriods": 1, "Threshold": 10, "ComparisonOperator": "GreaterThanThreshold", "AlarmActions": [ { "Ref": {"Fn::Join": ["", [{"Ref": "Stage"}, "Topic"]]} } ] } } } } ``` #### YAML ``` AWSTemplateFormatVersion: 2010-09-09 Transform: AWS::LanguageExtensions Parameters: Stage: Type: String Default: Dev AllowedValues: - Dev - Prod Conditions: isProd: !Equals - !Ref Stage - Prod isDev: !Equals - !Ref Stage - Dev Resources: DevQueue: Type: AWS::SQS::Queue Condition: isDev Properties: QueueName: !Sub My${Stage}Queue ProdQueu: Type: AWS::SQS::Queue Condition: isProd Properties: QueueName: !Sub My${Stage}Queue DevTopic: Condition: isDev Type: AWS::SNS::Topic ProdTopic: Condition: isProd Type: AWS::SNS::Topic MyAlarm: Type: AWS::CloudWatch::Alarm Properties: AlarmDescription: Alarm if queue depth grows beyond 10 messages Namespace: AWS/SQS MetricName: ApproximateNumberOfMessagesVisible Dimensions: - Name: !Sub '${Stage}Queue' Value: !GetAtt - !Sub '${Stage}Queue' - QueueName Statistic: Sum Period: 300 EvaluationPeriods: 1 Threshold: 10 ComparisonOperator: GreaterThanThreshold AlarmActions: - !Ref 'Fn::Join': - '' - - !Ref Stage - Topic ``` ## 支援的函數當使用 [AWS::LanguageExtensions 轉換](transform-aws-languageextensions.md)時，可以使用 `Ref` 函數內的以下函數。 + [`Fn::Base64`](intrinsic-function-reference-base64.md) + [`Fn::FindInMap`](intrinsic-function-reference-findinmap.md) + [`Fn::If`](intrinsic-function-reference-conditions.md#intrinsic-function-reference-conditions-if) + [`Fn::ImportValue`](intrinsic-function-reference-importvalue.md) + [`Fn::Join`](intrinsic-function-reference-join.md) + [`Fn::Sub`](intrinsic-function-reference-sub.md) + [`Fn::ToJsonString`](intrinsic-function-reference-ToJsonString.md) + `Ref` # 規則函數規則函數是只在 CloudFormation 範本的 `Rules` 區段中運作的特殊函數。這些函數可協助您使用自訂邏輯來驗證參數值。所有驗證都會在 CloudFormation 建立或更新任何資源之前進行。當標準參數限制不足時，規則很有用。例如，啟用 SSL 時，必須提供憑證和網域名稱。規則可以確保滿足這些相依性。可以在規則的條件或宣告中使用內部函數，如 `Fn::Equals`、`Fn::Not`、`Fn::RefAll`。由條件屬性決定 CloudFormation 是否套用宣告。若條件計算結果為 `true`，CloudFormation 會評估宣告以驗證在建立或更新堆疊時，某個參數值是否有效。若參數值為無效，CloudFormation 便不會建立或更新堆疊。如果條件評估為 `false`，CloudFormation 便不會檢查參數值，而直接繼續運作堆疊。如果您是第一次在範本中使用規則，建議您先檢閱**《AWS CloudFormation 使用者指南》中的 [CloudFormation 範本 Rules 語法](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/rules-section-structure.html)主題。 **Topics** + [`Fn::And`](#fn-and) + [`Fn::Contains`](#fn-contains) + [`Fn::EachMemberEquals`](#fn-eachmemberequals) + [`Fn::EachMemberIn`](#fn-eachmemberin) + [`Fn::Equals`](#fn-equals) + [`Fn::Not`](#fn-not) + [`Fn::Or`](#fn-or) + [`Fn::RefAll`](#fn-refall) + [`Fn::ValueOf`](#fn-valueof) + [`Fn::ValueOfAll`](#fn-valueofall) + [支援的函數](#supported-rule-functions) + [支援的屬性](#rules-parameter-attributes) ## `Fn::And` 如果所有指定條件計算結果為 `true`，則傳回 `true`；如果其中任一條件計算結果為 `false`，則傳回 `false`。`Fn::And` 擔任 AND 運算子。可納入的條件數量下限為 2，上限為 10。 ### 宣告 ``` "Fn::And" : [{condition}, {...}] ``` ### Parameters *condition* 規則指定的內部函數，計算結果為 `true` 或 `false`。 ### 範例若參考的安全群組名稱等於 `true` 且 `sg-mysggroup` 參數的值為 `InstanceType` 或 `t3.large`，以下範例會計算結果為 `t3.small`： ``` "Fn::And": [ { "Fn::Equals": [ "sg-mysggroup", {"Ref": "ASecurityGroup"} ] }, { "Fn::Contains": [ [ "t3.large", "t3.small" ], {"Ref": "InstanceType"} ] } ] ``` ## `Fn::Contains` 若指定字串與字串清單其中至少一個值相符，則傳回 `true`。 ### 宣告 ``` "Fn::Contains" : [[list_of_strings], string] ``` ### Parameters *list\$1of\$1strings* 字串清單，如 `"A", "B", "C"`。 *string* 想與字串清單對照的字串，例如 `"A"`。 ### 範例若清單 (`true` 或 `InstanceType`) 含有 `t3.large` 參數值，以下函數會計算結果為 `t3.small`： ``` "Fn::Contains" : [ ["t3.large", "t3.small"], {"Ref" : "InstanceType"} ] ``` ## `Fn::EachMemberEquals` 若指定字串符合某個清單內所有的值，傳回 `true`。 ### 宣告 ``` "Fn::EachMemberEquals" : [[list_of_strings], string] ``` ### Parameters *list\$1of\$1strings* 字串清單，如 `"A", "B", "C"`。 *string* 想與字串清單對照的字串，例如 `"A"`。 ### 範例如果類型 `AWS::EC2::VPC::Id` 之所有參數適用的 `Department` 標籤具有 `IT` 值，則下列函數會傳回 `true`: ``` "Fn::EachMemberEquals" : [ {"Fn::ValueOfAll" : ["AWS::EC2::VPC::Id", "Tags.Department"]}, "IT" ] ``` ## `Fn::EachMemberIn` 若字串清單中的每個成員均符合第二份字串清單內的值少一個值，即傳回 `true`。 ### 宣告 ``` "Fn::EachMemberIn" : [[strings_to_check], [strings_to_match]] ``` ### Parameters *strings\$1to\$1check* 字串清單，如 `"A", "B", "C"`。CloudFormation 會檢查 `strings_to_check` 參數內的每個成員是否存在於 `strings_to_match` 參數內。 *strings\$1to\$1match* 字串清單，如 `"A", "B", "C"`。`strings_to_match` 參數的每個成員會與 `strings_to_check` 參數的成員進行對照。 ### 範例以下函數會檢查使用者是否指定了位在有效的 Virtual Private Cloud (VPC) 內的子網路。VPC 必須位在使用者使用堆疊的帳戶和區域內。該函數會套用至類型 `AWS::EC2::Subnet::Id` 的所有參數。 ``` "Fn::EachMemberIn" : [ {"Fn::ValueOfAll" : ["AWS::EC2::Subnet::Id", "VpcId"]}, {"Fn::RefAll" : "AWS::EC2::VPC::Id"} ] ``` ## `Fn::Equals` 比較兩個值，判斷是否相同。若兩值相同，即傳回 `true`，反之則傳回 `false`。 ### 宣告 ``` "Fn::Equals" : ["value_1", "value_2"] ``` ### Parameters *`value`* 要與另一個值比較的任何類型的值。 ### 範例若 `true` 參數的值等同 `EnvironmentType`，下列範例會計算結果為 `prod`： ``` "Fn::Equals" : [{"Ref" : "EnvironmentType"}, "prod"] ``` ## `Fn::Not` 若某個條件計算結果為 `false`，則傳回 `true`，若某個條件計算結果為 `true`，則傳回 `false`。`Fn::Not` 擔任 NOT 運算子。 ### 宣告 ``` "Fn::Not" : [{condition}] ``` ### Parameters *`condition`* 規則指定的內部函數，計算結果為 `true` 或 `false`。 ### 範例若 `EnvironmentType` 參數的值不同於 `prod`，下列範例會計算結果為 `true`： ``` "Fn::Not" : [{"Fn::Equals" : [{"Ref" : "EnvironmentType"}, "prod"]}] ``` ## `Fn::Or` 如果任一指定條件評估為 `true`，則傳回 `true`；如果所有的條件評估為 `false`，則傳回 `false`。`Fn::Or` 擔任 OR 運算子。可納入的條件數量下限為 2，上限為 10。 ### 宣告 ``` "Fn::Or" : [{condition}, {...}] ``` ### Parameters *`condition`* 規則指定的內部函數，計算結果為 `true` 或 `false`。 ### 範例若參考的安全群組名稱等於 `true` 或 `sg-mysggroup` 參數的值為 `InstanceType` 或 `t3.large`，以下範例會計算結果為 `t3.small`： ``` "Fn::Or" : [ {"Fn::Equals" : ["sg-mysggroup", {"Ref" : "ASecurityGroup"}]}, {"Fn::Contains" : [["t3.large", "t3.small"], {"Ref" : "InstanceType"}]} ] ``` ## `Fn::RefAll` 傳回指定參數類型的所有值。 ### 宣告 ``` "Fn::RefAll" : "parameter_type" ``` ### Parameters *parameter\$1type* AWS特定參數類型，例如 `AWS::EC2::SecurityGroup::Id`或 `AWS::EC2::VPC::Id`。如需詳細資訊，請參閱*AWS CloudFormation 《使用者指南*》中的[支援 AWS的特定參數類型](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cloudformation-supplied-parameter-types.html#aws-specific-parameter-types-supported)。 ### 範例下列函數會傳回建立或更新堆疊之區域和 AWS 帳戶的所有 VPC IDs 清單： ``` "Fn::RefAll" : "AWS::EC2::VPC::Id" ``` ## `Fn::ValueOf` 傳回某個屬性值，或指定參數和屬性值的清單。 ### 宣告 ``` "Fn::ValueOf" : [ "parameter_logical_id", "attribute" ] ``` ### Parameters *屬性* 想要從中擷取某個值的屬性名稱。如需屬性的詳細資訊，請參閱 [支援的屬性](#rules-parameter-attributes)。 *parameter\$1logical\$1id* 想要從中擷取屬性值的參數名稱。該參數並需於範本的 `Parameters` 區段內宣告。 ### 範例以下範例會傳回由 `Department` 參數指定之 VPC 的 `ElbVpc` 標籤的值： ``` "Fn::ValueOf" : ["ElbVpc", "Tags.Department"] ``` 若給某個參數指定了多個值，Fn::ValueOf function 可傳回清單。例如可指定多個子網路，並取得可用區域清單，其中每個成員均是特定子網路的可用區域： ``` "Fn::ValueOf" : ["ListOfElbSubnets", "AvailabilityZone"] ``` ## `Fn::ValueOfAll` 傳回指定參數類型和屬性所有屬性值的清單。 ### 宣告 ``` "Fn::ValueOfAll" : ["parameter_type", "attribute"] ``` ### Parameters *屬性* 想要從中擷取某個值的屬性名稱。如需屬性的詳細資訊，請參閱 [支援的屬性](#rules-parameter-attributes)。 *parameter\$1type* AWS特定參數類型，例如 `AWS::EC2::SecurityGroup::Id`或 `AWS::EC2::VPC::Id`。如需詳細資訊，請參閱*AWS CloudFormation 《使用者指南*》中的[支援 AWS的特定參數類型](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cloudformation-supplied-parameter-types.html#aws-specific-parameter-types-supported)。 ### 範例在下列範例中，`Fn::ValueOfAll` 函數會傳回一份值的清單，其中每個成員均是含有 `Department` 標籤之 VPC 該標籤的值。 ``` "Fn::ValueOfAll" : ["AWS::EC2::VPC::Id", "Tags.Department"] ``` ## 支援的函數無法在 `Fn::ValueOf` 和 `Fn::ValueOfAll` 函數內使用另一個函數。不過可以在所有其他規則特定的內建函式使用下列函數： + `Ref` + 其他規則特定的內部函數 ## 支援的屬性以下清單所述的是可為特定資源和參數類型擷取的屬性值： `AWS::EC2::VPC::Id` 參數類型或 VPC ID。 + DefaultNetworkAcl + DefaultSecurityGroup + 標籤。*tag\$1key* `AWS::EC2::Subnet::Id` 參數類型或子網路 ID。 + AvailabilityZone + 標籤。*tag\$1key* + VpcId `AWS::EC2::SecurityGroup::Id` 參數類型或安全群組 ID。 + 標籤。*tag\$1key*