这是新的《CloudFormation 模板参考指南》**。请更新您的书签和链接。有关开始使用 CloudFormation 的帮助，请参阅《AWS CloudFormation 用户指南》[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html](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` 指令。

## 用法
<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)。

### 参数
<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* 替换为实际存储桶名称。

首先，在您的 S3 存储桶中保存一个名为 `single_wait_condition.yaml` 的 YAML 文件，其中应包含以下内容：

```
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)**。