Fn::FindInMap - AWS CloudFormation
DeclaraçãoParâmetrosValor de retornoExemplosFunções compatíveisRecursos relacionados

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.

Usar Fn::FindInMap com valores específicos da região

O exemplo a seguir mostra como usar Fn::FindInMap em um modelo com uma seção Mappings que contém um único mapa, RegionMap, que associa AMIs com regiões da AWS.

  • O mapa tem 5 chaves de nível superior que correspondem a várias regiões da AWS.

  • Cada chave de nível superior é atribuída a uma lista com duas chaves de segundo nível, "HVM64" e "HVMG2", que correspondem à arquitetura da AMI.

  • Cada uma das chaves de segundo nível é atribuída com um nome de AMI apropriada.

O modelo de exemplo a seguir contém um recurso AWS::EC2::Instance cuja propriedade ImageId é definida pela função FindInMap.

O MapName é definido como o mapa de interesse, que é "RegionMap" neste exemplo. A TopLevelKey é definida como a região na qual a pilha é criada, que é determinada usando o pseudoparâmetro "AWS::Region". A SecondLevelKey está definida como a arquitetura desejada, que é "HVM64" para este exemplo.

FindInMap retorna a AMI atribuída à FindInMap. Para uma instância HVM64 em us-east-1, FindInMap retornaria "ami-0ff8a91507f77f867".

nota

Considere os parâmetros AWS Systems Manager como uma 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 o tipo de parâmetro AWS::SSM::Parameter::Value<AWS::EC2::Image::Id> 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 ter mais informações, consulte Especificar recursos existentes no runtime com tipos de parâmetros fornecidos pelo CloudFormation.

JSON

{
  ...
  "Mappings" : {
    "RegionMap" : {
      "us-east-1" : { 
        "HVM64" : "ami-0ff8a91507f77f867", "HVMG2" : "ami-0a584ac55a7631c0c" 
      },
      "us-west-1" : { 
        "HVM64" : "ami-0bdb828fd58c52235", "HVMG2" : "ami-066ee5fd4a9ef77f1" 
      },
      "eu-west-1" : { 
        "HVM64" : "ami-047bb4163c506cd98", "HVMG2" : "ami-0a7c483d527806435" 
      },
      "ap-southeast-1" : { 
        "HVM64" : "ami-08569b978cc4dfa10", "HVMG2" : "ami-0be9df32ae9f92309" 
      },
      "ap-northeast-1" : { 
        "HVM64" : "ami-06cd52961ce9f0d85", "HVMG2" : "ami-053cdd503598e4a9d" 
      }
    }
  },
  "Resources" : {
    "myEC2Instance" : {
      "Type" : "AWS::EC2::Instance",
      "Properties" : {
        "ImageId" : { 
          "Fn::FindInMap" : [ 
            "RegionMap", 
            { 
              "Ref" : "AWS::Region" 
            }, 
            "HVM64"
          ]
        },
        "InstanceType" : "t2.micro"
      }   
    }
  }
}

YAML

Mappings: 
  RegionMap: 
    us-east-1: 
      HVM64: "ami-0ff8a91507f77f867"
      HVMG2: "ami-0a584ac55a7631c0c"
    us-west-1: 
      HVM64: "ami-0bdb828fd58c52235"
      HVMG2: "ami-066ee5fd4a9ef77f1"
    eu-west-1: 
      HVM64: "ami-047bb4163c506cd98"
      HVMG2: "ami-0a7c483d527806435"
    ap-southeast-1: 
      HVM64: "ami-08569b978cc4dfa10"
      HVMG2: "ami-0be9df32ae9f92309"
    ap-northeast-1: 
      HVM64: "ami-06cd52961ce9f0d85"
      HVMG2: "ami-053cdd503598e4a9d"
Resources: 
  myEC2Instance: 
    Type: "AWS::EC2::Instance"
    Properties: 
      ImageId: !FindInMap
        - RegionMap
        - !Ref 'AWS::Region'
        - HVM64
      InstanceType: t2.micro

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.

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

{
  ...
  "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": "ami-0a70b9d193ae8a799",
        "InstanceType": "t2.micro",
        "SecurityGroupIds":{
          "Fn::Split":[
            ",",
            {
              "Fn::FindInMap":[
                "SecurityGroups",
                {
                  "Ref":"EnvironmentType"
                },
                "SecurityGroupIds"
              ]
            }
          ]
        }
      }
    }
  }
}

YAML

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: ami-0a70b9d193ae8a799
      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 ter mais informações, consulte Fn::FindInMap enhancements.

Esses tópicos relacionados podem ser úteis à medida que você desenvolve modelos que usam a função Fn::FindInMap.