CloudFormation カスタムリソースのリクエストおよびレスポンスのリファレンス - AWS CloudFormation
テンプレートのセットアップオブジェクトをリクエストするレスポンスオブジェクト

CloudFormation カスタムリソースのリクエストおよびレスポンスのリファレンス

CloudFormation は、カスタムリソースプロバイダーと通信するリクエスト/レスポンスプロトコルを使用してカスタムリソースを管理します。各リクエストにはリクエストタイプ (Create、Update、または Delete) が含まれ、次の高レベルのワークフローに従います。

  1. テンプレート開発者は、テンプレート内の ServiceToken と ServiceTimeout を使用してカスタムリソースを定義し、スタックオペレーションを開始します。

  2. CloudFormation は、JSON リクエストを SNS または Lambda を介してカスタムリソースプロバイダーに送信します。

  3. カスタムリソースプロバイダーはリクエストを処理し、タイムアウト期間が終了する前に JSON レスポンスを署名付き Amazon S3 バケット URL に返します。

  4. CloudFormation はレスポンスを読み取り、スタックオペレーションを続行します。タイムアウト時間が終了する前に応答を受信しない場合、リクエストは不成功と見なされ、スタック操作は失敗します。

詳細については、「カスタムリソースのしくみ」を参照してください。

このセクションでは、各リクエストタイプの構造、パラメータ、および予想されるレスポンスについて説明します。

注記

レスポンス本文の合計サイズは 4,096 バイトを超えることはできません。

テンプレートのセットアップ

テンプレートでカスタムリソースを定義する場合、テンプレート開発者は次のプロパティで AWS::CloudFormation::CustomResource を使用します。

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 は新しい方が更新用のものであると解釈し、古いリソースに削除リクエストを送信します。詳細については、 を参照してください。AWS::CloudFormation::CustomResource

必須: はい

タイプ: 文字列

Reason

失敗応答の理由を説明します。

Status が FAILED の場合は必須です。それ以外の場合はオプションです。

必須: 条件に応じて異なります

タイプ: 文字列

NoEcho

Fn::GetAtt 関数を使用して取得したときに、カスタムリソースの出力をマスクするかどうかを示します。true に設定すると、テンプレートの Metadata セクションに保存されているものを除き、すべての戻り値はアスタリスク (*****) でマスクされます。CloudFormation は、Metadata セクションに含める情報の変換、変更、または編集を行いません。デフォルト値は false です。

NoEcho を使用して機密情報をマスクする方法、および動的なパラメータを使用してシークレットを管理する方法の詳細については、「テンプレートに認証情報を埋め込まない」ベストプラクティスを参照してください。

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"
}