這是新的 *CloudFormation 範本參考指南*。請更新您的書籤和連結。如需 CloudFormation 入門的說明，請參閱 [AWS CloudFormation 使用者指南](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)。

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

# `AWS::Include` 轉換程序
<a name="transform-aws-include"></a>

本主題說明如何使用 `AWS::Include` 轉換，將樣板式內容插入 CloudFormation 範本中。

`AWS::Include` 是 CloudFormation 巨集，當在堆疊範本中參考它時，如果您使用變更集來建立或更新堆疊，會在範本中的轉換位置插入指定檔案的內容。`AWS::Include` 函數的行為與程式設計語言中的 `include`、`copy` 或 `import` 指令類似。

## Usage
<a name="aws-include-usage"></a>

您可以在 CloudFormation 範本內的任意處使用 `AWS::Include` 轉換，但範本參數區段或範本版本除外。舉例來說，您可以在映射區段中使用 `AWS::Include`。

### 範本最上層的語法
<a name="aws-include-syntax-top-level"></a>

若要在 CloudFormation 範本的頂層將此轉換宣告為 `Transform` 區段，請使用下列語法：

#### JSON
<a name="aws-include-syntax-top-level.json"></a>

```
{
  "Transform":{
    "Name":"AWS::Include",
    "Parameters":{
      "Location":"s3://amzn-s3-demo-bucket/MyFileName.json"
    }
  },
  "Resources":{
    ...
  }
}
```

#### YAML
<a name="aws-include-syntax-top-level.yaml"></a>

```
Transform:
  Name: AWS::Include
  Parameters:
    Location: 's3://amzn-s3-demo-bucket/MyFileName.yaml'
Resources:
  ...
```

### 轉換程序內嵌於範本區段時的語法
<a name="aws-include-syntax-within-section"></a>

若要在 CloudFormation 範本的某個區段中宣告此轉換，請使用 `Fn::Transform` 內建函數和下列語法：

#### JSON
<a name="aws-include-syntax-within-section.json"></a>

```
{
  "Fn::Transform":{
    "Name":"AWS::Include",
    "Parameters":{
      "Location":"s3://amzn-s3-demo-bucket/MyFileName.json"
    }
  }
}
```

#### YAML
<a name="aws-include-syntax-within-section.yaml"></a>

```
Fn::Transform:
  Name: AWS::Include
  Parameters:
    Location: s3://amzn-s3-demo-bucket/MyFileName.yaml
```

如需詳細資訊，請參閱[`Fn::Transform`](intrinsic-function-reference-transform.md)。

### Parameters
<a name="aws-include-parameters"></a>

`Location`

該位置會以 Amazon S3 URI 呈現，其將包含 S3 儲存貯體中的特定檔案名稱；例如 `s3://amzn-s3-demo-bucket/MyFile.yaml`。

## 考量事項
<a name="aws-include-considerations"></a>

使用 `AWS::Include` 時，請謹記下列考量。如需有關使用巨集的更多考量，請參閱《AWS CloudFormation 使用者指南**》中的[巨集考量](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-macros-overview.html#template-macros-considerations)。
+ 我們目前支援 Amazon S3 URI，不支援其他 Amazon S3 格式 (例如 Amazon S3 ARN)。您必須使用 Amazon S3 儲存貯體，而非 GitHub 儲存庫等項目。
+ 具備 Amazon S3 URL 存取權的所有人皆能在範本中加入該程式碼片段。
+ 您的範本程式碼片段均必須是有效的 JSON。
+ 您的範本程式碼片段必須是有效的索引鍵–值物件，例如 `"KeyName": "keyValue"`。
+ 您無法用 `AWS::Include` 來參考也使用 `AWS::Include` 的範本程式碼片段。
+ 若您變更程式碼片段，堆疊並不會自動取得這些變更。如需取得這些變更，請使用更新後的程式碼片段來更新堆疊。更新堆疊時，務必確認加入的程式碼片段不會在您不知悉的情況下有所變更。請查看變更集，即可在更新堆疊前進行驗證。
+ 建立範本與程式碼片段時，可以將 YAML 和 JSON 範本語言混合使用。
+ YAML 程式碼片段目前不支援使用速記表示法。
+ 您可以使用 `AWS::Include` 來提供跨區域複寫 Amazon S3 URI。存取跨區域複寫物件時，請務必檢查 Amazon S3 儲存貯體的名稱。如需詳細資訊，請參閱《Amazon S3 使用者指南**》中的[在區域中和跨區域複寫物件](https://docs.aws.amazon.com/AmazonS3/latest/userguide/replication.html)。

## 範例
<a name="aws-include-examples"></a>

以下範例會說明如何使用 `AWS::Include` 轉換程序來執行等待條件控點。將 *amzn-s3-demo-bucket* 取代為實際的儲存貯體名稱。

首先，將名為 `single_wait_condition.yaml` 的 YAML 檔案儲存在 S3 儲存貯體中，其中包含以下內容：

```
MyWaitCondition:
  Type: AWS::CloudFormation::WaitCondition
  Properties:
    Handle: !Ref MyWaitHandle
    Timeout: '4500'
```

然後，使用 JSON 或 YAML 格式來參考此檔案。

### JSON
<a name="aws-include-example.json"></a>

```
{
   "Resources": {
      "MyWaitHandle": {
         "Type": "AWS::CloudFormation::WaitConditionHandle"
      },
      "Fn::Transform": {
         "Name": "AWS::Include",
         "Parameters": {
            "Location": "s3://amzn-s3-demo-bucket/single_wait_condition.yaml"
         }
      }
   }
}
```

### YAML
<a name="aws-include-example.yaml"></a>

```
Resources:
  MyWaitHandle:
    Type: AWS::CloudFormation::WaitConditionHandle
  Fn::Transform:
    Name: AWS::Include
    Parameters:
      Location: "s3://amzn-s3-demo-bucket/single_wait_condition.yaml"
```

如需詳細資訊，請參閱《AWS CloudFormation 使用者指南》**中的[在 CloudFormation 範本中建立等待條件](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-waitcondition.html)。