Ref - AWS CloudFormation
DéclarationParamètresValeur renvoyéeExemplesFonctions prises en charge

Il s’agit du nouveau Guide de référence des modèles CloudFormation . Veuillez mettre à jour vos favoris et vos liens. Pour obtenir de l'aide pour démarrer CloudFormation, consultez le guide de AWS CloudFormation l'utilisateur.

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Ref

La fonction intrinsèque Ref renvoie la valeur d’un paramètre, d’une ressource ou d’une autre fonction intrinsèque spécifiée. Elle sert couramment à créer des références entre ressources dans un modèle CloudFormation.

Déclaration

JSON

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

YAML

Syntaxe pour le nom complet de la fonction :

Ref: logicalName
Ref:
   IntrinsicFunction

Syntaxe pour la forme courte :

!Ref logicalName
!Ref
   IntrinsicFunction

Paramètres

logicalName

Le nom logique de la ressource ou du paramètre que vous souhaitez référencer.

IntrinsicFunction

La fonction intrinsèque qui se résout dans une chaîne valide. Elle doit contenir des références aux paramètres ou aux identifiants, et ne doit pas contenir d'identifiants de ressources logiques.

Valeur renvoyée

La valeur renvoyée par Ref dépend du type d’entité référencée :

  • Lorsque vous spécifiez le nom logique d'un paramètre, elle renvoie la valeur du paramètre. Pour plus d’informations, consultez Syntaxe Parameters des modèles CloudFormation.

  • Lorsque vous spécifiez le nom logique d’une ressource, elle renvoie une valeur que vous utilisez pour identifier cette ressource. Il s’agit généralement du nom de la ressource. Cependant, pour certaines ressources, la valeur renvoyée est un identifiant ayant une signification particulière dans le contexte de la ressource. Par exemple, la ressource AWS::EC2::EIP renvoie l’adresse IP et AWS::EC2::Instance renvoie l’ID de l’instance. Pour plus d’informations sur les valeurs renvoyées Ref pour chaque ressource, consultez la documentation de cette ressource dans Référence des propriétés et des ressources.

  • Lorsque vous spécifiez une fonction intrinsèque, elle renvoie la sortie de cette fonction.

Exemples

Création de références entre ressources

La déclaration de ressource suivante pour une adresse IP Elastic nécessite l’ID d’une instance EC2. Elle utilise la fonction Ref pour indiquer l’ID de l’instance issue de la ressource MyEC2Instance, déclarée ailleurs dans le modèle.

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

Renvoi d’un identifiant de ressource dans les sorties de pile

Les exemples suivants montrent comment utiliser la fonction Ref pour renvoyer, en sortie de pile, le nom d’un compartiment Amazon S3 ayant pour nom logique MyBucket.

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

Utilisation de la fonction intrinsèque Fn::Join dans la fonction Ref

Note

Lorsque vous utilisez la transformation AWS::LanguageExtensions, vous pouvez utiliser Ref en combinaison avec d’autres fonctions intrinsèques. Pour les fonctions prises en charge, consultez Fonctions prises en charge.

Les exemples suivants montrent comment définir les identifiants des ressources en utilisant la fonction intrinsèque Fn::Sub, des conditions et la valeur d’entrée du paramètre Stage. Les fonctions Ref et Fn::GetAtt référencent ensuite les valeurs appropriées selon l’étape. La fonction Fn::Sub est d’abord utilisée avec Fn::GetAtt pour récupérer l’ARN de la file d’attente Amazon SQS appropriée afin de configurer les dimensions de l’alarme Amazon CloudWatch. Ensuite, Fn::Join est utilisé avec Ref pour créer le nom de la rubrique SNS pour la propriété 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

Fonctions prises en charge

Lorsque vous utilisez la transformation AWS::LanguageExtensions, vous pouvez utiliser les fonctions suivantes dans la fonction Ref.