# Sintaxe de Mappings de modelo do CloudFormation A seção opcional `Mappings` ajuda a criar pares de chave-valor que podem ser usados para especificar valores com base em determinadas condições ou dependências. Um caso de uso comum para a seção `Mappings` é definir valores com base na Região da AWS em que a pilha é implantada. Isso pode ser feito por meio do pseudoparâmetro `AWS::Region`. O pseudoparâmetro `AWS::Region` é um valor que o CloudFormation resolve para a região em que a pilha é criada. Os pseudoparâmetros são resolvidos pelo CloudFormation quando você cria a pilha. Para recuperar valores em um mapa, você pode usar a função intrínseca `Fn::FindInMap` na seção `Resources` do seu modelo. ## Sintaxe A seção `Mappings` usa a seguinte sintaxe: ### JSON ``` "Mappings" : { "MappingLogicalName" : { "Key1" : { "Name" : "Value1" }, "Key2" : { "Name" : "Value2" }, "Key3" : { "Name" : "Value3" } } } ``` ### YAML ``` Mappings: MappingLogicalName: Key1: Name: Value1 Key2: Name: Value2 Key3: Name: Value3 ``` + `MappingLogicalName` é o nome lógico do mapeamento. + Dentro de um mapeamento, cada mapa é uma chave seguida por outro mapeamento. + A chave deve ser um mapa de pares nome/valor e exclusiva dentro do mapeamento. + O par de nome/valor é um rótulo e o valor para mapear. Nomeando os valores, você pode mapear mais de um conjunto de valores para uma chave. + As chaves em mapeamentos devem ser sequências literais. + Os valores podem ser do tipo `String` ou `List`. **nota** Você não pode incluir parâmetros, pseudoparâmetros ou funções intrínsecas na seção `Mappings`. Se os valores em um mapeamento não estiverem sendo usados atualmente pela pilha, você não poderá atualizar apenas o mapeamento. Você precisa incluir alterações que adicionam, modificam ou excluem recursos. ## Exemplos **Topics** + [Mapeamento básico](#mappings-section-structure-basic-example) + [Mapeamento com vários valores](#mappings-section-structure-multiple-values-example) + [Retornar um valor de um mapeamento](#mappings-section-structure-return-value-example) + [Parâmetro de entrada e `Fn::FindInMap`](#mappings-section-structure-input-parameter-example) ### Mapeamento básico O exemplo a seguir mostra uma seção `Mappings` com um mapa `RegionToInstanceType` que contém cinco chaves que são mapeadas para pares de nome e valor que contêm valores de sequência únicos. As chaves são nomes de regiões. Cada par de nome-valor é um tipo de instância da família T que está disponível na região representada pela chave. Os pares de nome-valor têm um nome (`InstanceType` no exemplo) e um valor. #### JSON ``` "Mappings" : { "RegionToInstanceType" : { "us-east-1" : { "InstanceType" : "t2.micro" }, "us-west-1" : { "InstanceType" : "t2.micro" }, "eu-west-1" : { "InstanceType" : "t2.micro" }, "eu-north-1" : { "InstanceType" : "t3.micro" }, "me-south-1" : { "InstanceType" : "t3.micro" } } } ``` #### YAML ``` Mappings: RegionToInstanceType: us-east-1: InstanceType: t2.micro us-west-1: InstanceType: t2.micro eu-west-1: InstanceType: t2.micro eu-north-1: InstanceType: t3.micro me-south-1: InstanceType: t3.micro ``` ### Mapeamento com vários valores O exemplo a seguir tem chaves de regiões que são mapeadas para dois conjuntos de valores: uma chamada `MyAMI1` e a outra `MyAMI2`. **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 ``` "Mappings" : { "RegionToAMI" : { "us-east-1" : { "MyAMI1" : "ami-12345678901234567", "MyAMI2" : "ami-23456789012345678" }, "us-west-1" : { "MyAMI1" : "ami-34567890123456789", "MyAMI2" : "ami-45678901234567890" }, "eu-west-1" : { "MyAMI1" : "ami-56789012345678901", "MyAMI2" : "ami-67890123456789012" }, "ap-southeast-1" : { "MyAMI1" : "ami-78901234567890123", "MyAMI2" : "ami-89012345678901234" }, "ap-northeast-1" : { "MyAMI1" : "ami-90123456789012345", "MyAMI2" : "ami-01234567890123456" } } } ``` #### YAML ``` Mappings: RegionToAMI: us-east-1: MyAMI1: ami-12345678901234567 MyAMI2: ami-23456789012345678 us-west-1: MyAMI1: ami-34567890123456789 MyAMI2: ami-45678901234567890 eu-west-1: MyAMI1: ami-56789012345678901 MyAMI2: ami-67890123456789012 ap-southeast-1: MyAMI1: ami-78901234567890123 MyAMI2: ami-89012345678901234 ap-northeast-1: MyAMI1: ami-90123456789012345 MyAMI2: ami-01234567890123456 ``` ### Retornar um valor de um mapeamento Você pode usar a função `Fn::FindInMap` para retornar um valor nomeado com base em uma chave especificada. O modelo de exemplo a seguir contém um recurso do Amazon EC2 cuja propriedade `InstanceType` é atribuída pela função `FindInMap`. A função `FindInMap` especifica a chave como Região da AWS onde a pilha é criada (usando o pseudoparâmetro `AWS::Region`) e `InstanceType` como o nome do valor para o qual mapear. O `ImageId` usa um parâmetro do Systems Manager para recuperar dinamicamente a AMI mais recente do Amazon Linux 2. Para obter mais informações sobre pseudoparâmetros, consulte [Obter valores da AWS usando pseudoparâmetros](pseudo-parameter-reference.md). #### JSON ``` { "AWSTemplateFormatVersion" : "2010-09-09", "Mappings" : { "RegionToInstanceType" : { "us-east-1" : { "InstanceType" : "t2.micro" }, "us-west-1" : { "InstanceType" : "t2.micro" }, "eu-west-1" : { "InstanceType" : "t2.micro" }, "eu-north-1" : { "InstanceType" : "t3.micro" }, "me-south-1" : { "InstanceType" : "t3.micro" } } }, "Resources" : { "myEC2Instance" : { "Type" : "AWS::EC2::Instance", "Properties" : { "ImageId" : "{{resolve:ssm:/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2}}", "InstanceType" : { "Fn::FindInMap" : [ "RegionToInstanceType", { "Ref" : "AWS::Region" }, "InstanceType" ]} } } } } ``` #### YAML ``` AWSTemplateFormatVersion: 2010-09-09 Mappings: RegionToInstanceType: us-east-1: InstanceType: t2.micro us-west-1: InstanceType: t2.micro eu-west-1: InstanceType: t2.micro eu-north-1: InstanceType: t3.micro me-south-1: InstanceType: t3.micro Resources: myEC2Instance: Type: AWS::EC2::Instance Properties: ImageId: '{{resolve:ssm:/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2}}' InstanceType: !FindInMap [RegionToInstanceType, !Ref 'AWS::Region', InstanceType] ``` ### Parâmetro de entrada e `Fn::FindInMap` O seguinte exemplo mostra como criar uma instância do EC2 usando vários mapeamentos. O modelo usa mapeamentos aninhados para selecionar automaticamente o tipo de instância e o grupo de segurança apropriados com base no destino Região da AWS e no tipo de ambiente (`Dev` ou `Prod`). Ele também usa um parâmetro do Systems Manager para recuperar dinamicamente a AMI mais recente do Amazon Linux 2. #### JSON ``` { "AWSTemplateFormatVersion" : "2010-09-09", "Parameters" : { "EnvironmentType" : { "Description" : "The environment type (Dev or Prod)", "Type" : "String", "Default" : "Dev", "AllowedValues" : [ "Dev", "Prod" ] } }, "Mappings" : { "RegionAndEnvironmentToInstanceType" : { "us-east-1" : { "Dev" : "t3.micro", "Prod" : "c5.large" }, "us-west-1" : { "Dev" : "t2.micro", "Prod" : "m5.large" } }, "RegionAndEnvironmentToSecurityGroup" : { "us-east-1" : { "Dev" : "sg-12345678", "Prod" : "sg-abcdef01" }, "us-west-1" : { "Dev" : "sg-ghijkl23", "Prod" : "sg-45678abc" } } }, "Resources" : { "Ec2Instance" : { "Type" : "AWS::EC2::Instance", "Properties" : { "ImageId" : "{{resolve:ssm:/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2}}", "InstanceType" : { "Fn::FindInMap": [ "RegionAndEnvironmentToInstanceType", { "Ref": "AWS::Region" }, { "Ref": "EnvironmentType" } ]}, "SecurityGroupIds" : [{ "Fn::FindInMap" : [ "RegionAndEnvironmentToSecurityGroup", { "Ref" : "AWS::Region" }, { "Ref" : "EnvironmentType" } ]}] } } } } ``` #### YAML ``` AWSTemplateFormatVersion: 2010-09-09 Parameters: EnvironmentType: Description: The environment type (Dev or Prod) Type: String Default: Dev AllowedValues: - Dev - Prod Mappings: RegionAndEnvironmentToInstanceType: us-east-1: Dev: t3.micro Prod: c5.large us-west-1: Dev: t2.micro Prod: m5.large RegionAndEnvironmentToSecurityGroup: us-east-1: Dev: sg-12345678 Prod: sg-abcdef01 us-west-1: Dev: sg-ghijkl23 Prod: sg-45678abc Resources: Ec2Instance: Type: AWS::EC2::Instance Properties: ImageId: '{{resolve:ssm:/aws/service/ami-amazon-linux-latest/amzn2-ami-hvm-x86_64-gp2}}' InstanceType: !FindInMap [RegionAndEnvironmentToInstanceType, !Ref 'AWS::Region', !Ref EnvironmentType] SecurityGroupIds: - !FindInMap [RegionAndEnvironmentToSecurityGroup, !Ref 'AWS::Region', !Ref EnvironmentType] ``` ## Recursos relacionados Esses tópicos relacionados podem ser úteis à medida que você desenvolve modelos que usam a função `Fn::FindInMap`. + [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-findinmap.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-findinmap.html) + [Fn::FindInMap Melhorias do](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-findinmap-enhancements.html) + [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-sub.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-sub.html)