Este é o novo *Guia de referência de modelos do CloudFormation*. Atualize seus favoritos e links. Para obter ajuda para começar a usar o CloudFormation, consulte o [Guia do usuário do AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html). # `Fn::Sub` A função intrínseca `Fn::Sub` substitui variáveis em uma sequência de entrada por valores especificados por você. Em seus modelos, você pode usar essa função para construir comandos ou saídas que incluem valores que não estão disponíveis até que você crie ou atualize uma pilha. ## Declaração As seções a seguir mostram a sintaxe da função. ### JSON ``` { "Fn::Sub" : [ String, { Var1Name: Var1Value, Var2Name: Var2Value } ] } ``` Se você estiver substituindo apenas parâmetros do modelo, IDs lógicos de recursos ou atributos de recursos no parâmetro `String`, não especifique um mapa de variáveis. ``` { "Fn::Sub" : String } ``` ### YAML Sintaxe para o nome da função completo: ``` Fn::Sub: - String - Var1Name: Var1Value Var2Name: Var2Value ``` Sintaxe para a forma resumida: ``` !Sub - String - Var1Name: Var1Value Var2Name: Var2Value ``` Se você estiver substituindo apenas parâmetros do modelo, IDs lógicos de recursos ou atributos de recursos no parâmetro `String`, não especifique um mapa de variáveis. Sintaxe para o nome da função completo: ``` Fn::Sub: String ``` Sintaxe para a forma resumida: ``` !Sub String ``` ## Parâmetros `String` Uma sequência com variáveis que o CloudFormation substitui por seus valores associados em runtime. Escreva variáveis como `${MyVarName}`. As variáveis podem ser nomes de parâmetros do modelo, IDs lógicos de recursos, atributos de recursos ou uma variável em um mapa de chave/valor. Se você especificar apenas nomes de parâmetros do modelo, IDs lógicos de recursos e atributos de recursos, não especifique um mapa de chave/valor. Se você especificar nomes de parâmetros do modelo ou IDs lógicas de recursos, como `${InstanceTypeParameter}`, o CloudFormation retornará os mesmos valores como se você tivesse usado a função intrínseca `Ref`. Se você especificar atributos de recursos, como `${MyInstance.PublicIp}`, o CloudFormation retornará os mesmos valores como se você tivesse usado a função intrínseca `Fn::GetAtt`. Para escrever um cifrão e chaves (`${}`) literalmente, adicione um ponto de exclamação (`!`) após a chave de abertura, como `${!Literal}`. O CloudFormation resolve esse texto como `${Literal}`. Se você estiver usando um modelo de inicialização, adicione uma barra invertida `\` antes do cifrão, por exemplo `\${!Literal}`, caso contrário o literal será resolvido como uma string vazia. `VarName` O nome de uma variável que você incluiu no parâmetro `String`. `VarValue` O valor que o CloudFormation substitui para o nome da variável associada em runtime. ## Valor de retorno O CloudFormation retorna a sequência original, substituindo os valores de todas as variáveis. ## Exemplos Os exemplos a seguir demonstram como usar a função `Fn::Sub`. ### Usar `Fn::Sub` sem um mapeamento de chave-valor Neste exemplo simples, a descrição do recurso `InstanceSecurityGroup` é criada dinamicamente com o pseudoparâmetro `AWS::StackName`. Por exemplo, se o nome da pilha for “VPC-EC2-ALB-Stack”, a descrição resultante será “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}" ``` ### Usar `Fn::Sub` com um mapeamento de chave-valor Neste exemplo, o nome do recurso `WWWBucket` é criado dinamicamente com um mapeamento de chave-valor. A função `Fn::Sub` substitui `${Domain}` na string de entrada `www.${Domain}` com o valor de uma função `Ref` que faz referência ao parâmetro `RootDomainName`, que é definido em um modelo de pilha semelhante. Por exemplo, se o nome do domínio raiz for “mydomain.com”, o nome resultante para esse recurso será “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 ``` ### Usar múltiplas variáveis para desenvolver a estrutura de ARNs O exemplo apresentado a seguir usa `Fn::Sub` com os pseudoparâmetros `AWS::Region` e `AWS::AccountId` e o ID lógico do recurso `vpc` para criar um nome do recurso da Amazon (ARN) para uma VPC. #### JSON ``` { "Fn::Sub": "arn:aws:ec2:${AWS::Region}:${AWS::AccountId}:vpc/${vpc}" } ``` #### YAML ``` !Sub 'arn:aws:ec2:${AWS::Region}:${AWS::AccountId}:vpc/${vpc}' ``` ### Transferir valores de parâmetros em scripts de dados do usuário O exemplo apresentado a seguir usa `Fn::Sub` para substituir os pseudoparâmetros `AWS::StackName` e `AWS::Region` pelo nome e pela região reais da pilha no runtime. #### JSON Para facilitar a leitura, o exemplo do JSON usa a função `Fn::Join` para separar cada comando, em vez de especificar todo o script de dados do usuário em um único valor de sequência. ``` "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 O exemplo do YAML usa um bloco literal para especificar o script de dados do usuário. ``` 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} ``` ### Especificar valores condicionais usando mapeamentos Neste exemplo, o nome do recurso `myLogGroup` é criado dinamicamente substituindo-se a variável `log_group_name` pelo valor resultante da função `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 ``` ## Funções compatíveis No parâmetro `String`, não é possível usar funções. É necessário especificar um valor de string. Para os parâmetros `VarName` e `VarValue`, você pode usar as seguintes funções: + [`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)