Ref - AWS CloudFormation
DeclaraciónParámetrosValor devueltoEjemplosFunciones compatibles

Ref

La función intrínseca Ref devuelve el valor del parámetro o el recurso especificado. Cuando se usa la transformación Transformación AWS::LanguageExtensions, puede usar funciones intrínsecas como parámetro para Ref y Fn::GetAtt.

  • Al especificar el nombre lógico de un parámetro, devuelve el valor del parámetro.

  • Al especificar el nombre lógico de un recurso, devuelve un valor que se suele utilizar para hacer referencia a dicho recurso, como un ID físico.

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

Al declarar un recurso en una plantilla, si necesita especificar otro recurso de la plantilla por nombre, puede utilizar el Ref para referirse a él. En general, Ref devuelve el nombre del recurso. Por ejemplo, una referencia a AWS::AutoScaling::AutoScalingGroup devuelve el nombre de ese recurso del grupo de Auto Scaling.

Para algunos recursos, se devuelve un identificador que tenga otro significado importante en el contexto del recurso. Un recurso AWS::EC2::EIP, por ejemplo, devuelve la dirección IP, y un AWS::EC2::Instance devuelve el ID de instancia.

sugerencia

También puede usar Ref para agregar valores a los mensajes de Outputs.

Para obtener mas información acerca de los valores de devolución Ref para una propiedad o un recurso concretos, consulte la documentación de dicho recurso o propiedad en la Referencia de recursos y propiedades.

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

Cuando el parámetro es de tipo logicalName, el valor devuelto es el ID físico del recurso o el valor del parámetro.

Cuando el parámetro es de tipo IntrinsicFunction, el valor devuelto es el valor devuelto de la función intrínseca

Ejemplos

Ejemplo

La siguiente declaración de recursos para una dirección IP elástica necesita el ID de instancia de una instancia de EC2 y usa la función Ref para especificar el ID de instancia del recurso MyEC2Instance:

JSON

"MyEIP" : {
   "Type" : "AWS::EC2::EIP",
   "Properties" : {
      "InstanceId" : { "Ref" : "MyEC2Instance" }
   }
}

YAML

MyEIP:
  Type: "AWS::EC2::EIP"
  Properties:
    InstanceId: !Ref MyEC2Instance

Ejemplo de generación de un identificador para varias etapas

En este ejemplo se muestra cómo usar la función intrínseca Fn::Sub para reemplazar los valores del identificador para diferentes etapas. A continuación, se pueden usar las funciones Ref y Fn::GetAtt para hacer referencia a los valores apropiados, en función de la entrada para 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 usa con Ref para crear la cadena de ID lógico del parámetro Stage.

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'
  ProdQueue:
    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

Ejemplo: use la función intrínseca Fn::Sub dentro de la función Ref

En este ejemplo se muestra cómo usar la función intrínseca Fn::Sub para reemplazar los valores de la función Ref. A continuación, se pueden usar las funciones Ref y Fn::GetAtt para hacer referencia a los valores apropiados, en función de la entrada para la etapa. Fn::Sub se usa primero para obtener el ARN del tema de Amazon SNS adecuado para establecer las dimensiones de la alarma de Amazon CloudWatch. A continuación, Fn::Join se usa con Ref para crear la cadena de ID lógico del parámetro Stage.

JSON

{
    "AWSTemplateFormatVersion": "2010-09-09",
    "Transform": "AWS::LanguageExtensions",
    "Parameters": {
        "Stage": {
            "Type": "String",
            "Default": "Dev",
            "AllowedValues": [
                "Dev",
                "Prod"
            ]
        }
    },
    "Resources": {
        "TopicDev": {
            "Type": "AWS::SNS::Topic",
            "Properties": {
                "TopicName": "MyTopic"
            }
        }
    },
    "Outputs": {
        "stageOutput": {
            "Value": {
                "Ref": {
                    "Fn::Sub": "Topic${Stage}"
                }
            }
        }
    }
}

YAML

AWSTemplateFormatVersion: 2010-09-09
Transform: 'AWS::LanguageExtensions'
Parameters:
  Stage:
    Type: String
    Default: Dev
    AllowedValues:
      - Dev
      - Prod
Resources:
  TopicDev:
    Type: 'AWS::SNS::Topic'
    Properties:
      TopicName: MyTopic
Outputs:
  stageOutput:
    Value: !Ref 
      'Fn::Sub': 'Topic${Stage}'

Funciones compatibles

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