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

# 使用自訂資源建立自訂佈建邏輯
<a name="template-custom-resources"></a>

自訂資源可讓您能在 CloudFormation 範本中撰寫自訂佈建邏輯，讓 CloudFormation 可在您建立、更新 (若您變更自訂資源) 或刪除堆疊時隨時執行。當您的佈建需求涉及無法以 CloudFormation 內建資源類型表示的複雜邏輯或工作流程時，這會很實用。

例如，您可能會希望包含無法做為 CloudFormation 資源類型使用的資源。您可以使用自訂資源包含那些資源。以此方式，您仍然可以在單一堆疊中管理所有相關資源。

在 CloudFormation 範本中，您可以使用 `AWS::CloudFormation::CustomResource` 或 `Custom::MyCustomResourceTypeName` 資源類型來定義自訂資源。自訂資源需要一個屬性：服務字符，指定 CloudFormation 傳送請求的目的地，例如 Amazon SNS 主題或 Lambda 函式。

下列主題提供有關如何使用自訂資源的資訊：

**Topics**
+ [自訂資源的運作方式](#how-custom-resources-work)
+ [回應逾時](#response-timeout)
+ [CloudFormation 自訂資源請求和回應參考](crpg-ref.md)
+ [Amazon SNS 支援的自訂資源](template-custom-resources-sns.md)
+ [Lambda 後端自訂資源](template-custom-resources-lambda.md)

**注意**  
CloudFormation 登錄檔與自訂資源各有其優點。自訂資源提供下列優點：  
您無需註冊資源。
您可在範本中包含整個資源，而無需註冊。
支援 `Create`、`Update` 和 `Delete` 操作
登錄檔型資源所提供的優點包括如下：  
支援建模、佈建和管理第三方應用程式資源
支援 `Create`、`Read`、`Update` `Delete`、和 `List` (`CRUDL`) 操作
支援私有和第三方資源類型的偏移偵測
與自訂資源不同，以登錄為基礎的資源不需要關聯 Amazon SNS 主題或 Lambda 函數來執行 `CRUDL` 操作。如需詳細資訊，請參閱[使用 CloudFormation 登錄檔管理擴充功能](registry.md)。

## 自訂資源的運作方式
<a name="how-custom-resources-work"></a>

設定新自訂資源的一般程序包括下列步驟。這些步驟涉及兩個角色：擁有自訂資源的*自訂資源提供者*，以及建立包含自訂資源類型範本的*開發人員*。這可以是同一個人，但若不是，自訂資源提供者應與範本開發人員協作。

1. 自訂資源提供者會撰寫邏輯，用於決定如何處理來自 CloudFormation 的請求，以及對自訂資源執行相應操作。

1. 自訂資源提供者會建立 Amazon SNS 主題或 Lambda 函式，供 CloudFormation 傳送請求。Amazon SNS 主題或 Lambda 函式必須位於即將建立堆疊的同一區域。

1. 自訂資源提供者會將 Amazon SNS 主題 ARN 或 Lambda 函式 ARN 提供給範本開發人員。

1. 範本開發人員在 CloudFormation 範本中定義自訂資源。其中包含服務字符和任何輸入資料參數。輸入資料的服務字符和結構由自訂資源提供者定義。服務字符會指定 Amazon SNS 主題 ARN 或 Lambda 函式 ARN，且為必要項目，但輸入資料是否需要則取決於自訂資源。

現在，每當任何人使用範本來建立、更新或刪除自訂資源時，CloudFormation 都會向指定的服務字符傳送請求，並等待回應後再繼續執行堆疊操作。

以下是從範本建立堆疊的流程總結：

1. CloudFormation 向指定的服務字符傳送請求。請求包含請求類型和預先簽章的 Amazon S3 儲存貯體 URL 等資訊，自訂資源會將回應傳送到其中。如需請求中包含項目的詳細資訊，請參閱 [CloudFormation 自訂資源請求和回應參考](crpg-ref.md)。

   以下範例資料顯示 CloudFormation 在 `Create` 請求中包含的項目：在此範例中，`ResourceProperties` 可讓 CloudFormation 建立自訂承載，以傳送至 Lambda 函式。

   ```
   {
      "RequestType" : "Create",
      "RequestId" : "unique id for this create request",
      "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10",
      "ResponseURL" : "http://pre-signed-S3-url-for-response",
      "ResourceType" : "Custom::TestResource",
      "LogicalResourceId" : "MyTestResource",
      "ResourceProperties" : {
         "Name" : "Value",
         "List" : [ "1", "2", "3" ]
      }
   }
   ```

1. 自訂資源提供者會處理 CloudFormation 請求，並將 `SUCCESS` 或 `FAILED` 的回應傳送至預先簽章的 URL。custom resource provider 會以 JSON 格式檔案提供回應，並上傳至預先簽章的 S3 URL。如需詳細資訊，請參閱《*Amazon Simple Storage Service 使用者指南*》中的[使用預先簽章的 URL 上傳物件](https://docs.aws.amazon.com/AmazonS3/latest/userguide/PresignedUrlUploadObject.html)。

   在回應中，自訂資源提供者也可包含範本開發人員可存取的名稱值對。例如，若請求成功，回應可包含輸出資料，或是若請求失敗，則包含錯誤訊息。如需回應的詳細資訊，請參閱 [CloudFormation 自訂資源請求和回應參考](crpg-ref.md)。
**重要**  
如果名稱值對包含敏感資訊，您應該使用 `NoEcho` 欄位來遮罩自訂資源的輸出。否則，這些值可透過表示屬性值 (例如 `DescribeStackEvents`) 的 API 可見。  
如需使用 `NoEcho` 遮罩敏感資訊的詳細資訊，請參閱 [請勿在您的範本中內嵌憑證](security-best-practices.md#creds) 最佳實務。

   custom resource provider 負責接聽和回應請求。例如，針對 Amazon SNS 通知，自訂資源提供者必須接聽和回應傳送到特定主題 ARN 的通知。CloudFormation 會在預先簽章的 URL 位置等待並接聽回應。

   以下範例資料顯示回應中可能包含的自訂資源：

   ```
   {
      "Status" : "SUCCESS",
      "RequestId" : "unique id for this create request",
      "StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10",
      "LogicalResourceId" : "MyTestResource",
      "PhysicalResourceId" : "TestResource1",
      "Data" : {
         "OutputName1" : "Value1",
         "OutputName2" : "Value2",
      }
   }
   ```

1. 在取得 `SUCCESS` 回應後，CloudFormation 便會繼續堆疊操作。若傳回 `FAILED` 回應或沒有任何回應，則操作便會失敗。任何來自自訂資源的輸出資料都會存放在預先簽章的 URL 位置。範本開發人員可使用 [Fn::GetAtt](resources-section-structure.md#resource-properties-getatt) 函數擷取該資料。

**注意**  
如果您使用 AWS PrivateLink，VPC 中的自訂資源必須能夠存取 CloudFormation 特定的 S3 儲存貯體。自訂資源必須傳送回應至預先簽章的 Amazon S3 URL。若無法將回應傳送至 Amazon S3，CloudFormation 便不會收到回應，而堆疊操作則會失敗。如需詳細資訊，請參閱[CloudFormation 使用界面端點存取 (AWS PrivateLink)](vpc-interface-endpoints.md)。

## 回應逾時
<a name="response-timeout"></a>

自訂資源的預設逾時為 3600 秒 (1 小時)。如果在這段時間內沒有收到任何回應，堆疊操作就會失敗。

您可根據預期自訂資源傳回回應的時間，調整逾時數值。例如，若佈建的自訂資源會調用預期在五分鐘內回應的 Lambda 函式，您可在堆疊範本中透過指定 `ServiceTimeout` 屬性，將逾時時間設定為五分鐘。如需詳細資訊，請參閱[CloudFormation 自訂資源請求和回應參考](crpg-ref.md)。如此一來，若 Lambda 函式發生錯誤導致卡住，CloudFormation 會在五分鐘後使堆疊操作失敗，而非等待完整的一小時。

但請注意，勿將逾時數值設定過低。為避免非預期的逾時，請確保您的自訂資源有足夠時間執行必要動作並傳回回應。