Pengaturan templat Permintaan objek Objek respons

CloudFormation permintaan sumber daya kustom dan referensi respons

CloudFormation mengelola sumber daya kustom melalui protokol permintaan-respons yang berkomunikasi dengan penyedia sumber daya kustom Anda. Setiap permintaan menyertakan jenis permintaan (Create,Update, atauDelete) dan mengikuti alur kerja tingkat tinggi ini:

Pengembang template mendefinisikan sumber daya kustom dengan ServiceToken dan ServiceTimeout di template dan memulai operasi tumpukan.
CloudFormation mengirimkan permintaan JSON ke penyedia sumber daya khusus melalui SNS atau Lambda.
Penyedia sumber daya kustom memproses permintaan dan mengembalikan respons JSON ke URL bucket Amazon S3 yang telah ditetapkan sebelumnya sebelum periode batas waktu berakhir.
CloudFormation membaca respons dan melanjutkan dengan operasi tumpukan. Jika tidak ada respons yang diterima sebelum periode batas waktu berakhir, permintaan dianggap tidak berhasil, dan operasi tumpukan gagal.

Untuk informasi selengkapnya, lihat Cara kerja sumber daya kustom.

Bagian ini menjelaskan struktur, parameter, dan respons yang diharapkan untuk setiap jenis permintaan.

catatan

Ukuran total badan respons tidak dapat melebihi 4096 byte.

Pengaturan templat

Saat mendefinisikan sumber daya kustom dalam templat, pengembang templat menggunakan AWS::CloudFormation::CustomResourceproperti berikut:

ServiceToken

Topik Amazon SNS ARN atau Lambda berfungsi ARN dari Wilayah yang sama dengan tumpukan.

Wajib: Ya

Tipe: String

ServiceTimeout

Waktu maksimum, dalam hitungan detik, sebelum waktu operasi sumber daya kustom habis. Itu harus nilai antara 1 dan 3600. Default: 3600 detik (1 jam).

Wajib: Tidak

Tipe: String

Properti sumber daya tambahan didukung. Properti sumber daya akan dimasukkan seperti ResourceProperties dalam permintaan. Penyedia sumber daya khusus harus menentukan properti mana yang valid dan nilainya yang dapat diterima.

Permintaan objek

Create

Saat pengembang template membuat tumpukan yang berisi sumber daya khusus, CloudFormation kirimkan permintaan dengan RequestType set keCreate.

Buat permintaan berisi bidang berikut:

RequestType

Create.

Wajib: Ya

Tipe: String

RequestId

ID unik untuk permintaan tersebut.

Menggabungkan StackId dengan RequestId formulir nilai yang dapat Anda gunakan untuk mengidentifikasi permintaan secara unik pada sumber daya khusus tertentu.

Wajib: Ya

Tipe: String

StackId

Nama Sumber Daya Amazon (ARN) yang mengidentifikasi tumpukan yang berisi sumber daya khusus.

Menggabungkan StackId dengan RequestId formulir nilai yang dapat Anda gunakan untuk mengidentifikasi permintaan secara unik pada sumber daya khusus tertentu.

Wajib: Ya

Tipe: String

ResponseURL

URL respons mengidentifikasi bucket S3 yang telah ditetapkan sebelumnya yang menerima tanggapan dari penyedia sumber daya kustom ke. CloudFormation

Wajib: Ya

Tipe: String

ResourceType

Jenis sumber daya yang dipilih developer templat dari sumber daya kustom di templat CloudFormation . Nama jenis sumber daya kustom dapat memiliki panjang hingga 60 karakter dan dapat mencakup alfanumerik dan karakter berikut: _@-.

Wajib: Ya

Tipe: String

LogicalResourceId

Nama template yang dipilih pengembang (ID logis) dari sumber daya kustom dalam template. CloudFormation

Wajib: Ya

Tipe: String

ResourceProperties

Bidang ini berisi isi Properties objek yang dikirim oleh pengembang template. Isinya ditentukan oleh penyedia sumber daya khusus.

Wajib: Tidak

Jenis: objek JSON

Contoh


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

Ketika pengembang template membuat perubahan pada properti sumber daya kustom dalam template dan memperbarui tumpukan, CloudFormation mengirimkan permintaan ke penyedia sumber daya kustom dengan RequestType set keUpdate. Ini berarti bahwa kode sumber daya kustom Anda tidak harus mendeteksi perubahan sumber daya karena mengetahui bahwa propertinya telah berubah ketika jenis permintaanUpdate.

Permintaan Perbarui berisi bidang berikut:

RequestType

Update.

Wajib: Ya

Tipe: String

RequestId

ID unik untuk permintaan tersebut.

Menggabungkan StackId dengan RequestId formulir nilai yang dapat Anda gunakan untuk mengidentifikasi permintaan secara unik pada sumber daya khusus tertentu.

Wajib: Ya

Tipe: String

StackId

Nama Sumber Daya Amazon (ARN) yang mengidentifikasi tumpukan yang berisi sumber daya khusus.

Menggabungkan StackId dengan RequestId formulir nilai yang dapat Anda gunakan untuk mengidentifikasi permintaan secara unik pada sumber daya khusus tertentu.

Wajib: Ya

Tipe: String

ResponseURL

URL respons mengidentifikasi bucket S3 yang telah ditetapkan sebelumnya yang menerima tanggapan dari penyedia sumber daya kustom ke. CloudFormation

Wajib: Ya

Tipe: String

ResourceType

Wajib: Ya

Tipe: String

LogicalResourceId

Nama template yang dipilih pengembang (ID logis) dari sumber daya kustom dalam template. CloudFormation

Wajib: Ya

Tipe: String

PhysicalResourceId

ID fisik yang ditentukan penyedia sumber daya khusus yang unik untuk penyedia tersebut.

Wajib: Ya

Tipe: String

ResourceProperties

Bidang ini berisi isi Properties objek yang dikirim oleh pengembang template. Isinya ditentukan oleh penyedia sumber daya khusus.

Wajib: Tidak

Jenis: objek JSON

OldResourceProperties

Digunakan hanya untuk Update permintaan. Nilai properti sumber daya yang sebelumnya dideklarasikan oleh pengembang template dalam CloudFormation template.

Wajib: Ya

Jenis: objek JSON

Contoh


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

Ketika pengembang template menghapus tumpukan atau menghapus sumber daya kustom dari template dan kemudian memperbarui tumpukan, CloudFormation mengirimkan permintaan dengan RequestType set keDelete.

Hapus permintaan berisi bidang berikut:

RequestType

Delete.

Wajib: Ya

Tipe: String

RequestId

ID unik untuk permintaan tersebut.

Wajib: Ya

Tipe: String

StackId

Nama Sumber Daya Amazon (ARN) yang mengidentifikasi tumpukan yang berisi sumber daya khusus.

Wajib: Ya

Tipe: String

ResponseURL

URL respons mengidentifikasi bucket S3 yang telah ditetapkan sebelumnya yang menerima tanggapan dari penyedia sumber daya kustom ke. CloudFormation

Wajib: Ya

Tipe: String

ResourceType

Wajib: Ya

Tipe: String

LogicalResourceId

Nama template yang dipilih pengembang (ID logis) dari sumber daya kustom dalam template. CloudFormation

Wajib: Ya

Tipe: String

PhysicalResourceId

ID fisik yang ditentukan penyedia sumber daya khusus yang unik untuk penyedia tersebut.

Wajib: Ya

Tipe: String

ResourceProperties

Bidang ini berisi isi Properties objek yang dikirim oleh pengembang template. Isinya ditentukan oleh penyedia sumber daya khusus.

Wajib: Tidak

Jenis: objek JSON

Contoh


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

Objek respons

Penyedia sumber daya kustom mengirimkan respons ke URL yang telah ditandatangani sebelumnya untuk semua jenis permintaan. Jika penyedia sumber daya kustom tidak mengirim respons, CloudFormation tunggu hingga waktu operasi habis.

Responsnya harus berupa objek JSON dengan bidang berikut:

Status

Harus SUCCESS atau FAILED.

Wajib: Ya

Tipe: String

RequestId

ID unik untuk permintaan tersebut. Salin nilai ini persis seperti yang muncul dalam permintaan.

Wajib: Ya

Tipe: String

StackId

Nama Sumber Daya Amazon (ARN) yang mengidentifikasi tumpukan yang berisi sumber daya khusus. Salin nilai ini persis seperti yang muncul dalam permintaan.

Wajib: Ya

Tipe: String

LogicalResourceId

Nama template yang dipilih pengembang (ID logis) dari sumber daya kustom dalam template. CloudFormation Salin nilai ini persis seperti yang muncul dalam permintaan.

Wajib: Ya

Tipe: String

PhysicalResourceId

Nilai ini harus menjadi pengidentifikasi yang unik untuk vendor sumber daya khusus, dan dapat berukuran hingga 1 KB. Nilai harus berupa string yang tidak kosong dan harus identik untuk semua tanggapan untuk sumber daya yang sama.

Saat memperbarui sumber daya kustom, nilai yang dikembalikan untuk PhysicalResourceId menentukan perilaku pembaruan. Jika nilainya tetap sama, CloudFormation anggap itu pembaruan normal. Jika nilai berubah, CloudFormation menafsirkan pembaruan sebagai pengganti dan mengirimkan permintaan hapus ke sumber daya lama. Untuk informasi selengkapnya, lihat AWS::CloudFormation::CustomResource.

Wajib: Ya

Tipe: String

Reason

Menjelaskan alasan respons kegagalan.

Diperlukan jika Status adalah FAILED. Sebaliknya, ini bersifat opsional.

Wajib: Bersyarat

Tipe: String

NoEcho

Menunjukkan apakah akan menutupi output dari sumber daya kustom saat diambil dengan menggunakan Fn::GetAtt fungsi. Jika disetel ketrue, semua nilai yang dikembalikan ditutupi dengan tanda bintang (*****), kecuali yang disimpan di bagian Metadata template. CloudFormation tidak mengubah, memodifikasi, atau menyunting informasi apa pun yang Anda sertakan di Metadata bagian ini. Nilai default-nya adalah false.

Untuk informasi selengkapnya tentang penggunaan NoEcho untuk menutupi informasi sensitif, lihat praktik Jangan menanamkan kredensial dalam templat Anda terbaik.

Hanya tersedia untuk Create dan Update tanggapan. Tidak didukung untuk Delete tanggapan.

Wajib: Tidak

Jenis: Boolean

Data

Pasangan nama-nilai yang ditentukan penyedia sumber daya khusus untuk dikirim dengan respons. Anda dapat mengakses nilai yang disediakan di sini dengan nama di template denganFn::GetAtt.

Hanya tersedia untuk Create dan Update tanggapan. Tidak didukung untuk Delete tanggapan.

penting

Jika pasangan nama-nilai berisi informasi sensitif, Anda harus menggunakan NoEcho bidang untuk menutupi output dari sumber daya kustom. Jika tidak, nilai terlihat melalui APIs nilai properti permukaan (sepertiDescribeStackEvents).

Wajib: Tidak

Jenis: objek JSON

Contoh Respon Sukses

`Create`dan `Update` Respon


{
   "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` Respons


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

Contoh Respon Gagal


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

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Sumber daya khusus

Sumber daya khusus yang didukung Amazon SNS

CloudFormation permintaan sumber daya kustom dan referensi respons

catatan

Pengaturan templat

Permintaan objek

Contoh

Contoh

Contoh

Objek respons

penting

Contoh Respon Sukses

Createdan Update Respon

Delete Respons

Contoh Respon Gagal

`Create`dan `Update` Respon

`Delete` Respons