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). # Referência à função intrínseca O CloudFormation fornece várias funções internas que ajudam você a gerenciar as pilhas. Use funções intrínsecas nos modelos para atribuir valores às propriedades que não estão disponíveis até o runtime. **nota** É possível utilizar funções intrínsecas apenas em partes específicas de um modelo. Atualmente, é possível utilizar funções intrínsecas em propriedades de recursos, saídas, atributos de metadados e atributos de políticas de atualização. Você também pode usar as funções intrínsecas para criar condicionalmente recursos da pilha. **Topics** + [`Fn::Base64`](intrinsic-function-reference-base64.md) + [`Fn::Cidr`](intrinsic-function-reference-cidr.md) + [Funções de condição](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) + [Funções de regras](intrinsic-function-reference-rules.md) # `Fn::Base64` A função intrínseca `Fn::Base64` retorna a representação Base64 da string de entrada. Essa função normalmente é usada para passar dados codificados para instâncias do Amazon EC2 por meio da propriedade `UserData`. ## Declaração ### JSON ``` { "Fn::Base64" : valueToEncode } ``` ### YAML Sintaxe para o nome da função completo: ``` Fn::Base64: valueToEncode ``` Sintaxe para a forma resumida: ``` !Base64 valueToEncode ``` **nota** Caso você use a forma curta e inclua imediatamente outra função no parâmetro `valueToEncode`, use o nome da função completo em pelo menos uma das funções. Por exemplo, a sintaxe a seguir não é válida: ``` !Base64 !Sub string !Base64 !Ref logical_ID ``` Em vez disso, use o nome da função completo em pelo menos uma das funções, conforme mostrado nos seguintes exemplos: ``` !Base64 "Fn::Sub": string Fn::Base64: !Sub string ``` ## Parameters valueToEncode O valor da string que você deseja converter em Base64. ## Valor de retorno: A string original, em representação Base64. ## Exemplos ### JSON ``` { "Fn::Base64" : "AWS CloudFormation" } ``` ### YAML ``` Fn::Base64: AWS CloudFormation ``` ## Funções compatíveis Você pode usar qualquer função que retorne uma string dentro da função `Fn::Base64`. # `Fn::Cidr` A função intrínseca `Fn::Cidr` retorna uma matriz de blocos de endereços CIDR. O número de blocos CIDR retornados depende do parâmetro `count`. ## Declaração ### JSON ``` { "Fn::Cidr" : [ipBlock, contagem, cidrBits]} ``` ### YAML Sintaxe para o nome da função completo: ``` Fn::Cidr: - ipBlock - contagem - cidrBits ``` Sintaxe para a forma resumida: ``` !Cidr [ ipBlock, contagem, cidrBits ] ``` ## Parâmetros ipBlock O bloco de endereços CIDR especificado pelo usuário a ser dividido em blocos CIDR menores. contagem O número de CIDRs para gerar. O intervalo válido é entre 1 e 256. cidrBits O número de bits de sub-rede para o CIDR. Por exemplo, se você especificar um valor "8" para esse parâmetro, criará um CIDR com uma máscara de "/ 24". Bits de sub-rede é o inverso de uma máscara de sub-rede. Para calcular os bits de host necessários para um determinado número de bits de sub-rede, subtraia os bits de sub-rede de 32 para IPv4 ou de 128 para IPv6. ## Valor de retorno Uma matriz de blocos de endereços CIDR. ## Exemplo ### Uso básico Este exemplo cria 6 CIDRs com uma máscara de sub-rede "/ 27" dentro de um CIDR com uma máscara de "/24". #### JSON ``` { "Fn::Cidr" : [ "192.168.0.0/24", "6", "5"] } ``` #### YAML ``` !Cidr [ "192.168.0.0/24", 6, 5 ] ``` ### Criar uma VPC habilitada para IPv6 Este modelo de exemplo cria uma sub-rede habilitada para 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 ``` ## Funções compatíveis Você pode usar as seguintes funções em uma função `Fn::Cidr`: + [`Fn::Select`](intrinsic-function-reference-select.md) + [`Ref`](intrinsic-function-reference-ref.md) # Funções de condição É possível usar funções intrínsecas, como `Fn::If` ou `Fn::Equals`, para criar e configurar recursos de pilha com base em lógica condicional. Essas condições são avaliadas durante a criação ou atualização da pilha. Depois de definir todas as condições, você pode associá-las a recursos ou propriedades de recursos nas seções `Resources` e `Outputs` de um modelo. Para cenários avançados, é possível combinar condições usando as funções `Fn::And` ou `Fn::Or` ou usar `Fn::Not` para negar o valor de uma condição. Também é possível aninhar condições para criar uma lógica condicional mais complexa. Se você é novato no uso de condições em seus modelos, recomendamos revisar primeiro o tópico sobre [sintaxe de condições do modelo do CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/conditions-section-structure.html) no *Guia do usuário do AWS CloudFormation*. **nota** É necessário definir todas as condições na seção `Conditions` de um modelo, exceto para as condições `Fn::If`. É possível usar a condição `Fn::If` no atributo `Metadata` e atributo `UpdatePolicy` e valores de propriedade nas seções `Resources` e `Outputs`. **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) + [Funções compatíveis](#w2aac24c20c25) + [Modelo de exemplo](#conditions-sample-templates) ## `Fn::And` Retorna `true` se todas as condições especificadas forem verdadeiras, ou retornarem `false` se alguma das condições for falsa. O `Fn::And` atua como operador AND. O número mínimo de condições que você pode incluir é 2 e o máximo é 10. ### Declaração #### JSON ``` "Fn::And": [{condition}, {...}] ``` #### YAML Sintaxe para o nome da função completo: ``` Fn::And: [condition] ``` Sintaxe para a forma resumida: ``` !And [condition] ``` ### Parâmetros condition Uma condição que avalia como `true` ou `false`. ### Exemplos de uso de `Fn::And` O seguinte `MyAndCondition` avalia como verdadeiro se o nome do security group referenciado é igual a `sg-mysggroup` e se `SomeOtherCondition` avalia como verdadeiro: #### JSON ``` "MyAndCondition": { "Fn::And": [ {"Fn::Equals": ["sg-mysggroup", {"Ref": "ASecurityGroup"}]}, {"Condition": "SomeOtherCondition"} ] } ``` #### YAML ``` MyAndCondition: !And - !Equals ["sg-mysggroup", !Ref ASecurityGroup] - !Condition SomeOtherCondition ``` ## `Fn::Equals` Compara se dois valores são iguais. Retorna `true` se os dois valores são iguais ou `false` se eles não são. ### Declaração #### JSON ``` "Fn::Equals" : ["value_1", "value_2"] ``` #### YAML Sintaxe para o nome da função completo: ``` Fn::Equals: [value_1, value_2] ``` Sintaxe para a forma resumida: ``` !Equals [value_1, value_2] ``` ### Parâmetros value Um valor de string que você deseja comparar. ### Exemplos de uso de `Fn::Equals` A seguinte condição `IsProduction` avaliará como verdadeira se o valor para o parâmetro `EnvironmentType` for igual a `prod`: #### JSON ``` "IsProduction" : { "Fn::Equals": [ {"Ref": "EnvironmentType"}, "prod" ] } ``` #### YAML ``` IsProduction: !Equals [!Ref EnvironmentType, prod] ``` ## `Fn::If` Retorna um valor se a condição especificada avalia como `true` e outro valor se a condição especificada avalia como `false`. No momento, o CloudFormation oferece suporte à função intrínseca `Fn::If` no atributo `Metadata` e no atributo `UpdatePolicy` e aos valores de propriedade nas seções `Resources` e `Outputs` de um modelo. Você pode usar o pseudoparâmetro `AWS::NoValue` como um valor de retorno para remover a propriedade correspondente. ### Declaração #### JSON ``` "Fn::If": [condition_name, value_if_true, value_if_false] ``` #### YAML Sintaxe para o nome da função completo: ``` Fn::If: [condition_name, value_if_true, value_if_false] ``` Sintaxe para a forma resumida: ``` !If [condition_name, value_if_true, value_if_false] ``` ### Parâmetros condition\$1name Uma referência a uma condição na seção Condições. Use o nome da condição para fazer referência a ele. value\$1if\$1true Um valor a ser retornado se a condição especificada avalia como true. value\$1if\$1false Um valor a ser retornado se a condição especificada avalia como `false`. ### Exemplos de uso de `Fn::If` **Topics** + [Escolher condicionalmente um recurso](#w2aac24c20c19b9b5) + [Saídas condicionais](#w2aac24c20c19b9b7) + [Valores de matriz condicional](#w2aac24c20c19b9b9) + [Propriedades condicionais e valores de propriedades](#w2aac24c20c19b9c11) + [Políticas condicionais de atualização](#w2aac24c20c19b9c13) #### Escolher condicionalmente um recurso O exemplo a seguir usa uma função `Fn::If` em uma definição de recurso do Amazon EC2 para determinar qual recurso de grupo de segurança associar à instância. Se a condição `CreateNewSecurityGroup` for avaliada como verdadeira, o CloudFormation usará o valor referenciado `NewSecurityGroup` (um grupo de segurança criado em outro lugar no modelo) para especificar a propriedade `SecurityGroupIds`. Se `CreateNewSecurityGroup` for falsa, o CloudFormation usará o valor referenciado de `ExistingSecurityGroupId` (um parâmetro que faz referência a um grupo de segurança existente). ##### 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] ``` #### Saídas condicionais Na seção `Output` de um modelo, você pode usar a função `Fn::If` para emitir condicionalmente informações. No seguinte trecho, se a condição `CreateNewSecurityGroup` for verdadeira, o CloudFormation emitirá o ID do grupo de segurança do recurso `NewSecurityGroup`. Se a condição for falsa, o CloudFormation emitirá o ID do grupo de segurança do recurso `ExistingSecurityGroup`. ##### 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] ``` #### Valores de matriz condicional O exemplo a seguir usa `Fn::If` para fornecer condicionalmente diferentes valores de matriz com base em uma condição. Se a condição `MoreThan2AZs` for avaliada como verdadeira, ele usará três sub-redes públicas. Caso contrário, ele usará somente duas sub-redes públicas. ##### 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 ``` #### Propriedades condicionais e valores de propriedades O exemplo a seguir usa o pseudoparâmetro `AWS::NoValue` em uma função `Fn::If`. A condição usa um snapshot para uma instância de banco de dados do Amazon RDS somente se o ID do snapshot é fornecido. Se a condição `UseDBSnapshot` for avaliada como verdadeira, o CloudFormation usará o valor do parâmetro `DBSnapshotName` para a propriedade `DBSnapshotIdentifier`. Se a condição for avaliada como falsa, o CloudFormation removerá a propriedade `DBSnapshotIdentifier`. Ele também usa uma função `Fn::If` na propriedade `AllocatedStorage` da instância de banco de dados do Amazon RDS. Se a condição `IsProduction` for avaliada como verdadeira, o tamanho do armazenamento será definido como `100`. Caso contrário, ele será definido como `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"] ``` #### Políticas condicionais de atualização O seguinte trecho oferece uma política de atualização do Auto Scaling somente se a condição `RollingUpdates` for verdadeira. Se a condição for avaliada como falsa, o CloudFormation removerá a política de atualização `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` Retorna `true` para uma condição que avalia como `false` ou retorna `false` para uma condição que avalia como `true`. `Fn::Not` funciona como o operador NOT. ### Declaração #### JSON ``` "Fn::Not": [{condition}] ``` #### YAML Sintaxe para o nome da função completo: ``` Fn::Not: [condition] ``` Sintaxe para a forma resumida: ``` !Not [condition] ``` ### Parâmetros condition Uma condição como `Fn::Equals` que avalia como `true` ou `false`. ### Exemplos de uso de `Fn::Not` A seguinte condição `EnvCondition` será avaliada como verdadeira se o valor para o parâmetro `EnvironmentType` não for igual a `prod`: #### JSON ``` "MyNotCondition" : { "Fn::Not" : [{ "Fn::Equals" : [ {"Ref" : "EnvironmentType"}, "prod" ] }] } ``` #### YAML ``` MyNotCondition: !Not [!Equals [!Ref EnvironmentType, prod]] ``` ## `Fn::Or` Retorna `true` se alguma das condições especificadas forem verdadeiras, ou retornarem `false` se todas as condições forem falsas. O `Fn::Or` atua como operador OR. O número mínimo de condições que você pode incluir é 2 e o máximo é 10. ### Declaração #### JSON ``` "Fn::Or": [{condition}, {...}] ``` #### YAML Sintaxe para o nome da função completo: ``` Fn::Or: [condition, ...] ``` Sintaxe para a forma resumida: ``` !Or [condition, ...] ``` ### Parâmetros condition Uma condição que avalia como `true` ou `false`. ### Exemplos de uso de `Fn::Or` O seguinte `MyOrCondition` avalia como verdadeiro se o nome do security group referenciado é igual a `sg-mysggroup` ou se `SomeOtherCondition` avalia como verdadeiro: #### JSON ``` "MyOrCondition" : { "Fn::Or" : [ {"Fn::Equals" : ["sg-mysggroup", {"Ref" : "ASecurityGroup"}]}, {"Condition" : "SomeOtherCondition"} ] } ``` #### YAML ``` MyOrCondition: !Or [!Equals [sg-mysggroup, !Ref ASecurityGroup], Condition: SomeOtherCondition] ``` ## Funções compatíveis Você pode usar as seguintes funções na condição `Fn::If`: + `Fn::Base64` + `Fn::FindInMap` + `Fn::GetAtt` + `Fn::GetAZs` + `Fn::If` + `Fn::Join` + `Fn::Select` + `Fn::Sub` + `Ref` Você pode usar as seguintes funções em todas as outras funções de condição, como `Fn::Equals` e `Fn::Or`: + `Fn::FindInMap` + `Ref` + Outras funções de condição ## Modelo de exemplo ### Crie condicionalmente recursos para uma produção, desenvolvimento ou teste de pilha Em alguns casos, você pode criar pilhas que são semelhantes, mas com pequenos ajustes. Por exemplo, você pode ter um modelo que você usa para aplicativos de produção. Você deseja criar a mesma pilha de produção, para que você possa usá-la para desenvolvimento ou teste. No entanto, para desenvolvimento e teste, você pode não exigir toda a capacidade extra incluída em uma pilha de nível de produção. Em vez disso, você pode usar um parâmetro de entrada no tipo de ambiente para criar condicionalmente os recursos de pilha que são específicos para produção, desenvolvimento ou testes, como mostrado no seguinte exemplo: Você pode especificar `prod`, `dev` ou `test` para o parâmetro `EnvType`. Para cada tipo de ambiente, o modelo especifica um tipo de instância diferente. Os tipos de instância podem variar desde um tipo de instância grande, otimizada por computação, até um tipo de instância pequeno, de uso geral. Para especificar condicionalmente o tipo de instância, o modelo define duas condições na seção `Conditions`do modelo: `CreateProdResources`, que avalia como verdadeiro se o valor do parâmetro `EnvType` é igual a `prod` e `CreateDevResources`, que avalia como verdadeiro se o valor do parâmetro é igual a `dev`. Na propriedade `InstanceType`, o modelo aninha duas funções intrínsecas `Fn::If` para determinar qual tipo de instância deverá ser usada. Se a condição `CreateProdResources` for verdadeira, o tipo de instância será `c5.xlarge`. Se a condição for falsa, a condição `CreateDevResources` será avaliada. Se a condição `CreateDevResources` for verdadeira, o tipo de instância será `t3.medium`; caso contrário, o tipo de instância será `t3.small`. Além do tipo de instância, o ambiente de produção cria e anexa um volume do Amazon EC2 à instância. Os recurso `MountPoint` e `NewVolume` estão associados à condição `CreateProdResources` para que os recursos sejam criados somente se a condição for verdadeira. **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 ``` **nota** Para exemplos mais complexos do uso de condições para criar recursos, consulte o tópico [`Condition`Atributo](aws-attribute-condition.md). # `Fn::FindInMap` A função intrínseca `Fn::FindInMap` retorna o valor correspondente às chaves em um mapa de dois níveis que é declarado na seção `Mappings`. ## Declaração ### JSON ``` { "Fn::FindInMap" : [ "MapName", "TopLevelKey", "SecondLevelKey"] } ``` ### YAML Sintaxe para o nome da função completo: ``` Fn::FindInMap: [ MapName, TopLevelKey, SecondLevelKey ] ``` Sintaxe para a forma resumida: ``` !FindInMap [ MapName, TopLevelKey, SecondLevelKey ] ``` **nota** Você não pode aninhar duas instâncias de duas funções na forma abreviada. ## Parâmetros MapName O nome lógico de um mapeamento declarado na seção de mapeamento que contém as chaves e os valores. TopLevelKey O nome da chave de nível superior. Seu valor é uma lista de pares de chave/valor. SecondLevelKey O nome da chave de segundo nível, que é definido para uma das chaves na lista atribuída ao `TopLevelKey`. ## Valor de retorno O valor que é atribuído a `SecondLevelKey`. ## Exemplos Os exemplos a seguir demonstram como usar a função `Fn::FindInMap`. **Topics** + [Usar Fn::FindInMap com valores específicos da região](#intrinsic-function-reference-findinmap-region-example) + [Usar Fn::FindInMap para configurações específicas do ambiente](#intrinsic-function-reference-findinmap-environment-example) ### Usar Fn::FindInMap com valores específicos da região O exemplo a seguir mostra como usar `Fn::FindInMap` em um modelo que inclui dois mapeamentos: `AWSInstanceType2Arch` e `AWSRegionArch2AMI`. Também inclui um parâmetro `InstanceType` que permite escolher entre `t3.micro` e `t4g.nano`. O padrão é `t3.micro`, mas pode ser substituído durante a criação da pilha. O `Fn::FindInMap` primeiro determina a arquitetura (`HVM64` ou `ARM64`) com base no tipo de instância selecionado e pesquisa a ID da AMI correta para essa arquitetura na atual Região da AWS. **nota** Os IDs de AMI mostrados nesses exemplos são espaços reservados para fins de demonstração. Sempre que possível, considere usar referências dinâmicas aos parâmetros AWS Systems Manager como alternativa à seção `Mappings`. Para evitar atualizar todos os modelos com um novo ID sempre que a AMI que você deseja usar for alterada, use um parâmetro AWS Systems Manager para recuperar o ID da AMI mais recente quando a pilha for criada ou atualizada. As versões mais recentes de AMIs comumente usadas também estão disponíveis como parâmetros públicos no Systems Manager. Para obter mais informações, consulte [Obter valores armazenados em outros serviços usando referências dinâmicas](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 ``` ### Usar Fn::FindInMap para configurações específicas do ambiente O exemplo a seguir mostra como usar `Fn::FindInMap` em um modelo com uma seção `Mappings` que contém um único mapa, `SecurityGroups`. Ele também contém um parâmetro `EnvironmentType` que permite especificar se o ambiente é `Dev` ou `Prod`. O padrão é `Dev`, mas pode ser substituído durante a criação da pilha. `Fn::FindInMap` retorna o `SecurityGroupIds` apropriado com base no parâmetro `EnvironmentType`. Depois, `Fn::Split` divide a string separada por vírgulas de IDs de grupos de segurança em uma lista, que é o formato esperado para [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). Se você implantar essa pilha com `EnvironmentType` definido como `Dev`, `SecurityGroupIds` para `EC2Instance` será `sg-12345678`. Se você definir `EnvironmentType` como `Prod`, ele usará `sg-abcdef01` e `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 ] ``` ## Funções compatíveis Você pode usar as seguintes funções em uma função `Fn::FindInMap`: + `Fn::FindInMap` + `Ref` ## Recursos relacionados Para usar outras funções intrínsecas ou um valor padrão em uma função `Fn::FindInMap`, é necessário declarar a transformação `AWS::LanguageExtensions` no modelo. Para obter mais informações, consulte [`Fn::FindInMap enhancements`](intrinsic-function-reference-findinmap-enhancements.md). Esses tópicos relacionados podem ser úteis à medida que você desenvolve modelos que usam a função `Fn::FindInMap`. + [`Fn::Sub`](intrinsic-function-reference-sub.md) + [Sintaxe de Mappings do modelo do CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/mappings-section-structure.html) no *Guia do usuário do AWS CloudFormation* # `Fn::ForEach` A função intrínseca `Fn::ForEach` utiliza uma coleção e um fragmento e aplica os itens da coleção ao identificador no fragmento fornecido. `Fn::ForEach` pode conter outras funções intrínsecas, inclusive a própria `Fn::ForEach`, e ser usada nas seções `Conditions`, `Outputs` e `Resources` (incluindo as propriedades do recurso). Ela não pode ser usada em nenhuma das seções a seguir: `AWSTemplateFormatVersion`, `Description`, `Metadata`, `Transform`, `Parameters`, `Mappings`, `Rules`, ou `Hooks`. Se você usar a função intrínseca `Fn::ForEach` em seu modelo, também deverá usar o [`AWS::LanguageExtensions`Transformação](transform-aws-languageextensions.md). O uso da função intrínseca `Fn::ForEach` não altera as cotas que se aplicam ao modelo resultante. As cotas incluem o tamanho máximo de um modelo e o número máximo de recursos em um modelo. Para obter mais informações, consulte [Entender cotas do CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cloudformation-limits.html) no *Guia do usuário do AWS CloudFormation*. ## Declaração ### JSON ``` "Fn::ForEach::LoopLogicalName": [ "Identifier", ["Value1","Value2"], // Collection {"OutputKey": {OutputValue}} ] ``` ### YAML ``` 'Fn::ForEach::LoopLogicalName': - Identifier - - Value1 # Collection - Value2 - 'OutputKey': OutputValue ``` ## Parâmetros *Nome lógico do loop* Um ID lógico para o loop. O nome deve ser exclusivo no modelo e não pode entrar em conflito com nenhum valor lógico de ID na seção `Resources` do modelo. Esse nome não está na saída transformada. Ele é usado para referência interna no próprio modelo do CloudFormation. *Identificador* Um identificador para o espaço reservado que é substituído nos parâmetros `OutputKey` e `OutputValue`. Todas as instâncias de `${Identifier}` ou `&{Identifier}` nos parâmetros `OutputKey` e `OutputValue` serão substituídas pelos valores do parâmetro `Collection`. *Coleta* A coleção de valores sobre os quais iterar. Isso pode ser uma matriz nesse parâmetro ou pode ser uma [`Ref`](intrinsic-function-reference-ref.md) para uma `CommaDelimitedList`. Ao usar `&{Identifier}`, os caracteres que não são alfanuméricos podem ser passados na `Collection`. *Chave de saída* A chave no modelo transformado. `${Identifier}` ou `&{Identifier}` deve ser incluído no parâmetro `OutputKey`. Por exemplo, se `Fn::ForEach` for usado na seção `Resources` do modelo, esse será o ID lógico de cada recurso. A sintaxe `&{}` permite que caracteres não alfanuméricos em `Collection` sejam usados no parâmetro `OutputKey`. Para obter um exemplo disso, consulte [Passar caracteres não alfanuméricos da `Collection` para `Fn::ForEach`](intrinsic-function-reference-foreach-example-resource.md#intrinsic-function-reference-foreach-example-non-alphanumeric). *Valor de saída* O valor que é replicado no modelo transformado para cada item no parâmetro `Collection`. Por exemplo, se `Fn::ForEach` for usado na seção `Resources` do modelo, esse será o fragmento do modelo repetido para configurar cada recurso. ## Valor de retorno Um objeto expandido que contém o fragmento do objeto repetido uma vez para cada item na coleção, em que o identificador no fragmento é substituído pelo item da coleção. ## Funções compatíveis É possível usar as funções a seguir em `Fn::ForEach`. + Funções de condição: + [`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) ## Exemplos É possível encontrar exemplos das seções `Conditions`, `Outputs` e `Resources` no [Exemplos](intrinsic-function-reference-foreach-examples.md). # Exemplos **Topics** + [Exemplos de `Fn::ForEach` na seção `Resources`](intrinsic-function-reference-foreach-example-resource.md) + [Exemplos de `Fn::ForEach` na seção `Outputs`](intrinsic-function-reference-foreach-example-outputs.md) + [Exemplos de `Fn::ForEach` na seção `Conditions`](intrinsic-function-reference-foreach-example-conditions.md) # Exemplos de `Fn::ForEach` na seção `Resources` Estes exemplos demonstram o uso da função intrínseca `Fn::ForEach` na seção `Resources`. Para obter mais informações sobre esta seção, consulte [Recursos](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/resources-section-structure.html) no *Guia do usuário do AWS CloudFormation*. **Topics** + [Replicar um recurso do Amazon SNS](#intrinsic-function-reference-foreach-example-replicate-resource) + [Replicar um recurso do Amazon DynamoDB](#intrinsic-function-reference-foreach-example-replicate-ddb-resource) + [Replicar vários recursos](#intrinsic-function-reference-foreach-example-replicate-multiple-resources) + [Replicar vários recursos usando loops `Fn::ForEach` aninhados](#intrinsic-function-reference-foreach-example-nested-loop-resources) + [Fazer referência a propriedades replicadas para um recurso do Amazon EC2](#intrinsic-function-reference-foreach-example-reference-replicated-resource) + [Replicar propriedades de um recurso do Amazon EC2](#intrinsic-function-reference-foreach-example-replicate-resource-properties) + [Passar caracteres não alfanuméricos da `Collection` para `Fn::ForEach`](#intrinsic-function-reference-foreach-example-non-alphanumeric) ## Replicar um recurso do Amazon SNS Este trecho de exemplo retorna uma lista de quatro tópicos do Amazon SNS, com o ID lógico correspondente aos itens na coleção (`Success`, `Failure`, `Timeout`, `Unknown`), com um `TopicName` correspondente e `FifoTopic` definido como `true`. **nota** Para modelos que precisam funcionar com tópicos FIFO e padrão, você pode usar a propriedade `DisplayName` em vez de `TopicName`. Isso permite que o CloudFormation gere automaticamente nomes de tópicos com o sufixo apropriado `.fifo` quando `FifoTopic` for `true`. Basta substituir `TopicName` por `DisplayName: !Ref TopicName` na seção `Properties`. ### 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 ``` O modelo transformado será equivalente ao modelo a seguir: ``` 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 ``` ## Replicar um recurso do Amazon DynamoDB Este trecho de exemplo cria quatro recursos [AWS::DynamoDB::Table](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-dynamodb-table.html) com nomes como `Points`, `Score` etc. ### 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' ``` O modelo transformado será equivalente ao modelo a seguir: ``` 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' ``` ## Replicar vários recursos Este exemplo cria várias instâncias do [AWS::EC2::NatGateway](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ec2-natgateway.html) e do [AWS::EC2::EIP](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ec2-eip.html) usando uma convenção chamada `"{ResourceType}${Identifier}"`. É possível declarar vários tipos de recursos em um loop `Fn::ForEach` para usar um único identificador. Valores exclusivos para cada elemento na coleção são definidos na seção `Mappings`, onde a função intrínseca [`Fn::FindInMap`](intrinsic-function-reference-findinmap.md) é usada para referenciar o valor correspondente. Se `Fn::FindInMap` não for capaz de encontrar o identificador correspondente, a propriedade `Condition` não será definida como resolvendo no `!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 ``` O modelo transformado será equivalente ao modelo a seguir: ``` 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 ``` ## Replicar vários recursos usando loops `Fn::ForEach` aninhados Este exemplo usa loops `Fn::ForEach` aninhados para mapear três recursos ([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) e [AWS::EC2::SubnetNetworkAclAssociation](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ec2-subnetnetworkaclassociation.html)) entre si. ### 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' ``` O modelo transformado será equivalente ao modelo a seguir: ``` 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 ``` ## Fazer referência a propriedades replicadas para um recurso do Amazon EC2 Este exemplo usa a função intrínseca `Fn::ForEach` para fazer referência a recursos [AWS::EC2::Instance](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ec2-instance.html) replicados. ### 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] ``` O modelo transformado será equivalente ao modelo a seguir: ``` 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] ``` ## Replicar propriedades de um recurso do Amazon EC2 Este exemplo usa a função intrínseca `Fn::ForEach` para repetir algumas propriedades como `ImageId`, `InstanceType` e `AvailabilityZone` em um recurso [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'} ``` O modelo transformado será equivalente ao modelo a seguir: ``` 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 ``` ## Passar caracteres não alfanuméricos da `Collection` para `Fn::ForEach` Este exemplo usa a sintaxe `&{}`, que permite que caracteres não alfanuméricos (`.` e `/`) nos endereços IP sejam passados na `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 ``` O modelo transformado será equivalente ao modelo a seguir: ``` 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 ``` # Exemplos de `Fn::ForEach` na seção `Outputs` Estes exemplos demonstram o uso da função intrínseca `Fn::ForEach` na seção `Outputs`. Para obter mais informações sobre esta seção, consulte [Saídas](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/outputs-section-structure.html) no *Guia do usuário do AWS CloudFormation*. **Topics** + [Fazer referência a recursos `AWS::S3::Bucket` replicados](#intrinsic-function-reference-foreach-example-replicate-outputs) + [Fazer referência a recursos `AWS::EC2::Instance` replicados](#intrinsic-function-reference-foreach-example-replicate-conditions) ## Fazer referência a recursos `AWS::S3::Bucket` replicados Este exemplo usa loops `Fn::ForEach` aninhados na seção `Outputs` para reduzir o tamanho do modelo. ### 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] ``` O modelo transformado será equivalente ao modelo a seguir: ``` 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] ``` ## Fazer referência a recursos `AWS::EC2::Instance` replicados Este exemplo faz referência a recursos replicados na seção `Resources` usando os IDs lógicos gerados. ### 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] ``` O modelo transformado será equivalente ao modelo a seguir: ``` 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] ``` # Exemplos de `Fn::ForEach` na seção `Conditions` Estes exemplos demonstram o uso da função intrínseca `Fn::ForEach` na seção `Conditions`. Para obter mais informações sobre esta seção, consulte [Condições](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/conditions-section-structure.html) no *Guia do usuário do AWS CloudFormation*. **Importante** `Conditions` deve ser a segunda propriedade listada ou estar listada posteriormente. A criação da pilha apresentará falhas se `Conditions` for a primeira propriedade listada no parâmetro de fragmento do modelo para `Fn::ForEach`. ``` Resources: 'Fn::ForEach::Topics': - LogicalId - !Ref TopicList - '${LogicalId}': Condition: !Sub 'TopicCondition${LogicalId}' Type: AWS::SNS::Topic Properties: TopicName: !Sub 'My${LogicalId}' ``` `Conditions` deve ser adicionada como a segunda chave, ou posteriormente, para que a criação da pilha ocorra com êxito: ``` Resources: 'Fn::ForEach::Topics': - LogicalId - !Ref TopicList - '${LogicalId}': Type: AWS::SNS::Topic Condition: !Sub 'TopicCondition${LogicalId}' Properties: TopicName: !Sub 'My${LogicalId}' ``` **Topics** + [Replicar uma condição única](#intrinsic-function-reference-foreach-example-replicated-single-condition) ## Replicar uma condição única Este exemplo usa a função intrínseca `Fn::ForEach` na seção `Conditions` para replicar várias condições semelhantes com propriedades diferentes. ### 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 ``` O modelo transformado será equivalente ao modelo a seguir: ``` 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` A função intrínseca `Fn::GetAtt` retorna o valor de um atributo obtido de um recurso no modelo. ## Declaração ### JSON ``` { "Fn::GetAtt" : [ "logicalNameOfResource", "attributeName" ] } ``` ### YAML Sintaxe para o nome da função completo: ``` Fn::GetAtt: [ logicalNameOfResource, attributeName ] ``` Sintaxe para a forma resumida: ``` !GetAtt logicalNameOfResource.attributeName ``` ## Parâmetros `logicalNameOfResource` O nome lógico (também chamado de *ID lógico*) do recurso que contém o atributo que você deseja. `attributeName` O nome do atributo específico do recurso cujo valor é desejado. Consulte a página de referência do recurso para obter mais detalhes sobre os atributos disponíveis para esse tipo de recurso. ## Valor de retorno O valor de atributo. Para obter informações sobre valores de retorno de `GetAtt` para recursos, consulte a documentação dos recursos em [Referência de propriedades e recursos](aws-template-resource-type-ref.md). ## Exemplos ### Retornar um valor de atributo Este exemplo retorna uma string que contém o nome DNS do balanceador de carga com o nome lógico `myELB`. #### JSON ``` "Fn::GetAtt" : [ "myELB" , "DNSName" ] ``` #### YAML ``` !GetAtt myELB.DNSName ``` #### Retornar múltiplos valores de atributos O modelo de exemplo a seguir retorna `SourceSecurityGroup.OwnerAlias` e `SourceSecurityGroup.GroupName` do balanceador de carga com o nome lógico `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 ``` #### Usar `Fn::Sub` dentro da função `Fn::GetAtt` **nota** Ao usar a transformação `AWS::LanguageExtensions`, você pode usar `Fn::GetAtt` em combinação com outras funções intrínsecas. Para ver as funções com suporte, consulte [Funções compatíveis](#getatt-supported-functions). Os seguintes exemplos mostram como usar `Fn::GetAtt` com [`Fn::Sub`](intrinsic-function-reference-sub.md) em conjunto com [`Fn::ForEach`](intrinsic-function-reference-foreach.md) na seção `Outputs` de um modelo para reduzir o tamanho e o detalhamento do modelo. O uso de `Fn::Sub` em `Fn::GetAtt` permite que o modelo contenha uma função intrínseca que pode fazer referência a um bucket diferente em cada iteração da chamada `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 ``` ## Funções compatíveis Quando a [transformação AWS::LanguageExtensions](transform-aws-languageextensions.md) é usada, é possível usar as funções a seguir dentro da função `Fn::GetAtt`. Isso é verdade com o nome do recurso lógico `Fn::GetAtt` ou o nome do atributo `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) Quando a transformação `AWS::LanguageExtensions` não é usada: + O nome de atributo `Fn::GetAtt` só pode usar a função [`Ref`](intrinsic-function-reference-ref.md). + O nome do recurso lógico `Fn::GetAtt` não pode usar funções. É necessário especificar uma string que seja um ID lógico do recurso. # `Fn::GetAZs` A função intrínseca `Fn::GetAZs` retorna uma matriz que lista as zonas de disponibilidade para uma região especificada em ordem alfabética. Como os clientes têm acesso a diferentes zonas de disponibilidade, a função intrínseca `Fn::GetAZs` permite que os autores do modelo gravem modelos que se adaptam ao acesso do usuário da chamada. Dessa forma, não é necessário realizar a codificação rígida de uma lista completa de zonas de disponibilidade para uma região especificada. **Importante** A função `Fn::GetAZs` retorna apenas as zonas de disponibilidade que tenham uma sub-rede padrão, a menos que nenhuma das zonas de disponibilidade tenha uma sub-rede padrão. Nesse caso, todas as zonas de disponibilidade são retornadas. Da mesma forma que a resposta do comando `describe-availability-zones`da AWS CLI, a ordem dos resultados da função `Fn::GetAZs` não é garantida e pode ser alterada quando novas zonas de disponibilidade forem adicionadas. permissões do IAM As permissões necessárias para usar a função `Fn::GetAZs` dependem da plataforma em que você estiver iniciando as instâncias do Amazon EC2. Para ambas as plataformas, são necessárias permissões para as ações do Amazon EC2 `DescribeAvailabilityZones` e `DescribeAccountAttributes`. Para o EC2-VPC, também são necessárias permissões para a ação do Amazon EC2`DescribeSubnets`. ## Declaração ### JSON ``` { "Fn::GetAZs" : "region" } ``` ### YAML Sintaxe para o nome da função completo: ``` Fn::GetAZs: region ``` Sintaxe para a forma resumida: ``` !GetAZs region ``` ## Parâmetros region O nome da região cujas zonas de disponibilidade você deseja obter. É possível usar o pseudoparâmetro `AWS::Region` para especificar a região na qual a pilha será criada. Especificar uma string vazia é equivalente a especificar `AWS::Region`. ## Valor de retorno A lista de zonas de disponibilidade da região. ## Exemplos ### Avaliar uma região Para esses exemplos, o CloudFormation avalia `Fn::GetAZs` para a seguinte matriz, assumindo que o usuário criou a pilha na região `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 ``` ### Especificar a zona de disponibilidade de uma sub-rede O exemplo a seguir usa `Fn::GetAZs` para especificar uma zona de disponibilidade da sub-rede: #### 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: "" ``` ### Funções aninhadas com YAML em forma abreviada Os exemplos a seguir mostram os padrões válidos para usar as funções intrínsecas aninhadas usando a forma abreviada YAML. Você não pode aninhar funções em forma abreviada consecutivamente, portanto, um padrão como `!GetAZs !Ref` é inválido. #### YAML ``` 1. AvailabilityZone: !Select 2. - 0 3. - !GetAZs 4. Ref: 'AWS::Region' ``` #### YAML ``` 1. AvailabilityZone: !Select 2. - 0 3. - Fn::GetAZs: !Ref 'AWS::Region' ``` ## Funções compatíveis Use a função `Ref` na função `Fn::GetAZs`. # `Fn::ImportValue` A função intrínseca `Fn::ImportValue` retorna o valor de uma saída exportada por outra pilha. Normalmente, você usa essa função para criar referências de pilha cruzada. Para obter mais informações, consulte [Passo a passo: consultar saídas de recursos em outra pilha do CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/walkthrough-crossstackref.html) no *Guia do usuário do AWS CloudFormation*. Nos trechos do modelo de exemplo a seguir, Stack A exporta valores do security group da VPC, e Stack B os importa. **nota** As restrições a seguir se aplicam a referências de pilha cruzada. Para cada Conta da AWS, os nomes de `Export` devem ser exclusivos em uma região. Não é possível criar referências entre pilhas nas diversas regiões. Você pode usar a função intrínseca `Fn::ImportValue` para importar somente valores que foram exportados na mesma região. Para saídas, o valor da propriedade `Name` de uma `Export` não pode utilizar funções `Ref` ou `GetAtt` que dependem de um recurso. Da mesma forma, a função `ImportValue` não pode incluir funções `Ref` ou `GetAtt` que dependem de um recurso. Depois que outra pilha importar um valor de saída, não será possível excluir a pilha que está exportando o valor de saída ou modificar o valor de saída exportado. Todas as importações deverão ser removidas para que você possa excluir a pilha de exportação ou modificar o valor de saída. ## JSON Exportação da Stack 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 Exportação da Stack 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 Importação da Stack 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 Importação da Stack 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' ``` ## Declaração ### JSON ``` { "Fn::ImportValue" : sharedValueToImport } ``` ### YAML Você pode usar o nome completo da função: ``` Fn::ImportValue: sharedValueToImport ``` Como alternativa, você pode usar a forma abreviada: ``` !ImportValue sharedValueToImport ``` **Importante** Você não pode usar a forma abreviada de `!ImportValue` quando ela contém a forma abreviada de `!Sub`. ``` # do not use !ImportValue !Sub '${NetworkStack}-SubnetID' ``` Em vez disso, você deve usar o nome completo da função, por exemplo: ``` Fn::ImportValue: !Sub "${NetworkStack}-SubnetID" ``` ## Parâmetros sharedValueToImport O valor de saída da pilha que você deseja importar. ## Valor de retorno O valor de saída da pilha. ## Exemplo ### JSON ``` { "Fn::ImportValue" : {"Fn::Sub": "${NetworkStackNameParameter}-SubnetID" } } ``` ### YAML ``` Fn::ImportValue: !Sub "${NetworkStackName}-SecurityGroupID" ``` ## Funções compatíveis Você pode usar as seguintes funções na função `Fn::ImportValue`. O valor dessas funções não depende de um recurso. + `Fn::Base64` + `Fn::FindInMap` + `Fn::If` + `Fn::Join` + `Fn::Select` + `Fn::Sub` + `Ref` # `Fn::Join` A função intrínseca `Fn::Join` anexa um conjunto de valores em um único valor, separados pelo delimitador especificado. Se um delimitador é a string vazia, o conjunto de valores é concatenado sem delimitador. ## Declaração ### JSON ``` { "Fn::Join" : [ "delimiter", [ comma-delimited list of values ] ] } ``` ### YAML Sintaxe para o nome da função completo: ``` Fn::Join: [ delimiter, [ comma-delimited list of values ] ] ``` Sintaxe para a forma resumida: ``` !Join [ delimiter, [ comma-delimited list of values ] ] ``` ## Parâmetros delimitador O valor que você deseja que ocorra entre estilhaços. O delimitador ocorrerá apenas entre estilhaços. Não encerrará o valor final. ListOfValues A lista de valores a ser combinados. ## Valor de retorno A string combinada. ## Exemplos ### Unir uma matriz de strings simples O seguinte exemplo retorna: `"a:b:c"`. #### JSON ``` "Fn::Join" : [ ":", [ "a", "b", "c" ] ] ``` #### YAML ``` !Join [ ":", [ a, b, c ] ] ``` ### Unir usando a função Ref com parâmetros O exemplo a seguir usa `Fn::Join` para construir um valor de string. Ele usa a função `Ref` com o parâmetro `AWS::Partition` e o pseudoparâmetro `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 ``` **nota** Consulte também a função [`Fn::Sub`](intrinsic-function-reference-sub.md) para funcionalidade semelhante. ## Funções compatíveis No delimitador `Fn::Join`, não é possível usar nenhuma função. É necessário especificar um valor de string. Para a lista de valores `Fn::Join`, use as seguintes funções: + `Fn::Base64` + `Fn::FindInMap` + `Fn::GetAtt` + `Fn::GetAZs` + `Fn::If` + `Fn::ImportValue` + `Fn::Join` + `Fn::Split` + `Fn::Select` + `Fn::Sub` + `Ref` # `Fn::Length` A função intrínseca `Fn::Length` retorna o número de elementos em uma matriz ou uma função intrínseca que retorna um matriz. **Importante** Você deve usar o [`AWS::LanguageExtensions`Transformação](transform-aws-languageextensions.md) para usar a função intrínseca `Fn::Length`. ## Declaração ### JSON ``` { "Fn::Length" : IntrinsicFunction } ``` ``` { "Fn::Length" : Array } ``` ### YAML ``` Fn::Length : IntrinsicFunction ``` ``` Fn::Length : Array ``` ## Parâmetros `IntrinsicFunction` A função intrínseca que retorna uma matriz da qual você deseja retornar vários elementos. `Array` A matriz da qual você deseja retornar o número de elementos. ## Valor de retorno O número de elementos na função intrínseca que retorna uma matriz ou na matriz passada para a função intrínseca. ## Exemplos ### Retorna o número de elementos em uma função intrínseca que retorna uma matriz Esse exemplo de trecho retorna o número de elementos em uma função intrínseca que retorna uma matriz. A função retorna 3. #### JSON ``` { //... "Transform": "AWS::LanguageExtensions" //... "Fn::Length" : { "Fn::Split": ["|", "a|b|c"] } //... } ``` #### YAML ``` Transform: 'AWS::LanguageExtensions' #... Fn::Length: !Split ["|", "a|b|c"] #... ``` ### Retorna o número de elementos em uma função intrínseca Ref que referencia um tipo de parâmetro de lista Esse exemplo de trecho retorna o número de elementos em uma função intrínseca `Ref` que referencia um tipo de parâmetro de lista. Se o parâmetro com o nome `ListParameter` for uma lista com 3 elementos, a função retornará 3. #### JSON ``` { //... "Transform": "AWS::LanguageExtensions" //... "Fn::Length": { "Ref": "ListParameter" } //... } ``` #### YAML ``` Transform: 'AWS::LanguageExtensions' #... Fn::Length: !Ref ListParameter #... ``` ### Retornar o número de elementos em uma matriz Esse exemplo de trecho retorna o número de elementos na matriz passada para a uma função intrínseca. A função retorna 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 #... ``` ## Funções compatíveis Você pode usar as funções a seguir na função intrínseca `Fn::Length` ou na matriz: + `Condition Functions` + `Fn::Base64` + `Fn::FindInMap` + `Fn::Join` + `Fn::Length` + `Fn::Select` + `Fn::Split` + `Fn::Sub` + `Fn::ToJsonString` + `Ref` # `Fn::Select` A função intrínseca `Fn::Select` retorna um único objeto a partir de uma lista de objetos por índice. **Importante** `Fn::Select`O não verifica valores nulos ou se o índice está fora dos limites da série. Ambas as condições resultarão em um erro de pilha, portanto, você deverá ter certeza de que o índice escolhido é válida e se a lista contém valores não nulos. ## Declaração ### JSON ``` { "Fn::Select" : [ index, listOfObjects ] } ``` ### YAML Sintaxe para o nome da função completo: ``` Fn::Select: [ index, listOfObjects ] ``` Sintaxe para a forma resumida: ``` !Select [ index, listOfObjects ] ``` ## Parâmetros índice O índice do objeto para recuperar. Isto deve ser um valor de zero a N-1, onde N representa o número de elementos na série. listOfObjects A lista de objetos para selecionar. Essa lista não deve ser nula nem pode ter entradas nulas. ## Valor de retorno O objeto selecionado. ## Exemplos ### Exemplo básico O seguinte exemplo retorna: `"grapes"`. #### JSON ``` { "Fn::Select" : [ "1", [ "apples", "grapes", "oranges", "mangoes" ] ] } ``` #### YAML ``` !Select [ "1", [ "apples", "grapes", "oranges", "mangoes" ] ] ``` ### Tipo de parâmetros da lista delimitada por vírgula Você pode usar `Fn::Select` para selecionar um objeto a partir de um parâmetro `CommaDelimitedList`. Você pode usar um parâmetro `CommaDelimitedList` para combinar os valores dos parâmetros relacionados, que reduz o número total de parâmetros no seu modelo. Por exemplo, o parâmetro a seguir especifica uma lista delimitada por vírgulas de três blocos 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" ``` Para especificar um dos três blocos de CIDR, use `Fn::Select` na seção Recursos do mesmo modelo, conforme mostrado no snippet de amostra a seguir: #### 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 ] ``` ### Funções aninhadas com YAML em forma abreviada Os exemplos a seguir mostram os padrões válidos para usar as funções intrínsecas aninhadas com a forma abreviada `!Select`. Você não pode aninhar funções em forma abreviada consecutivamente, portanto, um padrão como `!GetAZs !Ref` é inválido. #### YAML ``` AvailabilityZone: !Select - 0 - !GetAZs Ref: 'AWS::Region' ``` #### YAML ``` AvailabilityZone: !Select - 0 - Fn::GetAZs: !Ref 'AWS::Region' ``` ## Funções compatíveis Para obter o valor de índice de `Fn::Select`, você pode usar as funções `Ref` e `Fn::FindInMap`. Para obter a lista de objetos `Fn::Select`, use as funções a seguir: + `Fn::FindInMap` + `Fn::GetAtt` + `Fn::GetAZs` + `Fn::If` + `Fn::Split` + `Ref` # `Fn::Split` Para dividir uma string em uma lista de valores de string, para que você possa selecionar um elemento na lista de strings resultante, use a função intrínseca `Fn::Split`. Especifique o local das divisões com um delimitador, como `,` (uma vírgula). Após dividir uma string, use a função [`Fn::Select`](intrinsic-function-reference-select.md) para escolher um elemento específico. Por exemplo, se uma string de IDs de sub-rede delimitada por vírgulas for importada para seu modelo de pilha, você poderá dividir a string em cada vírgula. Na lista de IDs de sub-rede, use a função intrínseca `Fn::Select` para especificar um ID de sub-rede para um recurso. ## Declaração ### JSON ``` { "Fn::Split" : [ "delimiter", "source string" ] } ``` ### YAML Sintaxe para o nome da função completo: ``` Fn::Split: [ delimiter, source string ] ``` Sintaxe para a forma resumida: ``` !Split [ delimiter, source string ] ``` ## Parameters Você deve especificar os dois parâmetros. delimitador Um valor de string que determina onde a string de origem será dividida. string de origem O valor de string que você deseja dividir. ## Valor de retorno Uma lista de valores de string. ## Exemplos Os exemplos a seguir demonstram o comportamento da função `Fn::Split`. ### Lista simples O exemplo a seguir divide uma string em cada barra vertical (`|`). A função exibe `["a", "b", "c"]`. #### JSON ``` { "Fn::Split" : [ "|" , "a|b|c" ] } ``` #### YAML ``` !Split [ "|" , "a|b|c" ] ``` ### Lista com valores de string vazios Se você dividir uma string com delimitadores consecutivos, a lista resultante incluirá uma string vazia. O exemplo a seguir mostra como uma string com dois delimitadores consecutivos e um delimitador anexado é dividida. A função exibe `["a", "", "c", ""]`. #### JSON ``` { "Fn::Split" : [ "|" , "a||c|" ] } ``` #### YAML ``` !Split [ "|" , "a||c|" ] ``` ### Divisão de um valor de saída importado O exemplo a seguir divide um valor de saída importado e seleciona o terceiro elemento na lista resultante de IDs de sub-rede, conforme especificado pela função `Fn::Select`. #### JSON ``` { "Fn::Select" : [ "2", { "Fn::Split": [",", {"Fn::ImportValue": "AccountSubnetIDs"}]}] } ``` #### YAML ``` !Select [2, !Split [",", !ImportValue AccountSubnetIDs]] ``` ## Funções compatíveis No delimitador `Fn::Split`, não é possível usar nenhuma função. É necessário especificar um valor de string. Para a lista de valores `Fn::Split`, use as seguintes funções: + `Fn::Base64` + `Fn::FindInMap` + `Fn::GetAtt` + `Fn::GetAZs` + `Fn::If` + `Fn::ImportValue` + `Fn::Join` + `Fn::Select` + `Fn::Sub` + `Ref` # `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) # `Fn::ToJsonString` A função intrínseca `Fn::ToJsonString` converte um objeto ou matriz na string JSON correspondente. **Importante** Você deve usar o [`AWS::LanguageExtensions`Transformação](transform-aws-languageextensions.md) para usar a função intrínseca `Fn::ToJsonString`. ## Declaração ### JSON ``` { "Fn::ToJsonString": Object } ``` ``` { "Fn::ToJsonString": Array } ``` ### YAML ``` Fn::ToJsonString: Object ``` ``` Fn::ToJsonString: Array ``` ## Parâmetros `Object` O objeto que você deseja converter em uma string JSON. `Array` A matriz que você deseja converter em uma string JSON. ## Valor de retorno O objeto ou a matriz convertidos em uma string JSON. ## Exemplos ### Converter um objeto em uma string JSON Esse exemplo de trecho converte o objeto passado para a função intrínseca em uma string JSON. #### JSON ``` { //... "Transform": "AWS::LanguageExtensions" //... "Fn::ToJsonString": { "key1": "value1", "key2": { "Ref": "ParameterName" } } //... } ``` #### YAML ``` Transform: 'AWS::LanguageExtensions' #... Fn::ToJsonString: key1: value1 key2: !Ref ParameterName #... ``` Em ambos os exemplos, se a `Ref` para `ParameterName` for resolvida como `resolvedValue`, a função será resolvida como a seguinte string JSON: ``` "{\"key1\":\"value1\",\"key2\":\"resolvedValue\"}" ``` ### Converter uma matriz em uma string JSON Esse exemplo de trecho converte a matriz passada para a função intrínseca em uma string JSON. #### JSON ``` { //... "Transform": "AWS::LanguageExtensions" //... "Fn::ToJsonString": [{ "key1": "value1", "key2": { "Ref": "ParameterName" } }] //... } ``` #### YAML ``` Transform: 'AWS::LanguageExtensions' #... Fn::ToJsonString: - key1: value1 key2: !Ref ParameterName #... ``` Em ambos os exemplos, se a `Ref` para `ParameterName` for resolvida como `resolvedValue`, a função será resolvida como a seguinte string JSON: ``` "[{\"key1\":\"value1\"},{\"key2\":\"resolvedValue\"}]" ``` ## Funções compatíveis Você pode usar as funções a seguir na função intrínseca `Fn::ToJsonString` ou na matriz: + `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` A função intrínseca `Fn::Transform` especifica uma macro para realizar o processamento personalizado em parte de um modelo de pilha. Macros permitem realizar o processamento personalizado em modelos, desde ações simples, como operações de localizar e substituir, até transformações extensas de modelos inteiros. Para obter mais informações, consulte [Usar macros do CloudFormation para executar processamento personalizado em modelos](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-macros.html) no *Guia do usuário do AWS CloudFormation*. Você também pode usar `Fn::Transform` para chamar a transformação [`AWS::Include`Transformação](transform-aws-include.md), que é uma macro hospedado pelo CloudFormation. ## Declaração ### JSON Sintaxe para o nome da função completo: ``` { "Fn::Transform": { "Name": "macro name", "Parameters": { "Key": "value" } } } ``` Sintaxe para a forma resumida: ``` { "Transform": { "Name": "macro name", "Parameters": { "Key": "value" } } } ``` ### YAML Sintaxe para o nome da função completo: ``` Fn::Transform: Name : macro name Parameters : Key : value ``` Sintaxe para a forma resumida: ``` !Transform Name: macro name Parameters: Key: value ``` ## Parâmetros `Name` O nome da macro da qual você deseja realizar o processamento. `Parameters` Os parâmetros de lista, especificados como pares de chave/valor a serem transferidos para a macro. ## Valor de retorno O trecho de modelo processado a ser incluído no modelo de pilha. ## Exemplos O exemplo a seguir chama a transformação `AWS::Include`, especificando que o local de onde recuperar um trecho de modelo é transmitido no parâmetro `InputValue`. ### JSON ``` { "Fn::Transform": { "Name": "AWS::Include", "Parameters": { "Location": { "Ref": "InputValue" } } } } ``` ### YAML ``` Fn::Transform: Name: AWS::Include Parameters: Location: !Ref InputValue ``` ## Funções compatíveis Nenhum. O CloudFormation transmite qualquer chamada de função intrínseca incluída em `Fn::Transform` à macro especificada como strings de literal. # `Ref` A função intrínseca `Ref` retorna o valor do recurso, parâmetro ou outra função intrínseca especificada. Essa função é comumente usada para criar referências entre recursos em um modelo do CloudFormation. ## Declaração ### JSON ``` { "Ref" : "logicalName" } ``` ``` { "Ref" : "IntrinsicFunction" } ``` ### YAML Sintaxe para o nome da função completo: ``` Ref: logicalName ``` ``` Ref: IntrinsicFunction ``` Sintaxe para a forma resumida: ``` !Ref logicalName ``` ``` !Ref IntrinsicFunction ``` ## Parâmetros logicalName O nome lógico do recurso ou parâmetro que você deseja referenciar. IntrinsicFunction A função intrínseca que é resolvida como uma string válida. Ela deve conter referências a parâmetros ou identificadores e não deve conter identificadores lógicos de recursos. ## Valor de retorno O valor de retorno de `Ref` depende do tipo de entidade que está sendo referenciada: + Quando você especifica um nome lógico do parâmetro, ele retorna o valor do parâmetro. Para obter mais informações, consulte [Sintaxe do modelo Parameters do CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html). + Quando você especifica o nome lógico de um recurso, ele retorna um valor que você usa para identificar esse recurso. Normalmente, esse é o nome do recurso. No entanto, para alguns recursos, um identificador é retornado com outro significado importante no contexto do recurso. Por exemplo, o recurso `AWS::EC2::EIP` retorna o endereço IP, enquanto `AWS::EC2::Instance` retorna o ID da instância. Para obter mais informações sobre valores de retorno `Ref` para um recurso, consulte a documentação desse recurso na [Referência de propriedades e recursos](aws-template-resource-type-ref.md). + Quando você especifica uma função intrínseca, ela retorna a saída dessa função. ## Exemplos ### Criar referências entre recursos A declaração de recurso a seguir para um endereço IP elástico necessita do ID de instância de uma instância do EC2. Ela usa a função `Ref` para especificar o ID da instância do recurso `MyEC2Instance` declarado em outro lugar no modelo. #### 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 ``` ### Retornar um identificador de recurso como saída da pilha Os exemplos a seguir mostram como usar a função `Ref` para retornar o nome de um bucket do Amazon S3 com o nome lógico `MyBucket` como saída da pilha. #### 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 ``` ### Usar a função intrínseca `Fn::Join` dentro da função `Ref` **nota** Ao usar a transformação `AWS::LanguageExtensions`, você pode usar `Ref` em combinação com outras funções intrínsecas. Para ver as funções com suporte, consulte [Funções compatíveis](#ref-supported-functions). Os exemplos a seguir mostram como definir identificadores de recursos usando a função intrínseca `Fn::Sub`, condições e a entrada para o parâmetro `Stage`. As funções `Ref` e `Fn::GetAtt` então fazem referência aos valores apropriados com base no estágio. `Fn::Sub` é usada primeiramente com `Fn::GetAtt` para obter o ARN da fila apropriada do Amazon SQS para definir as dimensões do alarme do Amazon CloudWatch. Em seguida, [`Fn::Join`](intrinsic-function-reference-join.md) é usada com `Ref` para criar o nome do tópico SNS para a propriedade `AlarmActions`. #### 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 ``` ## Funções compatíveis Quando a [transformação AWS::LanguageExtensions](transform-aws-languageextensions.md) é usada, é possível usar as funções a seguir dentro da função `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` # Funções de regras As funções de regra são funções especiais que funcionam somente na seção `Rules` de um modelo do CloudFormation. Essas funções ajudam você a validar valores de parâmetros usando lógica personalizada. Todas as validações ocorrem antes que o CloudFormation crie ou atualize quaisquer recursos. As regras são úteis quando as restrições de parâmetros padrão são insuficientes. Por exemplo, quando o SSL estiver habilitado, um certificado e um nome de domínio deverão ser fornecidos. Uma regra pode garantir que essas dependências sejam atendidas. Na condição ou asserções de uma regra, você pode usar as funções intrínsecas, como `Fn::Equals`, `Fn::Not` e `Fn::RefAll`. A propriedade da condição determina se o CloudFormation se aplica a asserções. Se a condição for avaliada como `true`, o CloudFormation avaliará as asserções para verificar se um valor de parâmetro é válido quando uma pilha for criada ou atualizada. Se um valor de parâmetro não for válido, o CloudFormation não criará ou atualizará a pilha. Se a condição for avaliada como `false`, o CloudFormation não verificará o valor do parâmetro e prosseguirá com a operação de pilha. Se você é novo no uso de regras em seus modelos, recomendamos analisar primeiro o tópico de [Sintaxe de Rules do modelo do CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/rules-section-structure.html) no *Guia do usuário do AWS CloudFormation*. **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) + [Funções compatíveis](#supported-rule-functions) + [Atributos compatíveis](#rules-parameter-attributes) ## `Fn::And` Retorna `true` se todas as condições especificadas forem avaliadas como `true`; retorna `false` se alguma das condições for avaliada como `false`. `Fn::And` funciona como um operador AND. O número mínimo de condições que você pode incluir é duas, e o máximo é dez. ### Declaração ``` "Fn::And" : [{condition}, {...}] ``` ### Parâmetros *condição* Uma função intrínseca específica da regra que pode ser avaliada como `true` ou `false`. ### Exemplo O exemplo a seguir será avaliado como `true` se o nome do grupo de segurança referenciado for igual a `sg-mysggroup` e se o valor do parâmetro `InstanceType` for `t3.large` ou `t3.small`: ``` "Fn::And": [ { "Fn::Equals": [ "sg-mysggroup", {"Ref": "ASecurityGroup"} ] }, { "Fn::Contains": [ [ "t3.large", "t3.small" ], {"Ref": "InstanceType"} ] } ] ``` ## `Fn::Contains` Retorna `true` se uma string especificada corresponder a pelo menos um valor em uma lista de strings. ### Declaração ``` "Fn::Contains" : [[list_of_strings], string] ``` ### Parâmetros *list\$1of\$1strings* Uma lista de strings, como `"A", "B", "C"`. *string* Uma string, como `"A"`, que você compara com uma lista de strings. ### Exemplo A função a seguir será avaliada como `true` se o valor do parâmetro `InstanceType` estiver contido na lista (`t3.large` ou `t3.small`): ``` "Fn::Contains" : [ ["t3.large", "t3.small"], {"Ref" : "InstanceType"} ] ``` ## `Fn::EachMemberEquals` Retorna `true` se uma string especificada corresponder a todos os valores em uma lista. ### Declaração ``` "Fn::EachMemberEquals" : [[list_of_strings], string] ``` ### Parâmetros *list\$1of\$1strings* Uma lista de strings, como `"A", "B", "C"`. *string* Uma string, como `"A"`, que você compara com uma lista de strings. ### Exemplo A função a seguir retornará `true` se a etiqueta `Department` de todos os parâmetros do tipo `AWS::EC2::VPC::Id` tiver o valor de `IT`. ``` "Fn::EachMemberEquals" : [ {"Fn::ValueOfAll" : ["AWS::EC2::VPC::Id", "Tags.Department"]}, "IT" ] ``` ## `Fn::EachMemberIn` Retorna `true` se cada membro em uma lista de strings corresponder a pelo menos um valor em uma segunda lista de strings. ### Declaração ``` "Fn::EachMemberIn" : [[strings_to_check], [strings_to_match]] ``` ### Parâmetros *strings\$1to\$1check* Uma lista de strings, como `"A", "B", "C"`. O CloudFormation verifica se cada membro no parâmetro `strings_to_check` está no parâmetro `strings_to_match`. *strings\$1to\$1match* Uma lista de strings, como `"A", "B", "C"`. Cada membro no parâmetro `strings_to_match` é comparado com os membros do parâmetro `strings_to_check`. ### Exemplo A função a seguir verifica se os usuários especificam uma sub-rede que esteja em uma Virtual Private Cloud (VPC). A VPC deve estar na conta e na região em que os usuários estão trabalhando com a pilha. A função aplica-se a todos os parâmetros do tipo `AWS::EC2::Subnet::Id`. ``` "Fn::EachMemberIn" : [ {"Fn::ValueOfAll" : ["AWS::EC2::Subnet::Id", "VpcId"]}, {"Fn::RefAll" : "AWS::EC2::VPC::Id"} ] ``` ## `Fn::Equals` Compara dois valores para determinar se eles são iguais. Retorna `true` se os dois valores forem iguais e `false` se eles não forem. ### Declaração ``` "Fn::Equals" : ["value_1", "value_2"] ``` ### Parâmetros *`value`* Um valor de qualquer tipo para você comparar com outro valor. ### Exemplo O exemplo a seguir será avaliado como `true` se o valor do parâmetro `EnvironmentType` for igual a `prod`: ``` "Fn::Equals" : [{"Ref" : "EnvironmentType"}, "prod"] ``` ## `Fn::Not` Retorna `true` para uma condição que avalia como `false` e retorna `false` para uma condição que avalia como `true`. `Fn::Not` funciona como o operador NOT. ### Declaração ``` "Fn::Not" : [{condition}] ``` ### Parâmetros *`condition`* Uma função intrínseca específica da regra que pode ser avaliada como `true` ou `false`. ### Exemplo O exemplo a seguir será avaliado como `true` se o valor do parâmetro `EnvironmentType` não for igual a `prod`: ``` "Fn::Not" : [{"Fn::Equals" : [{"Ref" : "EnvironmentType"}, "prod"]}] ``` ## `Fn::Or` Retorna `true` se uma das condições especificadas for avaliada como `true`; retorna `false` se todas as condições forem avaliadas como `false`. `Fn::Or` funciona como um operador OR. O número mínimo de condições que você pode incluir é duas, e o máximo é dez. ### Declaração ``` "Fn::Or" : [{condition}, {...}] ``` ### Parâmetros *`condition`* Uma função intrínseca específica da regra que pode ser avaliada como `true` ou `false`. ### Exemplo O exemplo a seguir será avaliado como `true` se o nome do grupo de segurança referenciado for igual a `sg-mysggroup` ou se o valor do parâmetro `InstanceType` for `t3.large` ou `t3.small`: ``` "Fn::Or" : [ {"Fn::Equals" : ["sg-mysggroup", {"Ref" : "ASecurityGroup"}]}, {"Fn::Contains" : [["t3.large", "t3.small"], {"Ref" : "InstanceType"}]} ] ``` ## `Fn::RefAll` Retorna todos os valores de determinado tipo de parâmetro. ### Declaração ``` "Fn::RefAll" : "parameter_type" ``` ### Parâmetros *parameter\$1type* Um tipo de parâmetro específico da AWS, como `AWS::EC2::SecurityGroup::Id` ou `AWS::EC2::VPC::Id`. Para obter mais informações, consulte [Tipos de parâmetros específicos da AWS compatíveis](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cloudformation-supplied-parameter-types.html#aws-specific-parameter-types-supported) no *Guia do usuário do AWS CloudFormation*. ### Exemplo A seguinte função retorna uma lista de todos os IDs da VPC para a região e para a Conta da AWS em que a pilha está sendo criada ou atualizada: ``` "Fn::RefAll" : "AWS::EC2::VPC::Id" ``` ## `Fn::ValueOf` Retorna um valor de atributo ou lista de valores de um parâmetro e atributo específicos. ### Declaração ``` "Fn::ValueOf" : [ "parameter_logical_id", "attribute" ] ``` ### Parâmetros *atributo* O nome de um atributo do qual você deseja recuperar um valor. Para obter mais informações sobre atributos, consulte [Atributos compatíveis](#rules-parameter-attributes). *parameter\$1logical\$1id* O nome de um parâmetro do qual você deseja recuperar valores de atributos. O parâmetro já deve estar declarado na seção `Parameters` do modelo. ### Exemplos O exemplo a seguir retorna o valor da tag `Department` para a VPC que é especificada pelo parâmetro `ElbVpc`: ``` "Fn::ValueOf" : ["ElbVpc", "Tags.Department"] ``` Se você especificar vários valores para um parâmetro, a função Fn::ValueOf poderá retornar uma lista. Por exemplo, você pode especificar várias sub-redes e obter uma lista de zonas de disponibilidade, em que cada membro é a Zona de disponibilidade de determinada sub-rede: ``` "Fn::ValueOf" : ["ListOfElbSubnets", "AvailabilityZone"] ``` ## `Fn::ValueOfAll` Retorna uma lista de valores de atributos de um tipo de parâmetro e atributo. ### Declaração ``` "Fn::ValueOfAll" : ["parameter_type", "attribute"] ``` ### Parâmetros *atributo* O nome de um atributo do qual você quer recuperar um valor. Para obter mais informações sobre atributos, consulte [Atributos compatíveis](#rules-parameter-attributes). *parameter\$1type* Um tipo de parâmetro específico da AWS, como `AWS::EC2::SecurityGroup::Id` ou `AWS::EC2::VPC::Id`. Para obter mais informações, consulte [Tipos de parâmetros específicos da AWS compatíveis](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cloudformation-supplied-parameter-types.html#aws-specific-parameter-types-supported) no *Guia do usuário do AWS CloudFormation*. ### Exemplo No exemplo a seguir, a função `Fn::ValueOfAll` retorna uma lista de valores, em que cada membro é o valor da tag `Department` das VPCs com essa tag: ``` "Fn::ValueOfAll" : ["AWS::EC2::VPC::Id", "Tags.Department"] ``` ## Funções compatíveis Você não pode usar outra função nas funções `Fn::ValueOf` e `Fn::ValueOfAll`. No entanto, você pode usar as seguintes funções dentro de todas as outras funções intrínsecas específicas de regras: + `Ref` + Outras funções intrínsecas específicas de regras ## Atributos compatíveis A lista a seguir descreve os valores de atributos que você pode recuperar para tipos específicos de recursos e parâmetros: O tipo de parâmetro `AWS::EC2::VPC::Id` ou IDs da VPC. + DefaultNetworkAcl + DefaultSecurityGroup + Tags.*tag\$1key* O tipo de parâmetro `AWS::EC2::Subnet::Id` ou IDs da sub-rede. + AvailabilityZone + Tags.*tag\$1key* + VpcId O tipo de parâmetro `AWS::EC2::SecurityGroup::Id` ou IDs do grupo de segurança. + Tags.*tag\$1key*