Este é o novo *Guia de referência de modelos do CloudFormation*. Atualize seus favoritos e links. Para obter ajuda para começar a usar o CloudFormation, consulte o [Guia do usuário do AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html).
# `Fn::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}}"] }
```
Se você quiser especificar um valor alternativo para quando uma chave não for encontrada no mapeamento, inclua um `DefaultValue`:
```
{ "Fn::FindInMap" : [ "{{MapName}}", "{{TopLevelKey}}", "{{SecondLevelKey}}", {"DefaultValue": "{{DefaultValue}}"}] }
```
### YAML
Sintaxe para o nome da função completo:
```
Fn::FindInMap: [ {{MapName}}, {{TopLevelKey}}, {{SecondLevelKey}} ]
```
Sintaxe para a forma resumida:
```
!FindInMap [ {{MapName}}, {{TopLevelKey}}, {{SecondLevelKey}} ]
```
Se você quiser especificar um valor alternativo para quando uma chave não for encontrada no mapeamento, inclua um `DefaultValue`:
Sintaxe para o nome da função completo:
```
Fn::FindInMap:
- {{MapName}}
- {{TopLevelKey}}
- {{SecondLevelKey}}
- DefaultValue: {{DefaultValue}}
```
Sintaxe para a forma resumida:
```
!FindInMap
- {{MapName}}
- {{TopLevelKey}}
- {{SecondLevelKey}}
- DefaultValue: {{DefaultValue}}
```
**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`.
DefaultValue
O valor que o `Fn::FindInMap` retorna se o `TopLevelKey` ou o `SecondLevelKey` não for encontrado no mapeamento especificado. Esse parâmetro é opcional. Se omitido, o `Fn::FindInMap` gera um erro quando uma chave não é encontrada.
O quarto parâmetro deve ser um mapa com a chave `DefaultValue`. Por exemplo: `{"DefaultValue": "us-east-1"}`.
## Valor de retorno
O valor que é atribuído a `SecondLevelKey`. Se o `TopLevelKey` ou o `SecondLevelKey` não for encontrado e o `DefaultValue` for especificado, o `DefaultValue` será retornado em vez disso.
## 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)
+ [Use o Fn::FindInMap com um valor padrão](#intrinsic-function-reference-findinmap-default-value-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 [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 ]
```
### Use o Fn::FindInMap com um valor padrão
O exemplo a seguir usa um `DefaultValue` a para fornecer um substituto quando uma chave não é encontrada no mapeamento. Se a Região da AWS atual não estiver definida no mapeamento `RegionMap`, o `Fn::FindInMap` retorna `t3.micro` em vez de gerar um erro.
#### JSON
```
{
"AWSTemplateFormatVersion": "2010-09-09",
"Mappings": {
"RegionMap": {
"us-east-1": {
"InstanceType": "t3.large"
},
"eu-west-1": {
"InstanceType": "t3.medium"
}
}
},
"Resources": {
"MyInstance": {
"Type": "AWS::EC2::Instance",
"Properties": {
"ImageId": "{{resolve:ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64}}",
"InstanceType": {
"Fn::FindInMap": [
"RegionMap",
{ "Ref": "AWS::Region" },
"InstanceType",
{ "DefaultValue": "t3.micro" }
]
}
}
}
}
}
```
#### YAML
```
AWSTemplateFormatVersion: 2010-09-09
Mappings:
RegionMap:
us-east-1:
InstanceType: t3.large
eu-west-1:
InstanceType: t3.medium
Resources:
MyInstance:
Type: AWS::EC2::Instance
Properties:
ImageId: '{{resolve:ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-x86_64}}'
InstanceType: !FindInMap
- RegionMap
- !Ref AWS::Region
- InstanceType
- DefaultValue: t3.micro
```
## Funções compatíveis
Você pode usar as seguintes funções em uma função `Fn::FindInMap`:
+ `Fn::FindInMap`
+ `Ref`
## Recursos relacionados
Para usar funções intrínsecas além do `Fn::FindInMap` e do `Ref` nos parâmetros de uma função do `Fn::FindInMap`, você deve declarar uma transformação `AWS::LanguageExtensions` no seu 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*