Fn::Sub - Amazon CloudFormation
声明参数返回值示例支持的函数
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

参数

String

一个带变量的字符串，Amazon CloudFormation 在运行时会将这些变量替换为其关联的值。以 ${MyVarName} 形式编写变量。变量可以是模板参数名、资源逻辑 ID、资源属性或键值映射中的变量。如果您仅指定模板参数名、资源逻辑 ID 和资源属性，则不要指定键值映射。

如果您指定模板参数名或资源逻辑 ID（例如 ${InstanceTypeParameter}），则 CloudFormation 返回的值与您使用 Ref 内部函数时返回的值相同。如果您指定资源属性（例如 ${MyInstance.PublicIp}），则 CloudFormation 返回的值与您使用 Fn::GetAtt 内部函数时返回的值相同。

要按字面书写美元符号和大括号（${}），请在左大括号后面添加感叹号（!），如 ${!Literal}。CloudFormation 将该文本解析为 ${Literal}。

VarName

String 参数中包含的变量的名称。

VarValue

CloudFormation 在运行时要将关联的变量名称替换为的值。

返回值

CloudFormation 返回原始字符串，并替换所有变量的值。

示例

以下示例说明如何使用 Fn::Sub 函数。

使用不带键值映射的 Fn::Sub

在这一简单示例中，InstanceSecurityGroup 资源描述使用 AWS::StackName 伪参数动态创建。例如，如果堆栈名称为“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} 替换为引用在同一堆栈模板中定义的 RootDomainName 参数的 Ref 函数值。例如，如果根域名称为“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 资源名称（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}

使用映射指定条件值

在此示例中，myLogGroup 资源的名称是通过将 log_group_name 变量替换为 Fn::FindInMap 函数的结果值来动态创建的。

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 参数，您可以使用以下函数：