本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# Amazon SNS 支援的自訂資源
本主題說明如何為自訂資源設定服務字符，該服務字符會指定 CloudFormation 傳送請求的 Amazon SNS 主題。您也會了解自訂資源堆疊建立、更新和刪除所產生的事件順序，以及傳送和接收的訊息。
您可以使用自訂資源和 Amazon SNS 來啟用案例，例如將新資源新增至堆疊，並將動態資料插入堆疊。例如，當您建立堆疊時，CloudFormation 可以將 `Create` 請求傳送到應用程式 (執行於 Amazon EC2 執行個體上) 監控的主題。Amazon SNS 通知會觸發應用程式執行額外的佈建任務，例如擷取列入允許清單的彈性 IP 地址集區。完成之後，應用程式會傳送回應 (以及任何輸出資料)，以通知 CloudFormation 繼續堆疊操作。
若您指定 Amazon SNS 主題作為自訂資源的目標，CloudFormation 會在涉及該自訂資源的堆疊操作期間，向指定的 SNS 主題傳送訊息。若要處理這些訊息並執行必要的操作，您必須有支援的端點訂閱該 SNS 主題。
有關自訂資源的簡介及其運作方式，請參閱 [自訂資源的運作方式](template-custom-resources.md#how-custom-resources-work)。如需 Amazon SNS 及其運作方式的資訊，請參閱 [Amazon Simple Notification Service 開發人員指南](https://docs.aws.amazon.com/sns/latest/dg/)。
## 使用 Amazon SNS 建立自訂資源
**Topics**
+ [步驟 1：建立堆疊](#crpg-walkthrough-stack-creation)
+ [步驟 2：更新堆疊](#crpg-walkthrough-stack-updates)
+ [步驟 3：刪除堆疊](#crpg-walkthrough-stack-deletion)
### 步驟 1：建立堆疊
1. 範本開發人員會建立包含自訂資源的 CloudFormation 堆疊。
下列範例範本中，我們為邏輯 ID 為 `MySeleniumTest` 的自訂資源使用自訂資源類型名稱 `Custom::SeleniumTester`。自訂資源類型名稱必須是英數字元，長度上限為 60 個字元。
自訂資源類型的宣告是使用服務字符、選用的提供者特定屬性，以及選用的 [Fn::GetAtt](resources-section-structure.md#resource-properties-getatt) 屬性 (由自訂資源提供者定義)。這些屬性可用來將資訊從範本開發人員傳遞到自訂資源提供者 (反之亦然)。服務字符會指定資源提供者已設定的 Amazon SNS 主題。
```
{
"AWSTemplateFormatVersion" : "2010-09-09",
"Resources" : {
"MySeleniumTest" : {
"Type": "Custom::SeleniumTester",
"Version" : "1.0",
"Properties" : {
"ServiceToken": "arn:aws:sns:us-west-2:123456789012:CRTest",
"seleniumTester" : "SeleniumTest()",
"endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com" ],
"frequencyOfTestsPerHour" : [ "3", "2", "4" ]
}
}
},
"Outputs" : {
"topItem" : {
"Value" : { "Fn::GetAtt" : ["MySeleniumTest", "resultsPage"] }
},
"numRespondents" : {
"Value" : { "Fn::GetAtt" : ["MySeleniumTest", "lastUpdate"] }
}
}
}
```
**注意**
在提供者回應 CloudFormation 期間，自訂資源提供者會傳回以 `Fn::GetAtt` 存取的資料名稱和值。如果custom resource provider是第三方，則範本開發人員必須從自訂資源提供者取得這些傳回值的名稱。
1. CloudFormation 會使用 `"RequestType" : "Create"` 將 Amazon SNS 通知傳送給資源提供者，其中包含堆疊的相關資訊、堆疊範本的自訂資源屬性，以及回應的 S3 URL。
`ServiceToken` 屬性中的範本內嵌了用來傳送通知的 SNS 主題。為避免使用硬式編碼的值，範本開發人員可以使用範本參數，在啟動堆疊時輸入值。
以下範例顯示自訂資源 `Create` 請求，其中包括使用 `Custom::SeleniumTester` 的 `LogicalResourceId` 所建立的自訂資源類型名稱 `MySeleniumTester`：
```
{
"RequestType" : "Create",
"RequestId" : "unique-request-id",
"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::SeleniumTester",
"LogicalResourceId" : "MySeleniumTester",
"ResourceProperties" : {
"seleniumTester" : "SeleniumTest()",
"endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com" ],
"frequencyOfTestsPerHour" : [ "3", "2", "4" ]
}
}
```
如需 `Create` 請求之請求物件的詳細資訊，請參閱 [請求和回應參考](crpg-ref.md)主題。
1. 自訂資源提供者會處理範本開發人員傳送的資料，並判斷 `Create` 請求是否成功。接著，資源提供者會使用 CloudFormation 傳送的 S3 URL 來傳送 `SUCCESS` 或 `FAILED` 的回應。
CloudFormation 預期的回應欄位根據回應類型而異。如需特定請求類型的回應欄位資訊，請參閱 [請求和回應參考](crpg-ref.md) 區段中該請求類型的文件。
在回應建立或更新請求時，自訂資源提供者可傳回回應 `Data` 欄位中的資料元素。這些是名稱值對；*名稱*對應至 `Fn::GetAtt` 屬性，其與堆疊範本中的自訂資源搭配使用。*值*是範本開發人員以屬性名稱在資源上呼叫 `Fn::GetAtt` 時傳回的資料。
以下為自訂資源回應的範例：
```
{
"Status" : "SUCCESS",
"RequestId" : "unique-request-id",
"StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10",
"LogicalResourceId" : "MySeleniumTester",
"PhysicalResourceId" : "Tester1",
"Data" : {
"resultsPage" : "http://www.myexampledomain/test-results/guid",
"lastUpdate" : "2012-11-14T03:30Z"
}
}
```
如需 `Create` 請求之回應物件的詳細資訊，請參閱 [請求和回應參考](crpg-ref.md)主題。
`StackId`、`RequestId` 以及 `LogicalResourceId` 欄位必須從請求逐字複製。
1. CloudFormation 會將堆疊狀態宣告為 `CREATE_COMPLETE` 或 `CREATE_FAILED`。如果已成功建立堆疊，範本開發人員可透過 [Fn::GetAtt](resources-section-structure.md#resource-properties-getatt) 來存取利用所建立自訂資源的輸出值。
例如，示範的自訂資源範本會使用 `Fn::GetAtt` 將資源輸出複製到堆疊輸出中：
```
"Outputs" : {
"topItem" : {
"Value" : { "Fn::GetAtt" : ["MySeleniumTest", "resultsPage"] }
},
"numRespondents" : {
"Value" : { "Fn::GetAtt" : ["MySeleniumTest", "lastUpdate"] }
}
}
```
### 步驟 2：更新堆疊
若要更新現有堆疊，您必須提交範本以指定堆疊中的資源屬性更新，如以下範例所示。CloudFormation 只會更新含範本中指定變更的資源。如需詳細資訊，請參閱[了解更新堆疊資源的行為](using-cfn-updating-stacks-update-behaviors.md)。
您可以更新需要替換基礎實體資源的自訂資源。當您更新 CloudFormation 範本中的自訂資源時，CloudFormation 會將更新請求傳送給該自訂資源。若需替換自訂資源，新的自訂資源必須以新的實體 ID 傳送回應。CloudFormation 接收回應時，會比較新舊自訂資源的 `PhysicalResourceId`。如果不同，CloudFormation 會將更新視為取代，並將刪除請求傳送到舊資源，如[步驟 3：刪除堆疊](#crpg-walkthrough-stack-deletion)所示。
**注意**
如果您未變更自訂資源，CloudFormation 就不會在堆疊更新期間傳送請求給自訂資源。
1. 範本開發人員可啟動包含自訂資源的堆疊更新。在更新期間，範本開發人員可以指定堆疊範本中的新 Properties (屬性)。
以下是使用自訂資源類型的堆疊範本 `Update` 範例：
```
{
"AWSTemplateFormatVersion" : "2010-09-09",
"Resources" : {
"MySeleniumTest" : {
"Type": "Custom::SeleniumTester",
"Version" : "1.0",
"Properties" : {
"ServiceToken": "arn:aws:sns:us-west-2:123456789012:CRTest",
"seleniumTester" : "SeleniumTest()",
"endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com",
"http://mynewsite.com" ],
"frequencyOfTestsPerHour" : [ "3", "2", "4", "3" ]
}
}
},
"Outputs" : {
"topItem" : {
"Value" : { "Fn::GetAtt" : ["MySeleniumTest", "resultsPage"] }
},
"numRespondents" : {
"Value" : { "Fn::GetAtt" : ["MySeleniumTest", "lastUpdate"] }
}
}
}
```
1. CloudFormation 會使用 `"RequestType" : "Update"` 將 Amazon SNS 通知傳送給資源提供者，其中包含類似於 `Create` 呼叫的資訊，差別在於 `OldResourceProperties` 欄位包含舊資源屬性，而 ResourceProperties 包含更新的資源屬性 (如果有)。
以下是 `Update` 請求範例：
```
{
"RequestType" : "Update",
"RequestId" : "unique-request-id",
"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::SeleniumTester",
"LogicalResourceId" : "MySeleniumTester",
"PhysicalResourceId" : "Tester1",
"ResourceProperties" : {
"seleniumTester" : "SeleniumTest()",
"endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com",
"http://mynewsite.com" ],
"frequencyOfTestsPerHour" : [ "3", "2", "4", "3" ]
},
"OldResourceProperties" : {
"seleniumTester" : "SeleniumTest()",
"endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com" ],
"frequencyOfTestsPerHour" : [ "3", "2", "4" ]
}
}
```
如需 `Update` 請求之請求物件的詳細資訊，請參閱 [請求和回應參考](crpg-ref.md)主題。
1. 自訂資源提供者會處理 CloudFormation 傳送的資料。自訂資源會執行更新並傳送 `SUCCESS` 或 `FAILED` 的回應給 S3 URL。然後，CloudFormation 會比較新舊自訂資源的 `PhysicalResourceIDs`。若其不同，CloudFormation 會將該更新視為需要替換，並傳送刪除請求給舊資源。以下範例示範custom resource provider對 `Update` 請求的回應。
```
{
"Status" : "SUCCESS",
"RequestId" : "unique-request-id",
"StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10",
"LogicalResourceId" : "MySeleniumTester",
"PhysicalResourceId" : "Tester2"
}
```
如需 `Update` 請求之回應物件的詳細資訊，請參閱 [請求和回應參考](crpg-ref.md)主題。
`StackId`、`RequestId` 以及 `LogicalResourceId` 欄位必須從請求逐字複製。
1. CloudFormation 會將堆疊狀態宣告為 `UPDATE_COMPLETE` 或 `UPDATE_FAILED`。如果更新失敗，即會復原堆疊。如果已成功更新堆疊，範本開發人員即可使用 `Fn::GetAtt` 來存取已建立之自訂資源的任何新輸出值。
### 步驟 3：刪除堆疊
1. 範本開發人員可刪除包含自訂資源的堆疊。CloudFormation 可取得堆疊範本中指定的目前屬性與 SNS 主題，並準備向自訂資源提供者發出請求。
1. CloudFormation 會使用 `"RequestType" : "Delete"` 將 Amazon SNS 通知傳送給資源提供者，其中包含堆疊的目前資訊、堆疊範本的自訂資源屬性，以及回應的 S3 URL。
每當您刪除堆疊，或更新堆疊以移除或取代自訂資源時，CloudFormation 會比較新舊自訂資源的 `PhysicalResourceId`。如果不同，CloudFormation 會將更新視為取代，並針對舊資源 (`OldPhysicalResource`) 傳送刪除請求，如下列 `Delete` 請求範例所示。
```
{
"RequestType" : "Delete",
"RequestId" : "unique-request-id",
"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::SeleniumTester",
"LogicalResourceId" : "MySeleniumTester",
"PhysicalResourceId" : "Tester1",
"ResourceProperties" : {
"seleniumTester" : "SeleniumTest()",
"endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com",
"http://mynewsite.com" ],
"frequencyOfTestsPerHour" : [ "3", "2", "4", "3" ]
}
}
```
如需 `Delete` 請求之請求物件的詳細資訊，請參閱 [請求和回應參考](crpg-ref.md)主題。
`DescribeStackResource`、`DescribeStackResources` 以及 `ListStackResources` 會顯示使用者定義的名稱 (如有指定)。
1. 自訂資源提供者會處理 CloudFormation 傳送的資料，並判斷 `Delete` 請求是否成功。接著，資源提供者會使用 CloudFormation 傳送的 S3 URL 來傳送 `SUCCESS` 或 `FAILED` 的回應。若要成功刪除含自訂資源的堆疊，custom resource provider 必須成功回應刪除請求。
以下為 custom resource provider對 `Delete` 請求的回應範例：
```
{
"Status" : "SUCCESS",
"RequestId" : "unique-request-id",
"StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/5b918d10-cd98-11ea-90d5-0a9cd3354c10",
"LogicalResourceId" : "MySeleniumTester",
"PhysicalResourceId" : "Tester1"
}
```
如需 `Delete` 請求之回應物件的詳細資訊，請參閱 [請求和回應參考](crpg-ref.md)主題。
`StackId`、`RequestId` 以及 `LogicalResourceId` 欄位必須從請求逐字複製。
1. CloudFormation 會將堆疊狀態宣告為 `DELETE_COMPLETE` 或 `DELETE_FAILED`。