Amazon SNS 支援的自訂資源

本主題說明如何為自訂資源設定服務字符，該服務字符會指定 CloudFormation 傳送請求的 Amazon SNS 主題。您也會了解自訂資源堆疊建立、更新和刪除所產生的事件順序，以及傳送和接收的訊息。

您可以使用自訂資源和 Amazon SNS 來啟用案例，例如將新資源新增至堆疊，並將動態資料插入堆疊。例如，當您建立堆疊時，CloudFormation 可以將 Create 請求傳送到應用程式 (執行於 Amazon EC2 執行個體上) 監控的主題。Amazon SNS 通知會觸發應用程式執行額外的佈建任務，例如擷取列入允許清單的彈性 IP 地址集區。完成之後，應用程式會傳送回應 (以及任何輸出資料)，以通知 CloudFormation 繼續堆疊操作。

若您指定 Amazon SNS 主題作為自訂資源的目標，CloudFormation 會在涉及該自訂資源的堆疊操作期間，向指定的 SNS 主題傳送訊息。若要處理這些訊息並執行必要的操作，您必須有支援的端點訂閱該 SNS 主題。

有關自訂資源的簡介及其運作方式，請參閱自訂資源的運作方式。如需 Amazon SNS 及其運作方式的資訊，請參閱 Amazon Simple Notification Service 開發人員指南。

步驟 1：建立堆疊

範本開發人員會建立包含自訂資源的 CloudFormation 堆疊。

下列範例範本中，我們為邏輯 ID 為 MySeleniumTest 的自訂資源使用自訂資源類型名稱 Custom::SeleniumTester。自訂資源類型名稱必須是英數字元，長度上限為 60 個字元。

自訂資源類型的宣告是使用服務字符、選用的提供者特定屬性，以及選用的 Fn::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是第三方，則範本開發人員必須從自訂資源提供者取得這些傳回值的名稱。
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 請求之請求物件的詳細資訊，請參閱請求和回應參考主題。
自訂資源提供者會處理範本開發人員傳送的資料，並判斷 Create 請求是否成功。接著，資源提供者會使用 CloudFormation 傳送的 S3 URL 來傳送 SUCCESS 或 FAILED 的回應。

CloudFormation 預期的回應欄位根據回應類型而異。如需特定請求類型的回應欄位資訊，請參閱請求和回應參考區段中該請求類型的文件。

在回應建立或更新請求時，自訂資源提供者可傳回回應 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 請求之回應物件的詳細資訊，請參閱請求和回應參考主題。

StackId、RequestId 以及 LogicalResourceId 欄位必須從請求逐字複製。
CloudFormation 會將堆疊狀態宣告為 CREATE_COMPLETE 或 CREATE_FAILED。如果已成功建立堆疊，範本開發人員可透過 Fn::GetAtt 來存取利用所建立自訂資源的輸出值。

例如，示範的自訂資源範本會使用 Fn::GetAtt 將資源輸出複製到堆疊輸出中：
```
"Outputs" : {
   "topItem" : {
      "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "resultsPage"] }
   },
   "numRespondents" : {
      "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "lastUpdate"] }
   }
}
```

步驟 2：更新堆疊

若要更新現有堆疊，您必須提交範本以指定堆疊中的資源屬性更新，如以下範例所示。CloudFormation 只會更新含範本中指定變更的資源。如需詳細資訊，請參閱了解更新堆疊資源的行為。

您可以更新需要替換基礎實體資源的自訂資源。當您更新 CloudFormation 範本中的自訂資源時，CloudFormation 會將更新請求傳送給該自訂資源。若需替換自訂資源，新的自訂資源必須以新的實體 ID 傳送回應。CloudFormation 接收回應時，會比較新舊自訂資源的 PhysicalResourceId。如果不同，CloudFormation 會將更新視為取代，並將刪除請求傳送到舊資源，如步驟 3：刪除堆疊所示。

注意

如果您未變更自訂資源，CloudFormation 就不會在堆疊更新期間傳送請求給自訂資源。

範本開發人員可啟動包含自訂資源的堆疊更新。在更新期間，範本開發人員可以指定堆疊範本中的新 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"] }
      }
   }
}

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 請求之請求物件的詳細資訊，請參閱請求和回應參考主題。

自訂資源提供者會處理 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 請求之回應物件的詳細資訊，請參閱請求和回應參考主題。

StackId、RequestId 以及 LogicalResourceId 欄位必須從請求逐字複製。
CloudFormation 會將堆疊狀態宣告為 UPDATE_COMPLETE 或 UPDATE_FAILED。如果更新失敗，即會復原堆疊。如果已成功更新堆疊，範本開發人員即可使用 Fn::GetAtt 來存取已建立之自訂資源的任何新輸出值。

步驟 3：刪除堆疊

範本開發人員可刪除包含自訂資源的堆疊。CloudFormation 可取得堆疊範本中指定的目前屬性與 SNS 主題，並準備向自訂資源提供者發出請求。
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 請求之請求物件的詳細資訊，請參閱請求和回應參考主題。

DescribeStackResource、DescribeStackResources 以及 ListStackResources 會顯示使用者定義的名稱 (如有指定)。
自訂資源提供者會處理 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 請求之回應物件的詳細資訊，請參閱請求和回應參考主題。

StackId、RequestId 以及 LogicalResourceId 欄位必須從請求逐字複製。
CloudFormation 會將堆疊狀態宣告為 DELETE_COMPLETE 或 DELETE_FAILED。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

請求和回應參考

Lambda 後端自訂資源

Amazon SNS 支援的自訂資源

使用 Amazon SNS 建立自訂資源

主題

步驟 1：建立堆疊

注意

步驟 2：更新堆疊

注意

步驟 3：刪除堆疊