本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# CloudFormation 巨集概觀
使用巨集處理範本有兩個主要步驟：建立巨集本身，然後使用巨集在您的範本上執行處理。
若要建立巨集定義，您必須建立下列項目：
+ 用來執行範本處理的 Lambda 函式。此 Lambda 函數接受程式碼片段或整個範本，以及您定義的任何其他參數。它會傳回已處理的範本程式碼片段或整個範本作為回應。
+ [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-cloudformation-macro.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-cloudformation-macro.html) 類型的資源，可讓使用者從 CloudFormation 範本內呼叫 Lambda 函式。此資源指定針對此巨集叫用的 Lambda 函數的 ARN，以及可協助除錯的其他選用屬性。若要在帳戶中建立此資源，請撰寫包含`AWS::CloudFormation::Macro`資源的範本，然後從範本建立具有自我管理許可的堆疊或堆疊集。 CloudFormation StackSets 目前不支援從參考巨集的範本建立或更新具有服務管理許可的堆疊集。
若要使用巨集，請在範本中參考巨集：
+ 若要處理範本的區段或部分，請在 `Fn::Transform` 函數 (位置相對於您想要轉換的範本內容) 中參考巨集。當您使用 `Fn::Transform` 時，您也可以傳遞它需要的任何指定參數。
+ 若要處理整個範本，請在範本的 [Transform](transform-section-structure.md) 區段中參考巨集。
接著，您通常會建立變更集，然後加以執行。(處理巨集可能會新增您不了解的多項資源。為了確保您知道巨集所產生的所有變更，我們強烈建議您使用變更集。) CloudFormation 會將指定的範本內容以及任何額外的指定參數，傳遞到巨集資源中指定的 Lambda 函式。Lambda 函數會傳回已處理的範本內容，不論是程式碼片段或整個範本。
所有巨集之後，CloudFormation 會產生已稱為在範本中變更設定，包含處理範本的內容。檢閱變更集之後，請執行它來套用變更。
## 如何直接建立堆疊
若要使用參考巨集的範本來建立或更新堆疊，您通常會建立變更集，然後執行它。變更集說明 CloudFormation 將根據處理過的範本所採取的動作。處理巨集可能會新增您不了解的多個資源。為了確保您知道巨集所產生的所有變更，我們強烈建議您使用變更集。檢閱變更集之後，您可以執行它來確實套用變更。
巨集可以將 IAM 資源新增至您的範本。針對這些資源，CloudFormation 會要求您[確認其功能](control-access-with-iam.md#using-iam-capabilities)。因為 CloudFormation 無法知道在處理範本之前新增哪些資源，所以您建立變更集時可能需要確認 IAM 功能 (視參考的巨集是否包含 IAM 資源而定)。因此，當您執行變更集時，CloudFormation 具有必要功能來建立 IAM 資源。
要透過處理範本建立或更新堆疊，無需先在變更集中審核建議的變更，可在 `CreateStack` 或 `UpdateStack` 請求期間指定 `CAPABILITY_AUTO_EXPAND` 功能。如果您知道巨集執行哪些處理，您應只直接透過包含巨集的堆疊範本來建立堆疊。您不能將變更集與堆疊集巨集一起使用；您必須直接更新堆疊集。
如需詳細資訊，請參閱《AWS CloudFormation API 參考》**中的 [https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html) 或 [https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_UpdateStack.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_UpdateStack.html)。
**重要**
如果您的堆疊集範本參考了一或多個巨集，您必須直接從處理的範本建立堆疊集，而不必先檢視變更集中產生的變更。處理巨集可能會新增您不了解的多個資源。從直接參考巨集的範本建立或更新堆疊集之前，請確定您知道巨集會執行哪些處理操作。
若要減少從參考巨集的範本啟動堆疊的步驟數目，您可以使用 `package`和 `deploy` AWS CLI 命令。如需詳細資訊，請參閱[使用 將本機成品上傳至 S3 儲存貯體 AWS CLI](using-cfn-cli-package.md)及[建立包含轉換的堆疊](service_code_examples.md#deploy-sdk)。
## 考量事項
配合使用巨集時，請記住下列考量事項和限制：
+ 只有提供 Lambda AWS 區域 的 才支援巨集。如需可使用 Lambda 的區域清單，請參閱 [AWS Lambda 端點與配額](https://docs.aws.amazon.com/general/latest/gr/lambda-service.html)。
+ 任何處理的範本程式碼片段都必須是有效的 JSON。
+ 任何處理的範本程式碼片段都必須通過建立堆疊、更新堆疊、建立堆疊集或更新堆疊集操作的驗證檢查。
+ CloudFormation 會先解析巨集，再處理範本。產生的範本必須是有效的 JSON，且不能超過範本大小上限。
+ 由於 CloudFormation 處理範本中元素的順序，巨集無法將模組包含在傳回至 CloudFormation 的處理範本內容中。如需詳細資訊，請參閱[巨集評估順序](template-macros-author.md#template-macros-order)。
+ CloudFormation 會採用原始範本的副本來執行更新復原功能。即使加入的程式碼片段有所變更，它也會復原至原始範本。
+ 在巨集內包含巨集沒有作用，因為我們不會處理以遞迴方式處理巨集。
+ 巨集內目前不支援 `Fn::ImportValue` 內部函數。
+ 範本包含的內部函數是在任何巨集之後評估。因此，巨集傳回的已處理範本內容可能包含內部函數的呼叫，一樣照常評估。
+ StackSets 目前不支援從參考 CloudFormation 巨集的範本建立或更新具有服務受管許可的 StackSets。
## 巨集帳戶範圍和許可
巨集只能在它們已建立為資源的帳戶中使用。巨集的名稱在給定帳戶內必須是唯一的。不過，您可以在基礎 Lambda 函數上啟用跨帳戶存取，然後建立巨集定義在多個帳戶中參考該函數，就能讓多個帳戶使用相同的功能。在下列範例中，三個帳戶包含巨集定義，各指向相同的 Lambda 函數。
為了建立巨集定義，使用者必須有許可，才能在指定的帳戶內建立堆疊或堆疊集。
為了讓 CloudFormation 成功執行範本中包含的巨集，使用者必須有基礎 Lambda 函式的 `Invoke` 許可。為避免潛在提升許可，CloudFormation 會在執行巨集時模擬使用者。
如需詳細資訊，請參閱《AWS Lambda 開發人員指南**》中的[在 AWS Lambda中管理許可](https://docs.aws.amazon.com/lambda/latest/dg/lambda-permissions.html)，以及《服務授權參考**》中的 [AWS Lambda的動作、資源和條件索引鍵](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awslambda.html)。