本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# CloudFormation 自訂資源請求和回應參考
CloudFormation 透過與您的自訂資源提供者通訊的請求回應通訊協定來管理自訂資源。每個請求都包含請求類型 (`Create`、 或 `Delete`)`Update`，並遵循此高階工作流程：
1. 範本開發人員在範本`ServiceTimeout`中定義具有 `ServiceToken`和 的自訂資源，並啟動堆疊操作。
1. CloudFormation 透過 SNS 或 Lambda 將 JSON 請求傳送至自訂資源提供者。
1. 自訂資源提供者會處理請求，並在逾時期間到期之前，將 JSON 回應傳回預先簽章的 Amazon S3 儲存貯體 URL。
1. CloudFormation 會讀取回應並繼續堆疊操作。如果在逾時期間結束前未收到任何回應，請求會被視為失敗，且堆疊操作會失敗。
如需詳細資訊，請參閱[自訂資源的運作方式](template-custom-resources.md#how-custom-resources-work)。
本節說明每個請求類型的結構、參數和預期回應。
**注意**
回應內文的總大小不能超過 4096 個位元組。
## 範本設定
在範本中定義自訂資源時，範本開發人員會使用 [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-cloudformation-customresource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-cloudformation-customresource.html)搭配下列屬性：
`ServiceToken`
Amazon SNS 主題 ARN 或 Lambda 函數 ARN，來自與堆疊相同的區域。
*必要*：是
*類型：*字串
`ServiceTimeout`
自訂資源操作逾時之前的時間上限，以秒為單位。它必須是介於 1 到 3600 之間的值。預設：3600 秒 (1 小時）。
*必要*：否
*類型：*字串
支援其他資源屬性。資源屬性將做為 包含在請求`ResourceProperties`中。自訂資源提供者必須判斷哪些屬性有效及其可接受的值。
## 請求物件
------
#### [ Create ]
當範本開發人員建立包含自訂資源的堆疊時，CloudFormation 會傳送將 `RequestType` 設定為 的請求`Create`。
建立包含以下欄位的請求：
`RequestType`
`Create`.
*必要*：是
*類型：*字串
`RequestId`
請求的唯一 ID。
結合 `StackId` 與 `RequestId` 形成值，該值可用於唯一識別特定自訂資源上的請求。
*必要*：是
*類型：*字串
`StackId`
識別包含自訂資源之堆疊的 Amazon Resource Name (ARN)。
結合 `StackId` 與 `RequestId` 形成值，該值可用於唯一識別特定自訂資源上的請求。
*必要*：是
*類型：*字串
`ResponseURL`
回應 URL 會識別預先簽章的 S3 儲存貯體，該儲存貯體會從自訂資源提供者接收對 CloudFormation 的回應。
*必要*：是
*類型：*字串
`ResourceType`
CloudFormation 範本內由範本開發人員選擇之自訂資源的資源類型。自訂資源類型名稱的長度上限為 60 個字元，且可包含英數字元及以下字元：`_@-`。
*必要*：是
*類型：*字串
`LogicalResourceId`
CloudFormation 範本中自訂資源的範本開發人員選擇名稱 （邏輯 ID)。
*必要*：是
*類型：*字串
`ResourceProperties`
此欄位包含由範本開發人員傳送的 `Properties` 物件內容。其內容由自訂資源提供者定義。
*必要*：否
*類型*：JSON 物件
*範例*
```
{
"RequestType" : "Create",
"RequestId" : "unique-request-id",
"StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/id",
"ResponseURL" : "pre-signed-url-for-create-response",
"ResourceType" : "Custom::MyCustomResourceType",
"LogicalResourceId" : "resource-logical-id",
"ResourceProperties" : {
"key1" : "string",
"key2" : [ "list" ],
"key3" : { "key4" : "map" }
}
}
```
------
#### [ Update ]
當範本開發人員變更範本中自訂資源的屬性並更新堆疊時，CloudFormation 會將請求傳送至自訂資源提供者，並將 `RequestType` 設定為 `Update`。這表示您的自訂資源程式碼不需要偵測資源的變更，因為它知道其屬性在請求類型為 `Update` 時已變更。
更新包含以下欄位的請求：
`RequestType`
`Update`.
*必要*：是
*類型：*字串
`RequestId`
請求的唯一 ID。
結合 `StackId` 與 `RequestId` 形成值，該值可用於唯一識別特定自訂資源上的請求。
*必要*：是
*類型：*字串
`StackId`
識別包含自訂資源之堆疊的 Amazon Resource Name (ARN)。
結合 `StackId` 與 `RequestId` 形成值，該值可用於唯一識別特定自訂資源上的請求。
*必要*：是
*類型：*字串
`ResponseURL`
回應 URL 會識別預先簽章的 S3 儲存貯體，該儲存貯體會從自訂資源提供者接收對 CloudFormation 的回應。
*必要*：是
*類型：*字串
`ResourceType`
CloudFormation 範本內由範本開發人員選擇之自訂資源的資源類型。自訂資源類型名稱的長度上限為 60 個字元，且可包含英數字元及以下字元：`_@-`。您無法於更新期間變更類型。
*必要*：是
*類型：*字串
`LogicalResourceId`
CloudFormation 範本中自訂資源的範本開發人員選擇名稱 （邏輯 ID)。
*必要*：是
*類型：*字串
`PhysicalResourceId`
自訂資源提供者定義的實體 ID，對於該提供者是唯一的。
*必要*：是
*類型：*字串
`ResourceProperties`
此欄位包含由範本開發人員傳送的 `Properties` 物件內容。其內容由自訂資源提供者定義。
*必要*：否
*類型*：JSON 物件
`OldResourceProperties`
僅用於 `Update` 請求。範本開發人員之前在 CloudFormation 範本中宣告的資源屬性值。
*必要*：是
*類型*：JSON 物件
*範例*
```
{
"RequestType" : "Update",
"RequestId" : "unique-request-id",
"StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/id",
"ResponseURL" : "pre-signed-url-for-update-response",
"ResourceType" : "Custom::MyCustomResourceType",
"LogicalResourceId" : "resource-logical-id",
"PhysicalResourceId" : "provider-defined-physical-id",
"ResourceProperties" : {
"key1" : "new-string",
"key2" : [ "new-list" ],
"key3" : { "key4" : "new-map" }
},
"OldResourceProperties" : {
"key1" : "string",
"key2" : [ "list" ],
"key3" : { "key4" : "map" }
}
}
```
------
#### [ Delete ]
當範本開發人員刪除堆疊或從範本中移除自訂資源，然後更新堆疊時，CloudFormation 會傳送將 `RequestType` 設定為 的請求`Delete`。
刪除包含以下欄位的請求：
`RequestType`
`Delete`.
*必要*：是
*類型：*字串
`RequestId`
請求的唯一 ID。
*必要*：是
*類型：*字串
`StackId`
識別包含自訂資源之堆疊的 Amazon Resource Name (ARN)。
*必要*：是
*類型：*字串
`ResponseURL`
回應 URL 會識別預先簽章的 S3 儲存貯體，該儲存貯體會從自訂資源提供者接收對 CloudFormation 的回應。
*必要*：是
*類型：*字串
`ResourceType`
CloudFormation 範本內由範本開發人員選擇之自訂資源的資源類型。自訂資源類型名稱的長度上限為 60 個字元，且可包含英數字元及以下字元：`_@-`。
*必要*：是
*類型：*字串
`LogicalResourceId`
CloudFormation 範本中自訂資源的範本開發人員選擇名稱 （邏輯 ID)。
*必要*：是
*類型：*字串
`PhysicalResourceId`
自訂資源提供者定義的實體 ID，對於該提供者是唯一的。
*必要*：是
*類型：*字串
`ResourceProperties`
此欄位包含由範本開發人員傳送的 `Properties` 物件內容。其內容由自訂資源提供者定義。
*必要*：否
*類型*：JSON 物件
*範例*
```
{
"RequestType" : "Delete",
"RequestId" : "unique-request-id",
"StackId" : "arn:aws:cloudformation:us-west-2:123456789012:stack/mystack/id",
"ResponseURL" : "pre-signed-url-for-delete-response",
"ResourceType" : "Custom::MyCustomResourceType",
"LogicalResourceId" : "resource-logical-id",
"PhysicalResourceId" : "provider-defined-physical-id",
"ResourceProperties" : {
"key1" : "string",
"key2" : [ "list" ],
"key3" : { "key4" : "map" }
}
}
```
------
## 回應物件
自訂資源提供者會將回應傳送至所有請求類型的預先簽章 URL。如果自訂資源提供者未傳送回應，CloudFormation 會等到操作逾時。
回應必須是具有下列欄位的 JSON 物件：
`Status`
必須為 `SUCCESS` 或 `FAILED`。
*必要*：是
*類型：*字串
`RequestId`
請求的唯一 ID。複製此值與請求中顯示的完全相同。
*必要*：是
*類型：*字串
`StackId`
識別包含自訂資源之堆疊的 Amazon Resource Name (ARN)。複製此值與請求中顯示的完全相同。
*必要*：是
*類型：*字串
`LogicalResourceId`
CloudFormation 範本中自訂資源的範本開發人員選擇名稱 （邏輯 ID)。複製此值與請求中顯示的完全相同。
*必要*：是
*類型：*字串
`PhysicalResourceId`
此值應為自訂資源廠商的唯一識別碼，且大小上限為 1 KB。此值必須是非空白字串，並且對於相同資源的所有回應必須完全相同。
更新自訂資源時， 傳回的值會`PhysicalResourceId`決定更新行為。如果值保持不變，CloudFormation 會將其視為正常更新。如果值變更，CloudFormation 會將更新解譯為取代，並將刪除請求傳送至舊資源。如需詳細資訊，請參閱[https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-cloudformation-customresource.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-cloudformation-customresource.html)。
*必要*：是
*類型：*字串
`Reason`
描述失敗回應的原因。
在 `Status` 為 `FAILED` 時需要。否則為選用。
*必要*：有條件
*類型：*字串
`NoEcho`
指示使用 `Fn::GetAtt` 函數擷取自訂資源時是否要遮罩其輸出。如果設定為 `true`，則所有傳回的值都會以星號 (\$1\$1\$1\$1\$1) 遮罩，*但儲存在範本 `Metadata` 區段中的值除外*。CloudFormation 不會轉換、修改或標記您在 `Metadata` 區段中包含的任何資訊。預設值為 `false`。
如需使用 `NoEcho` 遮罩敏感資訊的詳細資訊，請參閱 [請勿在您的範本中內嵌憑證](security-best-practices.md#creds) 最佳實務。
僅適用於 `Create`和 `Update`回應。不支援`Delete`回應。
*必要*：否
*類型*：布林值
`Data`
要與回應一起傳送的自訂資源提供者定義之名稱值對。您可以在模板中透過 `Fn::GetAtt` 依名稱存取此處提供的值。
僅適用於 `Create`和 `Update`回應。不支援`Delete`回應。
如果名稱值對包含敏感資訊，您應該使用 `NoEcho` 欄位來遮罩自訂資源的輸出。否則，這些值可透過表示屬性值 (例如 `DescribeStackEvents`) 的 API 可見。
*必要*：否
*類型*：JSON 物件
### 成功回應範例
#### `Create` 和 `Update` 回應
```
{
"Status": "SUCCESS",
"RequestId": "unique-request-id",
"StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/name/id",
"LogicalResourceId": "resource-logical-id",
"PhysicalResourceId": "provider-defined-physical-id",
"NoEcho": true,
"Data": {
"key1": "value1",
"key2": "value2"
}
}
```
#### `Delete` 回應
```
{
"Status": "SUCCESS",
"RequestId": "unique-request-id",
"StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/name/id",
"LogicalResourceId": "resource-logical-id",
"PhysicalResourceId": "provider-defined-physical-id"
}
```
### 失敗的回應範例
```
{
"Status": "FAILED",
"RequestId": "unique-request-id",
"StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/name/id",
"LogicalResourceId": "resource-logical-id",
"PhysicalResourceId": "provider-defined-physical-id",
"Reason": "Required failure reason string"
}
```