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

使用範本巨集對 CloudFormation 範本執行自訂處理

巨集可讓您對範本執行自訂處理，從簡單的動作 (例如作 find-and-replace 業) 到整個範本的大量轉換。

要了解可能性的廣度，請考慮AWS::Include和AWS::Serverless轉換，它們是由 CloudFormation以下主控的宏：

CloudFormation 巨集的運作方式

使用巨集處理範本有兩個主要步驟：建立巨集本身，然後使用巨集在您的範本上執行處理。

若要建立巨集定義，您需要建立下列項目：

若要使用巨集，請在範本中參考巨集：

接著，您通常會建立變更集，然後加以執行。（處理宏可以添加多個您可能不知道的資源。 為了確保您知道巨集引入的所有變更，我們強烈建議您使用變更集。) CloudFormation 將指定的範本內容與任何其他指定的參數一起傳遞至巨集資源中指定的 Lambda 函數。Lambda 函數會傳回已處理的範本內容，不論是程式碼片段或整個範本。

呼叫樣板中的所有巨集之後， CloudFormation 會產生包含已處理範本內容的變更集。檢閱變更集之後，請執行它來套用變更。

建立 CloudFormation 巨集定義

當您建立巨集定義時，巨集定義會在指定的帳戶中使用基礎 Lambda 函數，以便 CloudFormation 叫用它來處理範本。

CloudFormation 宏功能界面

對於巨集，請使用下列事件對應 CloudFormation 來叫用基礎 Lambda 函數。 CloudFormation 以JSON格式發送其請求，並且它希望函數響應JSON也被格式化。

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

CloudFormation 預期基礎函數以下列JSON格式傳回回應：

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

如需建立巨集時其他考量的相關資訊，請參閱建立 CloudFormation 巨集定義時的考量。

CloudFormation 巨集帳戶範圍和權限

巨集只能在它們已建立為資源的帳戶中使用。巨集的名稱在給定帳戶內必須是唯一的。不過，您可以在基礎 Lambda 函數上啟用跨帳戶存取，然後建立巨集定義在多個帳戶中參考該函數，就能讓多個帳戶使用相同的功能。在下列範例中，三個帳戶包含巨集定義，各指向相同的 Lambda 函數。

如需詳細資訊，請參閱管理您的存取權限概觀 AWS中的 Lambda 資源 AWS Lambda 開發人員指南。

為了建立巨集定義，使用者必須有許可，才能在指定的帳戶內建立堆疊或堆疊集。

若 CloudFormation 要成功執行範本中包含的巨集，使用者必須擁有基礎 Lambda 函數的Invoke權限。若要防止潛在的權限提升，請在執行巨 CloudFormation 集時模擬使用者。如需詳細資訊，請參閱 AWS Lambda 開發人員指南和操作以及條件上下文鍵 AWS Lambda (在 IAM 使用者指南中)

AWS::Serverless 轉換程序和轉AWS::Include 轉換程序換是由主控的巨集 CloudFormation。不需要特殊權限即可使用它們，而且可以從中的任何帳戶中取得這些權限 CloudFormation。

偵錯 CloudFormation 巨集

為了協助除錯，當您為巨集建立 AWS::CloudFormation::Macro 資源類型時，您也可以指定 LogGroupName 和 LogRoleArn 屬性。這些內容可讓您指定在 CloudWatch 呼叫巨集的基礎資訊時， CloudFormation 將錯誤記錄資訊傳送至的記錄群組 AWS Lambda 功能，並且在將日誌條目發送到這些日誌時 CloudFormation 應該承擔角色。

帳單

當巨集執行時，Lambda 函數的擁有者需要支付執行該函數的任何相關費用。

AWS::Serverless 轉換程序和轉AWS::Include 轉換程序換是由主控的巨集 CloudFormation。可免費使用它們。

建立 CloudFormation 巨集定義時的考量

建立巨集定義時，請謹記下列事項：

在範本中使用 CloudFormation 巨集

CloudFormation 成功建立包含巨集定義的堆疊後，即可在這些帳戶中使用巨集。在範本中，請在您要處理的範本內容的相對適當位置上參考巨集，以此來使用巨集。

CloudFormation 巨集評估順序

您可以參考指定範本中的多個巨集，包括由主控的轉換 CloudFormation，例如AWS::Include 轉換程序和AWS::Serverless 轉換程序。

巨集是根據在範本中的位置而依序評估，從最深巢狀往外到最通用。範本中同一位置的巨集是根據它們所列順序而按順序評估。

在動作順序和範圍方面，轉換 (例如 AWS::Include 和 AWS::Transform) 與任何其他巨集視為相同。

例如，在以下範本範例中， CloudFormation 會先評估PolicyAdder巨集，因為它是範本中巢狀最深的巨集。 CloudFormation 然後在評估MyMacro之前進行評估，AWS::Serverless因為它AWS::Serverless在Transform部分之前列出。

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

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: amzn-s3-demo-bucket1
        Tags: [{"key":"value"}] 
        'Fn::Transform':
          - Name: 'AWS::Include'
              Parameters:
                Location: s3://amzn-s3-demo-bucket2/MyFileName.yaml
        CorsConfiguration: []
        # End of processable content for AWS::Include
    MyEc2Instance:
      Type: 'AWS::EC2::Instance' 
      Properties:
        ImageID: ami-1234567890abcdef0
# End of processable content for MyMacro

變更集合和 CloudFormation 巨集

若要使用參考巨集的範本來建立或更新堆疊，您通常會建立變更集，然後執行它。變更集描述 CloudFormation 將根據已處理的範本採取的動作。處理巨集可能會新增您不了解的多個資源。為了確保您知道巨集所產生的所有變更，我們強烈建議您使用變更集。檢閱變更集之後，您可以執行它來確實套用變更。

巨集可以將IAM資源新增至您的範本。對於這些資源， CloudFormation需要您確認其功能。由於在處理範本之前 CloudFormation 無法知道要新增哪些資源，因此您可能需要在建立變更集時確認IAM功能，具體取決於參考的巨集是否包含IAM資源。如此一來，當您執行變更集時，就 CloudFormation 具有建立IAM資源的必要功能。

如果您使用 AWS CLI，您可以使用package和deploy指令減少從參考巨集的範本啟動堆疊的步驟數。如需詳細資訊，請參閱部署以 Lambda 為基礎的應用程式 AWS Lambda 開發人員指南。

範本階段和 CloudFormation 巨集

範本的階段會指出範本是原始使用者提交的範本，還是 CloudFormation 已經處理巨集的範本。

使用處理過的範本針對堆疊問題進行故障診斷。如果範本未參考巨集，則原始範本和處理過的範本會相同。

您可以使用控 CloudFormation 制台或 AWS CLI查看堆棧模板的階段。

巨集範例

除了本指南中的巨集範例：建立和使用巨集逐步解說之外，您還可以在我們的GitHub 儲存庫中找到範例巨集，包括原始程式碼和範本。這些範例「按現狀」提供作為教學用途。

另請參閱

AWS::CloudFormation: 巨集

Transform

Fn::Transform

AWS::Serverless 轉換程序

AWS::Include 轉換程序