本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 使用虛擬參數取得 AWS 值
<a name="pseudo-parameter-reference"></a>

虛擬參數是內建變數，可讓您存取重要的 AWS 環境資訊，例如帳戶 IDs、區域名稱，以及可在部署或環境之間變更的堆疊詳細資訊。

您可以使用虛擬參數，而不是硬式編碼值，讓您的範本更方便攜帶，並更輕鬆地在不同 AWS 帳戶 和 區域重複使用。

## 語法
<a name="pseudo-parameter-syntax"></a>

您可以透過 `Ref` 內建函數或 `Fn::Sub` 內建函數參考虛擬參數。

### Ref
<a name="pseudo-parameter-ref-syntax"></a>

`Ref` 內建函數使用下列一般語法。如需詳細資訊，請參閱 [Ref](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-ref.html)。

#### JSON
<a name="pseudo-parameter-ref-syntax.json"></a>

```
{ "Ref" : "AWS::PseudoParameter" }
```

#### YAML
<a name="pseudo-parameter-ref-syntax.yaml"></a>

```
!Ref AWS::PseudoParameter
```

### Fn::Sub
<a name="pseudo-parameter-sub-syntax"></a>

`Fn::Sub` 內建函數使用不同格式，在虛擬參數前後加上 `${}` 語法。如需詳細資訊，請參閱 [Fn::Sub](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-sub.html)。

#### JSON
<a name="pseudo-parameter-sub-syntax.json"></a>

```
{ "Fn::Sub" : "${AWS::PseudoParameter}" }
```

#### YAML
<a name="pseudo-parameter-sub-syntax.yaml"></a>

```
!Sub '${AWS::PseudoParameter}'
```

## 可用的虛擬參數
<a name="available-pseudo-parameters"></a>

### `AWS::AccountId`
<a name="cfn-pseudo-param-accountid"></a>

傳回要在其中建立堆疊之帳戶的 AWS 帳戶 ID，例如 `123456789012`。

此虛擬參數常用於定義 IAM 角色、原則及其他涉及帳戶專屬 ARN 的資源原則。

### `AWS::NotificationARNs`
<a name="cfn-pseudo-param-notificationarns"></a>

傳回接收堆疊事件通知的 Amazon SNS 主題對應的 Amazon Resource Name (ARN) 清單。您可以在建立 AWS CLI 或更新堆疊時，透過 中的 `--notification-arns`選項或透過 主控台指定這些 ARNs。

不同於其他傳回單一數值的虛擬參數，`AWS::NotificationARNs` 會傳回 ARN 清單。要存取清單中的特定 ARN，請使用 `Fn::Select` 內建函數。如需詳細資訊，請參閱[https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-select.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-select.html)。

### `AWS::NoValue`
<a name="cfn-pseudo-param-novalue"></a>

若在 `Fn::If` 內部函數中將此參數指定為傳回值，則系統會移除對應的資源屬性。如需詳細資訊，請參閱[https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-conditions.html#intrinsic-function-reference-conditions-if](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/intrinsic-function-reference-conditions.html#intrinsic-function-reference-conditions-if)。

此虛擬參數在建立僅需於特定條件下納入的條件式資源屬性時特別實用。

### `AWS::Partition`
<a name="cfn-pseudo-param-partition"></a>

傳回資源所在的分割區。對於標準 AWS 區域，分割區為 `aws`。如果資源處於其他分割區，則會傳回 `aws-`*partitionname* 分割區。例如，中國 （北京和寧夏） 區域中資源的分割區為 ，`aws-cn`G AWS GovCloud （美國西部） 區域中資源的分割區為 `aws-us-gov`。

分區是資源 ARN 的一部分。使用 `AWS::Partition`可確保您的範本在不同 AWS 分割區之間正確運作。

### `AWS::Region`
<a name="cfn-pseudo-param-region"></a>

傳回建立包容性資源區域的代表字串，例如：`us-west-2`。

這是最常用的虛擬參數之一，因為它允許範本在不修改 AWS 區域 的情況下適應不同的參數。

### `AWS::StackId`
<a name="cfn-pseudo-param-stackid"></a>

傳回堆疊的 ID (ARN)，例如 `arn:aws:cloudformation:us-west-2:123456789012:stack/teststack/51af3dc0-da77-11e4-872e-1234567db123`。

### `AWS::StackName`
<a name="cfn-pseudo-param-stackname"></a>

傳回堆疊的名稱，例如 `teststack`。

堆疊名稱常用於建立獨特的資源名稱，這類名稱易於識別為屬於特定堆疊。

### `AWS::URLSuffix`
<a name="cfn-pseudo-param-urlsuffix"></a>

在部署 AWS 區域 堆疊的 中，傳回 AWS 網域的尾碼。尾碼通常為 `amazonaws.com`，但對於中國 (北京) 區域，尾碼為 `amazonaws.com.cn`。

此參數在建構 AWS 服務端點URLs 時特別有用。

## 範例
<a name="pseudo-parameter-examples"></a>

**Topics**
+ [基本使用](#pseudo-parameter-basic-example)
+ [使用 AWS::NotificationARNs](#pseudo-parameter-notification-example)
+ [具備 AWS::NoValue 的條件屬性](#pseudo-parameter-novalue-example)

### 基本使用
<a name="pseudo-parameter-basic-example"></a>

下列範例建立兩個資源：一個 Amazon SNS 主題，以及一個向該主題傳送通知的 CloudWatch 警示。它們使用 `AWS::StackName`、 `AWS::Region`和 `AWS::AccountId` 將堆疊名稱、目前 AWS 區域和帳戶 ID 動態插入資源名稱、描述和 ARNs。

#### JSON
<a name="pseudo-parameter-basic-example.json"></a>

```
{
    "Resources": {
        "MyNotificationTopic": {
            "Type": "AWS::SNS::Topic",
            "Properties": {
                "DisplayName": { "Fn::Sub": "Notifications for ${AWS::StackName}" }
            }
        },
        "CPUAlarm": {
            "Type": "AWS::CloudWatch::Alarm",
            "Properties": {
                "AlarmDescription": { "Fn::Sub": "Alarm for high CPU in ${AWS::Region}" },
                "AlarmName": { "Fn::Sub": "${AWS::StackName}-HighCPUAlarm" },
                "MetricName": "CPUUtilization",
                "Namespace": "AWS/EC2",
                "Statistic": "Average",
                "Period": 300,
                "EvaluationPeriods": 1,
                "Threshold": 80,
                "ComparisonOperator": "GreaterThanThreshold",
                "AlarmActions": [{ "Fn::Sub": "arn:aws:sns:${AWS::Region}:${AWS::AccountId}:${MyNotificationTopic}" }]
            }
        }
    }
}
```

#### YAML
<a name="pseudo-parameter-basic-example.yaml"></a>

```
Resources:
  MyNotificationTopic:
    Type: AWS::SNS::Topic
    Properties:
      DisplayName: !Sub Notifications for ${AWS::StackName}
  CPUAlarm:
    Type: AWS::CloudWatch::Alarm
    Properties:
      AlarmDescription: !Sub Alarm for high CPU in ${AWS::Region}
      AlarmName: !Sub ${AWS::StackName}-HighCPUAlarm
      MetricName: CPUUtilization
      Namespace: AWS/EC2
      Statistic: Average
      Period: 300
      EvaluationPeriods: 1
      Threshold: 80
      ComparisonOperator: GreaterThanThreshold
      AlarmActions:
        - !Sub arn:aws:sns:${AWS::Region}:${AWS::AccountId}:${MyNotificationTopic}
```

### 使用 AWS::NotificationARNs
<a name="pseudo-parameter-notification-example"></a>

下列範例設定 Auto Scaling 群組，以便在執行個體啟動事件及啟動錯誤時傳送通知。此設定使用 `AWS::NotificationARNs` 虛擬參數，該參數提供建立堆疊時指定的 Amazon SNS 主題 ARN 清單。`Fn::Select` 函數會從該清單中選擇第一個 ARN。

#### JSON
<a name="pseudo-parameter-notification-example.json"></a>

```
"myASG": {
   "Type": "AWS::AutoScaling::AutoScalingGroup",
   "Properties": {
      "LaunchTemplate": {
         "LaunchTemplateId": { "Ref": "myLaunchTemplate" },
         "Version": { "Fn::GetAtt": [ "myLaunchTemplate", "LatestVersionNumber" ] }
       },
       "MaxSize": "1",
       "MinSize": "1",
       "VPCZoneIdentifier": [
          "subnetIdAz1",
          "subnetIdAz2",
          "subnetIdAz3"
      ],
      "NotificationConfigurations" : [{
         "TopicARN" : { "Fn::Select" : [ "0", { "Ref" : "AWS::NotificationARNs" } ] },
         "NotificationTypes" : [ "autoscaling:EC2_INSTANCE_LAUNCH", "autoscaling:EC2_INSTANCE_LAUNCH_ERROR" ]
      }]
   }
}
```

#### YAML
<a name="pseudo-parameter-notification-example.yaml"></a>

```
myASG:
  Type: AWS::AutoScaling::AutoScalingGroup
  Properties:
    LaunchTemplate:
      LaunchTemplateId: !Ref myLaunchTemplate
      Version: !GetAtt myLaunchTemplate.LatestVersionNumber
    MinSize: '1'
    MaxSize: '1'
    VPCZoneIdentifier:
      - subnetIdAz1
      - subnetIdAz2
      - subnetIdAz3
    NotificationConfigurations:
      - TopicARN:
          Fn::Select:
          - '0'
          - Ref: AWS::NotificationARNs
        NotificationTypes:
        - autoscaling:EC2_INSTANCE_LAUNCH
        - autoscaling:EC2_INSTANCE_LAUNCH_ERROR
```

### 具備 AWS::NoValue 的條件屬性
<a name="pseudo-parameter-novalue-example"></a>

下列範例會建立 Amazon RDS 資料庫執行個體，僅在提供快照 ID 時才使用快照。若 `UseDBSnapshot` 條件評估為 true，CloudFormation 會對 `DBSnapshotIdentifier` 屬性使用 `DBSnapshotName` 參數值。若條件評估為 false，CloudFormation 即會移除 `DBSnapshotIdentifier` 屬性。

#### JSON
<a name="pseudo-parameter-novalue-example.json"></a>

```
"MyDB" : {
  "Type" : "AWS::RDS::DBInstance",
  "Properties" : {
    "AllocatedStorage" : "5",
    "DBInstanceClass" : "db.t2.small",
    "Engine" : "MySQL",
    "EngineVersion" : "5.5",
    "MasterUsername" : { "Ref" : "DBUser" },
    "MasterUserPassword" : { "Ref" : "DBPassword" },
    "DBParameterGroupName" : { "Ref" : "MyRDSParamGroup" },
    "DBSnapshotIdentifier" : {
      "Fn::If" : [
        "UseDBSnapshot",
        {"Ref" : "DBSnapshotName"},
        {"Ref" : "AWS::NoValue"}
      ]
    }
  }
}
```

#### YAML
<a name="pseudo-parameter-novalue-example.yaml"></a>

```
MyDB:
  Type: AWS::RDS::DBInstance
  Properties:
    AllocatedStorage: '5'
    DBInstanceClass: db.t2.small
    Engine: MySQL
    EngineVersion: '5.5'
    MasterUsername:
      Ref: DBUser
    MasterUserPassword:
      Ref: DBPassword
    DBParameterGroupName:
      Ref: MyRDSParamGroup
    DBSnapshotIdentifier:
      Fn::If:
        - UseDBSnapshot
        - Ref: DBSnapshotName
        - Ref: AWS::NoValue
```