這是新的 *CloudFormation 範本參考指南*。請更新您的書籤和連結。如需 CloudFormation 入門的說明，請參閱 [AWS CloudFormation 使用者指南](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)。本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # `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)