# CloudFormation カスタムリソースのリクエストおよびレスポンスのリファレンス
CloudFormation は、カスタムリソースプロバイダーと通信するリクエスト/レスポンスプロトコルを使用してカスタムリソースを管理します。各リクエストにはリクエストタイプ (`Create`、`Update`、または `Delete`) が含まれ、次の高レベルのワークフローに従います。
1. テンプレート開発者は、テンプレート内の `ServiceToken` と `ServiceTimeout` を使用してカスタムリソースを定義し、スタックオペレーションを開始します。
1. CloudFormation は、JSON リクエストを SNS または Lambda を介してカスタムリソースプロバイダーに送信します。
1. カスタムリソースプロバイダーはリクエストを処理し、タイムアウト期間が終了する前に JSON レスポンスを署名付き Amazon S3 バケット URL に返します。
1. CloudFormation はレスポンスを読み取り、スタックオペレーションを続行します。タイムアウト時間が終了する前に応答を受信しない場合、リクエストは不成功と見なされ、スタック操作は失敗します。
詳細については、「[カスタムリソースのしくみ](template-custom-resources.md#how-custom-resources-work)」を参照してください。
このセクションでは、各リクエストタイプの構造、パラメータ、および予想されるレスポンスについて説明します。
**注記**
レスポンス本文の合計サイズは 4,096 バイトを超えることはできません。
## テンプレートのセットアップ
テンプレートでカスタムリソースを定義する場合、テンプレート開発者は次のプロパティで [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 リソースネーム (ARN)。
`StackId` と `RequestId` を組み合わせると、特定のカスタムリソースに対するリクエストを一意に識別するために使用できる値が形成されます。
*必須:* はい
*タイプ*: 文字列
`ResponseURL`
応答 URL は、カスタムリソースプロバイダーから CloudFormation への応答を受信する署名済み S3 バケットを識別します。
*必須:* はい
*タイプ*: 文字列
`ResourceType`
CloudFormation テンプレート内のカスタムリソースに対し、テンプレートのデベロッパーが選択したリソースタイプ。カスタムリソースタイプの名前は、60 文字までの長さで指定できます。また、英数字や記号 `_@-` を含めることができます。
*必須:* はい
*タイプ*: 文字列
`LogicalResourceId`
CloudFormation テンプレートで開発者が選択したカスタムリソースの名前 (論理 ID)。
*必須:* はい
*タイプ*: 文字列
`ResourceProperties`
このフィールドにはテンプレート開発者によって送信された `Properties` オブジェクトの内容が含まれます。その内容は、custom resource provider によって定義されます。
*必須:* いいえ
*タイプ*: 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` に設定して custom resource provider にリクエストを送信します。カスタムリソースコードは、リクエスト タイプが `Update` のときにプロパティが変更されたことを認識しているため、リソースの変更を検出する必要がないということを、これは意味します。
更新リクエストには、以下のフィールドが含まれています。
`RequestType`
`Update`.
*必須:* はい
*タイプ*: 文字列
`RequestId`
リクエストの一意の ID。
`StackId` と `RequestId` を組み合わせると、特定のカスタムリソースに対するリクエストを一意に識別するために使用できる値が形成されます。
*必須:* はい
*タイプ*: 文字列
`StackId`
カスタムリソースを含むスタックを識別する Amazon リソースネーム (ARN)。
`StackId` と `RequestId` を組み合わせると、特定のカスタムリソースに対するリクエストを一意に識別するために使用できる値が形成されます。
*必須:* はい
*タイプ*: 文字列
`ResponseURL`
応答 URL は、カスタムリソースプロバイダーから CloudFormation への応答を受信する署名済み S3 バケットを識別します。
*必須:* はい
*タイプ*: 文字列
`ResourceType`
CloudFormation テンプレート内のカスタムリソースに対し、テンプレートのデベロッパーが選択したリソースタイプ。カスタムリソースタイプの名前は、60 文字までの長さで指定できます。また、英数字や記号 `_@-` を含めることができます。更新時にタイプを変更することはできません。
*必須:* はい
*タイプ*: 文字列
`LogicalResourceId`
CloudFormation テンプレートで開発者が選択したカスタムリソースの名前 (論理 ID)。
*必須:* はい
*タイプ*: 文字列
`PhysicalResourceId`
カスタムリソースプロバイダーによって定義された、プロバイダーで一意となる物理 ID。
*必須:* はい
*タイプ*: 文字列
`ResourceProperties`
このフィールドにはテンプレート開発者によって送信された `Properties` オブジェクトの内容が含まれます。その内容は、custom resource provider によって定義されます。
*必須:* いいえ
*タイプ*: 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 リソースネーム (ARN)。
*必須:* はい
*タイプ*: 文字列
`ResponseURL`
応答 URL は、カスタムリソースプロバイダーから CloudFormation への応答を受信する署名済み S3 バケットを識別します。
*必須:* はい
*タイプ*: 文字列
`ResourceType`
CloudFormation テンプレート内のカスタムリソースに対し、テンプレートのデベロッパーが選択したリソースタイプ。カスタムリソースタイプの名前は、60 文字までの長さで指定できます。また、英数字や記号 `_@-` を含めることができます。
*必須:* はい
*タイプ*: 文字列
`LogicalResourceId`
CloudFormation テンプレートで開発者が選択したカスタムリソースの名前 (論理 ID)。
*必須:* はい
*タイプ*: 文字列
`PhysicalResourceId`
カスタムリソースプロバイダーによって定義された、プロバイダーで一意となる物理 ID。
*必須:* はい
*タイプ*: 文字列
`ResourceProperties`
このフィールドにはテンプレート開発者によって送信された `Properties` オブジェクトの内容が含まれます。その内容は、custom resource provider によって定義されます。
*必須:* いいえ
*タイプ*: 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 リソースネーム (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` に設定すると、*テンプレートの `Metadata` セクションに保存されているものを除き*、すべての戻り値はアスタリスク (\$1\$1\$1\$1\$1) でマスクされます。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"
}
```