這是新的 *CloudFormation 範本參考指南*。請更新您的書籤和連結。如需 CloudFormation 入門的說明，請參閱 [AWS CloudFormation 使用者指南](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# `Fn::FindInMap`
內部函數 `Fn::FindInMap` 傳回對應 `Mappings` 區段中所宣告之兩個層級映射之索引鍵的值。
## 宣告
### JSON
```
{ "Fn::FindInMap" : [ "MapName", "TopLevelKey", "SecondLevelKey"] }
```
### YAML
完整函式名稱的語法：
```
Fn::FindInMap: [ MapName, TopLevelKey, SecondLevelKey ]
```
短格式的語法：
```
!FindInMap [ MapName, TopLevelKey, SecondLevelKey ]
```
**注意**
您無法以短形式巢套兩個函數的兩個執行個體。
## Parameters
MapName
在 Mappings 區段中宣告的映射邏輯名稱，包含索引鍵和值。
TopLevelKey
最上層的索引鍵名稱。其值為鍵/值對的清單。
SecondLevelKey
第二層的索引鍵名稱，設定為指派給 `TopLevelKey` 之清單中的其中一個索引鍵。
## 傳回值
指派給 `SecondLevelKey` 的值。
## 範例
以下範例會示範 `Fn::FindInMap` 函數的使用方式。
**Topics**
+ [使用具有區域特定值的 Fn::FindInMap](#intrinsic-function-reference-findinmap-region-example)
+ [將 Fn::FindInMap 用於環境特定的組態](#intrinsic-function-reference-findinmap-environment-example)
### 使用具有區域特定值的 Fn::FindInMap
下列範例示範如何在包含兩個映射的範本中使用 `Fn::FindInMap`：`AWSInstanceType2Arch` 和 `AWSRegionArch2AMI`。它還包含 `InstanceType` 參數，可讓您在 `t3.micro` 和 `t4g.nano` 之間進行選擇。預設值為 `t3.micro`，但可以在堆疊建立期間覆寫它。
`Fn::FindInMap` 首先會根據選取的執行個體類型決定架構 (`HVM64` 或 `ARM64`)，然後在目前的 AWS 區域中查詢該架構的正確 AMI ID。
**注意**
這些範例中顯示的 AMI ID 是用作示範用途的預留位置。盡可能考慮使用 AWS Systems Manager 參數的動態參考作為 `Mappings` 區段的替代方案。若要避免在每次要使用變更的 AMI 時，使用新 ID 更新所有範本，請在建立或更新堆疊時，使用 AWS Systems Manager 參數擷取最新的 AMI ID。Systems Manager 中也提供最新版本的常用 AMI 作為公有參數。如需詳細資訊，請參閱[使用動態參考取得存放在其他服務中的值](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
```
### 將 Fn::FindInMap 用於環境特定的組態
以下範例說明如何將 `Fn::FindInMap` 用於具有 `Mappings` 區段的範本，該區段包含單一映射 `SecurityGroups`。它也包含 `EnvironmentType` 參數，可讓您指定環境是 `Dev` 還是 `Prod`。預設為 `Dev`，但可以在堆疊建立期間覆寫它。
`Fn::FindInMap` 根據 `EnvironmentType` 參數傳回適當的 `SecurityGroupIds`。然後，`Fn::Split` 會將逗號分隔的安全群組 ID 字串分割為清單，這是 [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) 的預期格式。
如果您在 `EnvironmentType` 設定為 `Dev` 的情況下部署此堆疊，則 `EC2Instance` 的 `SecurityGroupIds` 將為 `sg-12345678`。如果將 `EnvironmentType` 設定為 `Prod`，則會使用 `sg-abcdef01` 和 `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 ]
```
## 支援的函數
您可以在 `Fn::FindInMap` 函數中善用以下函數：
+ `Fn::FindInMap`
+ `Ref`
## 相關資源
若要在 `Fn::FindInMap` 函數中使用其他內建函數或預設值，則必須在範本中宣告 `AWS::LanguageExtensions` 轉換。如需詳細資訊，請參閱[`Fn::FindInMap enhancements`](intrinsic-function-reference-findinmap-enhancements.md)。
當您開發使用 `Fn::FindInMap` 函數的範本時，這些相關主題會很有幫助。
+ [`Fn::Sub`](intrinsic-function-reference-sub.md)
+ **《AWS CloudFormation 使用者指南》中的 [CloudFormation 範本 Mappings 語法](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/mappings-section-structure.html)