这是新的《CloudFormation 模板参考指南》**。请更新您的书签和链接。有关开始使用 CloudFormation 的帮助，请参阅《AWS CloudFormation 用户指南》[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html](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
```
## 参数
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`