Ref - AWS CloudFormation
DeclaraciónParámetrosValor devueltoEjemplosFunciones compatibles

Ref

La función intrínseca Ref devuelve el valor de un parámetro, recurso u otra función intrínseca específicos. Esta función se suele utilizar para crear referencias entre los recursos de una plantilla de CloudFormation.

Declaración

JSON

{ "Ref" : "logicalName" }
{ "Ref" : "IntrinsicFunction" }

YAML

Sintaxis del nombre de función completo:

Ref: logicalName
Ref:
   IntrinsicFunction

Sintaxis de la forma abreviada:

!Ref logicalName
!Ref
   IntrinsicFunction

Parámetros

logicalName

El nombre lógico del recurso o parámetro del que quiera quitar la referencia.

IntrinsicFunction

La función intrínseca que se resuelve en una cadena válida. Debe contener referencias a parámetros o identificadores, y no debe contener identificadores lógicos de recursos.

Valor devuelto

El valor devuelto de Ref depende del tipo de entidad a la que se hace referencia:

  • Al especificar el nombre lógico de un parámetro, devuelve el valor del parámetro. Para obtener más información, consulte Sintaxis de Parameters de la plantilla de CloudFormation.

  • Al especificar el nombre lógico de un recurso, devuelve un valor que se utiliza para identificar dicho recurso. Normalmente, ese es el nombre del recurso. Sin embargo, para algunos recursos, se devuelve un identificador que tenga otro significado importante en el contexto del recurso. Por ejemplo, el recurso AWS::EC2::EIP devuelve la dirección IP, y AWS::EC2::Instance devuelve el ID de la instancia. Para obtener más información acerca de los valores de devolución de Ref para un recurso, consulte la documentación de dicho recurso en la Referencia de recursos y propiedades.

  • Al especificar una función intrínseca, devuelve la salida de esa función.

Ejemplos

Creación de referencias entre recursos

La siguiente declaración de recursos para una dirección IP elástica necesita el ID de instancia de una instancia de EC2. Utiliza la función Ref para especificar el ID de instancia del recurso MyEC2Instance declarado en otra parte de la plantilla.

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

Devolución de un identificador de recurso como salida de la pila

En los siguientes ejemplos se muestra cómo utilizar la función Ref para devolver el nombre de un bucket de Amazon S3 con el nombre lógico MyBucket como salida de la pila.

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

Uso de la función intrínseca Fn::Join dentro de la función Ref

nota

Cuando utilice la transformación AWS::LanguageExtensions, podrá utilizar Ref en combinación con otras funciones intrínsecas. Para ver las funciones compatibles, consulte Funciones compatibles.

En los siguientes ejemplos se muestra cómo establecer los identificadores de los recursos mediante la función intrínseca Fn::Sub, las condiciones y la entrada del parámetro Stage. A continuación, las funciones Ref y Fn::GetAtt hacen referencia a los valores apropiados, en función de la etapa. Fn::Sub se usa primero con Fn::GetAtt para obtener el ARN de la cola de Amazon SQS adecuada para establecer las dimensiones de la alarma de Amazon CloudWatch. A continuación, Fn::Join se utiliza con Ref para crear el nombre del tema de SNS de la propiedad AlarmActions.

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

Funciones compatibles

Cuando se usa la transformación AWS::LanguageExtensions, se pueden usar las siguientes funciones dentro de la función Ref.