Ref - AWS CloudFormation
DeklarationParameterRückgabewertBeispieleUnterstützte Funktionen

Dies ist das neue CloudFormation Template Reference Guide. Bitte aktualisieren Sie Ihre Lesezeichen und Links. Hilfe bei den ersten Schritten mit CloudFormation finden Sie im AWS CloudFormation Benutzerhandbuch.

Ref

Die intrinsische Funktion Ref gibt den Wert eines angegebenen Parameters, einer Ressource oder einer anderen intrinsischen Funktion zurück. Diese Funktion wird üblicherweise verwendet, um Referenzen zwischen Ressourcen innerhalb einer CloudFormation-Vorlage zu erstellen.

Deklaration

JSON

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

YAML

Syntax für den vollständigen Funktionsnamen:

Ref: logicalName
Ref:
   IntrinsicFunction

Syntax für die Kurzform:

!Ref logicalName
!Ref
   IntrinsicFunction

Parameter

logicalName

Der logische Name der Ressource oder des Parameters, die bzw. der zu referenzieren ist.

IntrinsicFunction

Die intrinsische Funktion, die als gültige Zeichenfolge aufgelöst wird. Sie sollte Verweise auf Parameter oder Kennungen und keine logischen Ressourcenkennungen enthalten.

Rückgabewert

Der Rückgabewert von Ref hängt von der Art der Entität ab, auf die verwiesen wird:

  • Wenn Sie den logischen Namen eines Parameters angeben, wird der Wert des Parameters zurückgegeben. Weitere Informationen finden Sie unter CloudFormation-Vorlage Parameters Syntax.

  • Wenn Sie den logischen Namen einer Ressource angeben, wird ein Wert zurückgegeben, mit dem Sie diese Ressource identifizieren können. Normalerweise ist das der Name der Ressource. Für einige Ressourcen wird jedoch ein Identifikator zurückgegeben, der im Kontext der Ressource eine andere Bedeutung hat. Die Ressource AWS::EC2::EIP gibt zum Beispiel die IP-Adresse zurück und die Ressource AWS::EC2::Instance die Instance-ID. Weitere Informationen über Ref-Rückgabewerte für eine Ressource finden Sie in der Dokumentation für diese Ressource im Abschnitt Ressourcen- und Eigenschaftstypen.

  • Wenn Sie eine intrinsische Funktion angeben, wird die Ausgabe dieser Funktion zurückgegeben.

Beispiele

Referenzen zwischen Ressourcen erstellen

Die folgende Ressourcendeklaration für eine Elastic IP-Adresse benötigt die Instance-ID einer EC2-Instance. Sie verwendet die Funktion Ref, um die Instance-ID der an anderer Stelle in der Vorlage deklarierten Ressource MyEC2Instance anzugeben.

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

Rückgabe einer Ressourcenkennung als Stack-Ausgabe

Die folgenden Beispiele zeigen, wie Sie die Funktion Ref verwenden, um den Namen eines Amazon S3 Buckets mit dem logischen Namen MyBucket als Stack-Ausgabe zurückzugeben.

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

Verwenden Sie die intrinsische Funktion Fn::Join innerhalb der Funktion Ref .

Anmerkung

Wenn Sie die Transformation AWS::LanguageExtensions verwenden, können Sie Ref in Kombination mit anderen intrinsischen Funktionen verwenden. Für unterstützte Funktionen, siehe Unterstützte Funktionen.

Die folgenden Beispiele zeigen, wie Sie mit der intrinsischen Funktion Fn::Sub, den Bedingungen und der Eingabe für den Parameter Stage Identifikatoren von Ressourcen festlegen. Die Funktionen Ref und Fn::GetAtt verweisen dann auf die entsprechenden Werte, die auf der Stufe basieren. Fn::Sub wird zunächst mit Fn::GetAtt verwendet, um die ARN der entsprechenden Amazon SQS-Warteschlange zu erhalten und die Dimensionen des Amazon CloudWatch-Alarms festzulegen. Als nächstes wird Fn::Join mit Ref verwendet, um den Namen des SNS-Themas für die Eigenschaft AlarmActions zu erstellen.

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

Unterstützte Funktionen

Wenn Sie die Funktion AWS::LanguageExtensions transformverwenden, können Sie die folgenden Funktionen innerhalb der Funktion Ref verwenden.