Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

使用 Amazon CloudFormation 宏对模板执行自定义处理

通过使用宏，您可以对模板执行自定义处理，包括查找并替换操作等简单操作以及整个模板的大型转换。

要了解可能性的广度，请考虑 AWS::Include 和 AWS::Serverless 转换，它们是由 Amazon CloudFormation 托管的宏：

Amazon CloudFormation 宏的工作原理

使用宏处理模板有两个主要步骤：创建宏本身，然后使用宏来对模板执行处理。

要创建宏定义，您需要创建以下内容：

要使用宏，请在您的模板中引用宏：

接下来，您通常会创建一个更改集，然后执行它。（处理宏可添加您可能不知道的多个资源。为确保您了解宏所引入的所有更改，我们强烈建议您使用更改集。）Amazon CloudFormation 将指定的模板内容以及任何其他指定的参数一并传递给在宏资源中指定的 Lambda 函数。Lambda 函数返回已处理的模板内容，无论是代码段还是整个模板。

在调用模板中的所有宏之后，Amazon CloudFormation 会生成包含已处理模板内容的更改集。检查更改集后，执行它来应用更改。

创建 Amazon CloudFormation 宏定义

当您创建宏定义时，该宏定义使底层 Lambda 函数在指定的账户中可用，以便 Amazon CloudFormation 可以调用它来处理模板。

Amazon CloudFormation 宏函数接口

对于宏，Amazon CloudFormation 使用以下事件映射调用底层 Lambda 函数。Amazon CloudFormation 以 JSON 格式发送请求，并且它希望函数响应也被格式化为 JSON。

{
    "region" : "us-east-1",
    "accountId" : "$ACCOUNT_ID",
    "fragment" : { ... },
    "transformId" : "$TRANSFORM_ID",
    "params" : { ... },
    "requestId" : "$REQUEST_ID",
    "templateParameterValues" : { ... }
}

Amazon CloudFormation 预计底层函数以以下 JSON 格式返回响应：

{
    "requestId" : "$REQUEST_ID",
    "status" : "$STATUS",
    "fragment" : { ... }
    "errorMessage": "optional error message for failures"
}

有关在创建宏时的其他注意事项的信息，请参阅创建 Amazon CloudFormation 宏定义时的注意事项。

Amazon CloudFormation 宏账户范围和权限

您只能在创建宏的账户中将宏用作资源。宏的名称在给定账户中必须是唯一的。但是，您可以通过在底层 Lambda 函数上启用跨账户访问，然后创建宏定义以在多个账户中引用该函数，从而在多个账户中提供相同的功能。在下面的示例中，三个账户包含宏定义，每个宏定义都指向相同的 Lambda 函数。

有关更多信息，请参阅《Amazon Lambda 开发人员指南》中的管理您的 Amazon Lambda 资源的访问权限概述。

要创建宏定义，用户必须具有在指定账户中创建堆栈或堆栈集的权限。

为了使 Amazon CloudFormation 成功运行模板中包含的宏，用户必须对底层 Lambda 函数具有 Invoke 权限。为了防止可能的权限升级，Amazon CloudFormation 会在运行宏时模拟用户。有关更多信息，请参阅《Amazon Lambda 开发人员指南》中的 Lambda 权限模型和《IAM 用户指南》中的 Amazon Lambda 的操作和条件上下文键。

AWS::Serverless 转换 和 AWS::Include 转换 转换是由 Amazon CloudFormation 托管的宏。使用它们不需要特殊权限，并且可以从 Amazon CloudFormation 内的任何账户中获得它们。

调试 Amazon CloudFormation 宏

为了帮助调试，您还可以在为宏创建 AWS::CloudFormation::Macro 资源类型时指定 LogGroupName 和 LogRoleArn 属性。通过这些属性，您可以指定 Amazon CloudFormation 在调用宏的底层 Amazon Lambda 函数时向其发送错误日志记录信息的 CloudWatch 日志组，以及 Amazon CloudFormation 在将日志条目发送到这些日志时应该担任的角色。

Billing

当宏运行时，将对 Lambda 函数的所有者收取与执行该函数相关的任何费用。

AWS::Serverless 转换 和 AWS::Include 转换 转换是由 Amazon CloudFormation 托管的宏。使用它们不产生任何费用。

创建 Amazon CloudFormation 宏定义时的注意事项

在创建宏定义时，请记住以下几点：

在模板中使用 Amazon CloudFormation 宏

在 Amazon CloudFormation 成功创建包含宏定义的堆栈之后，该宏便可在这些账户中使用。您可以通过在模板中，在与要处理的模板内容相关的适当位置引用宏来使用宏。

Amazon CloudFormation 宏评估顺序

您可以在给定模板中引用多个宏，包括由 Amazon CloudFormation 托管的转换，例如 AWS::Include 转换 和 AWS::Serverless 转换。

将会根据宏在模板中的位置，从嵌套最深的宏向外直到最一般的宏，按顺序评估宏。对于模板中相同位置的宏，将会根据列出的顺序按顺序进行评估。

诸如 AWS::Include 和 AWS::Transform 之类的转换在操作顺序和范围方面被视为与任何其他宏相同。

例如，在下面的模板示例中，Amazon CloudFormation 首先评估 PolicyAdder 宏，因为它是模板中嵌套最深的宏。然后，Amazon CloudFormation 在评估 AWS::Serverless 之前评估 MyMacro，因为它在 Transform 部分中在 AWS::Serverless 之前列出。

AWSTemplateFormatVersion: 2010-09-09
 Transform: [MyMacro, AWS::Serverless]
 Resources:
    WaitCondition:
      Type: AWS::CloudFormation::WaitCondition
    MyBucket:
      Type: 'AWS::S3::Bucket'
      Properties:
        BucketName: MyBucket
        Tags: [{"key":"value"}]
        'Fn::Transform':
          - Name: PolicyAdder
        CorsConfiguration:[]
    MyEc2Instance:
      Type: 'AWS::EC2::Instance'
      Properties:
        ImageID: "ami-123"

Amazon CloudFormation 宏范围

在模板的 Transform 部分中引用的宏可以处理该模板的全部内容。

在 Fn::Transform 函数中引用的宏可以处理模板中该 Fn::Transform 函数的任何同级元素（包括子元素）的内容。

例如，在下面的模板示例中，AWS::Include 可以根据包含它的 Fn::Transform 函数的位置处理 MyBucket 属性。MyMacro 可以处理整个模板的内容，因为它包含在 Transform 部分中。

// Start of processable content for MyMacro
AWSTemplateFormatVersion: 2010-09-09 
 Transform: [MyMacro]
 Resources:
    WaitCondition:
      Type: AWS::CloudFormation::WaitCondition
    MyBucket:
      Type: 'AWS::S3::Bucket'  //Start of processable content for AWS::Include
      Properties:
        BucketName: MyBucket 
        Tags: [{"key":"value"}] 
        'Fn::Transform':
          - Name: 'AWS::Include'
              Parameters:
                Location: s3://DOC-EXAMPLE-BUCKET/MyFileName.yaml
        CorsConfiguration:[]   //End of processable content for AWS::Include
    MyEc2Instance:
      Type: 'AWS::EC2::Instance' 
      Properties:
        ImageID: "ami-123"
// End of processable content for MyMacro         

更改集和 Amazon CloudFormation 宏

要使用引用宏的模板创建或更新堆栈，通常需要创建一个更改集，然后执行它。更改集描述 CloudFormation 将基于处理后的模板执行的操作。处理宏可添加您可能不知道的多个资源。为确保您已了解宏所引入的所有更改，我们强烈建议您使用更改集。在查看更改集后，您可以执行它来实际应用更改。

宏可以将 IAM 资源添加到您的模板中。对于这些资源，Amazon CloudFormation 要求您确认其功能。由于 Amazon CloudFormation 无法在处理模板前了解所添加的资源，因此您可能需要在创建更改集时确认 IAM 功能，具体取决于引用的宏是否包含 IAM 资源。这样一来，当您运行更改集时，Amazon CloudFormation 会具有创建 IAM 资源所需的功能。

如果您使用 Amazon CLI，则可使用 package 和 deploy 命令减少从引用宏的模板启动堆栈的步骤数。有关更多信息，请参阅《Amazon Lambda 开发人员指南》中的部署基于 Lambda 的应用程序。

模板阶段和 CloudFormation 宏

模板的阶段指示模板是原始用户提交的模板还是 Amazon CloudFormation 已在其中处理宏的模板。

使用处理后的模板可解决堆栈问题。如果模板不引用宏，则原始模板和已处理模板是相同的。

您可以使用 Amazon CloudFormation 控制台或 Amazon CLI 查看堆栈模板的阶段。

宏示例

除了本指南中的 宏示例：创建和使用宏 演练之外，您还可以在 GitHub 上的 Amazon Web Services - Labs（亚马逊云科技 - 实验室）存储库的 Macros Examples（宏示例）部分中找到示例宏，包括源代码和模板。这些示例按“原样”提供，用于教学目的。

另请参阅

AWS::CloudFormation::Macro

转换

Fn::Transform

AWS::Serverless 转换

AWS::Include 转换