這是新的 *CloudFormation 範本參考指南*。請更新您的書籤和連結。如需 CloudFormation 入門的說明，請參閱 [AWS CloudFormation 使用者指南](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)。
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# `Ref`
內建函數 `Ref` 會傳回指定參數、資源或其他內建函數的值。此函數通常用於在 CloudFormation 範本內的資源之間建立參考。
## 宣告
### JSON
```
{ "Ref" : "logicalName" }
```
```
{ "Ref" : "IntrinsicFunction" }
```
### YAML
完整函式名稱的語法：
```
Ref: logicalName
```
```
Ref:
IntrinsicFunction
```
短格式的語法：
```
!Ref logicalName
```
```
!Ref
IntrinsicFunction
```
## Parameters
logicalName
您要參照的資源或參數之邏輯名稱。
IntrinsicFunction
解析為有效字串的內部函數。它應該包含對參數或識別碼的參考，並且不應包含資源邏輯識別碼。
## 傳回值
`Ref` 的傳回值取決於所參考實體的類型：
+ 當您指定參數的邏輯名稱時，它會傳回參數值。如需詳細資訊，請參閱 [CloudFormation 範本 Parameters 語法](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html)。
+ 當您指定資源的邏輯名稱時，它會傳回您用來識別該資源的值。通常，這是資源名稱。但是，針對某些資源，將會傳回一個識別碼，它對於該資源而言有其他重要的意義。例如，`AWS::EC2::EIP` 資源會傳回 IP 位址，而 `AWS::EC2::Instance` 會傳回執行個體 ID。如需有關資源的 `Ref` 傳回值的詳細資訊，請參閱 [資源和屬性參考](aws-template-resource-type-ref.md) 中該資源的文件。
+ 當您指定內部函數時，它會傳回該函數的輸出。
## 範例
### 建立資源之間的參考
下列彈性 IP 位址的資源宣告需要 EC2 執行個體的執行個體 ID。它使用 `Ref` 函數來指定範本中其他位置宣告之 `MyEC2Instance` 資源的執行個體 ID。
#### 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
```
### 將資源識別符傳回為堆疊輸出
下列範例示範如何使用 `Ref` 函數將邏輯名稱為 `MyBucket` 的 Amazon S3 儲存貯體的名稱傳回為堆疊輸出。
#### 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
```
### 使用 `Ref` 函數內的 `Fn::Join` 內建函數
**注意**
使用 `AWS::LanguageExtensions` 轉換時，您可以搭配其他內建函數使用 `Ref`。如需支援的函數，請參閱 [支援的函數](#ref-supported-functions)。
下列範例示範如何使用 `Fn::Sub` 內建函數、條件和 `Stage` 參數輸入來設定資源的識別符。然後，`Ref` 和 `Fn::GetAtt` 函數會根據階段來參考適當的值。`Fn::Sub` 首先與 `Fn::GetAtt` 搭配使用，以獲取適當 Amazon SQS 佇列的 ARN，進而設定 Amazon CloudWatch 警示的維度。接下來，[`Fn::Join`](intrinsic-function-reference-join.md) 會與 `Ref` 搭配使用，以建立 `AlarmActions` 屬性的 SNS 主題名稱。
#### 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
```
## 支援的函數
當使用 [AWS::LanguageExtensions 轉換](transform-aws-languageextensions.md)時，可以使用 `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`