Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Buat definisi CloudFormation makro
Saat Anda membuat definisi makro, definisi makro membuat fungsi Lambda yang mendasarinya tersedia di akun yang ditentukan sehingga CloudFormation memanggilnya untuk memproses templat.
## Pemetaan acara
Ketika CloudFormation memanggil fungsi Lambda makro, ia mengirimkan permintaan dalam format JSON dengan struktur berikut:
```
{
"region" : "{{us-east-1}}",
"accountId" : "{{$ACCOUNT_ID}}",
"fragment" : { {{...}} },
"transformId" : "{{$TRANSFORM_ID}}",
"params" : { {{...}} },
"requestId" : "{{$REQUEST_ID}}",
"templateParameterValues" : { {{...}} }
}
```
+ `region`
Wilayah tempat makro berada.
+ `accountId`
ID akun akun tempat makro menjalankan fungsi Lambda.
+ `fragment`
Konten templat yang tersedia untuk pemrosesan kustom, dalam format JSON.
+ Untuk makro yang termasuk dalam bagian templat `Transform`, ini adalah seluruh templat kecuali untuk bagian `Transform`.
+ Untuk makro yang disertakan dalam panggilan fungsi intrinsik `Fn::Transform`, ini mencakup semua node saudara (dan turunannya) berdasarkan lokasi fungsi intrinsik dalam templat kecuali untuk fungsi `Fn::Transform` tersebut. Untuk informasi selengkapnya, lihat [Ruang lingkup template makro](#template-macros-scope).
+ `transformId`
Nama makro yang memanggil fungsi ini.
+ `params`
Untuk panggilan `Fn::Transform` fungsi, parameter apa pun yang ditentukan untuk fungsi tersebut. CloudFormation tidak mengevaluasi parameter ini sebelum meneruskannya ke fungsi.
Untuk makro yang termasuk dalam bagian templat `Transform`, bagian ini kosong.
+ `requestId`
ID permintaan yang memanggil fungsi ini.
+ `templateParameterValues`
Parameter apa pun yang ditentukan di [Parameters](parameters-section-structure.md) bagian templat. CloudFormation mengevaluasi parameter ini sebelum meneruskannya ke fungsi.
## Format respons
CloudFormation mengharapkan fungsi Lambda mengembalikan respons dalam format JSON berikut:
```
{
"requestId" : "{{$REQUEST_ID}}",
"status" : "{{$STATUS}}",
"fragment" : { {{...}} },
"errorMessage": "optional error message for failures"
}
```
+ `requestId`
ID permintaan yang memanggil fungsi ini. Ini harus sesuai dengan ID permintaan yang disediakan oleh CloudFormation saat menjalankan fungsi.
+ `status`
Status permintaan (peka huruf besar kecil). Harus diatur ke`success`. CloudFormation memperlakukan setiap respon lain sebagai kegagalan.
+ `fragment`
Konten template yang diproses CloudFormation untuk disertakan dalam template yang diproses, termasuk saudara kandung. CloudFormation menggantikan konten template yang diteruskan ke fungsi Lambda dengan fragmen template yang diterimanya dalam respons Lambda.
Konten templat yang diproses harus berupa JSON yang valid, dan penyertaannya dalam templat yang diproses harus menghasilkan templat yang valid.
Jika fungsi Anda tidak benar-benar mengubah konten templat yang diteruskan CloudFormation ke sana, tetapi Anda masih perlu menyertakan konten itu dalam templat yang diproses, fungsi Anda perlu mengembalikan konten templat itu ke CloudFormation dalam responsnya.
+ `errorMessage`
Pesan kesalahan yang menjelaskan mengapa transformasi gagal. CloudFormation menampilkan pesan kesalahan ini di panel **Peristiwa** di halaman **Detail tumpukan** untuk tumpukan Anda.
Contoh:
```
Error creating change set: Transform
{{Akun AWS account
number}}::{{macro name}} failed with:
{{error message string}}.
```
## Buat definisi makro
**Untuk membuat definisi CloudFormation makro**
1. [Bangun fungsi Lambda](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html) yang akan menangani pemrosesan konten template. Hal ini dapat memproses setiap bagian dari template, sampai ke seluruh template.
1. Buat CloudFormation template yang berisi jenis `AWS::CloudFormation::Macro` sumber daya dan tentukan `Name` dan `FunctionName` properti. `FunctionName`Properti harus berisi ARN dari fungsi Lambda untuk dipanggil saat menjalankan makro. CloudFormation
1. (Opsional) Untuk membantu dalam debugging, Anda juga dapat menentukan `LogGroupName` dan `LogRoleArn` properti saat membuat jenis `AWS::CloudFormation::Macro` sumber daya untuk makro Anda. Properti ini memungkinkan Anda menentukan grup CloudWatch log Log yang CloudFormation mengirimkan informasi pencatatan kesalahan saat menjalankan fungsi Lambda dasar makro, dan peran tersebut CloudFormation harus diambil saat mengirim entri log ke log tersebut.
1. [Buat tumpukan](cfn-console-create-stack.md) menggunakan template dengan makro di akun yang ingin Anda gunakan. Atau, [buat kumpulan tumpukan dengan izin yang dikelola sendiri](stacksets-getting-started-create-self-managed.md) menggunakan templat dengan makro di akun administrator, lalu buat instance tumpukan di akun target.
1. Setelah CloudFormation berhasil membuat tumpukan yang berisi definisi makro, makro tersedia untuk digunakan dalam akun tersebut. Anda menggunakan makro dengan mereferensikannya di templat, di lokasi yang sesuai yang relevan dengan konten templat yang ingin Anda proses.
## Ruang lingkup template makro
Makro yang direferensikan di bagian `Transform` dari templat dapat memproses seluruh konten templat tersebut.
Makro yang direferensikan dalam suatu fungsi `Fn::Transform` dapat memproses konten salah satu elemen saudara (termasuk anak-anak) dari fungsi `Fn::Transform` tersebut dalam templat.
Misalnya, pada contoh templat di bawah ini, `AWS::Include` dapat memproses properti `MyBucket`, berdasarkan lokasi fungsi `Fn::Transform` yang memuatnya. `MyMacro` dapat memproses konten seluruh templat karena penyertaannya di bagian `Transform`.
```
# Start of processable content for MyMacro
AWSTemplateFormatVersion: 2010-09-09
Transform: [MyMacro]
Resources:
WaitCondition:
Type: AWS::CloudFormation::WaitCondition
MyBucket:
Type: AWS::S3::Bucket
# Start of processable content for AWS::Include
Properties:
BucketName: {{amzn-s3-demo-bucket1}}
Tags: {{[{"key":"value"}]}}
'Fn::Transform':
- Name: 'AWS::Include'
Parameters:
Location: {{s3://amzn-s3-demo-bucket2/MyFileName.yaml}}
CorsConfiguration: {{[]}}
# End of processable content for AWS::Include
MyEc2Instance:
Type: AWS::EC2::Instance
Properties:
ImageID: {{ami-1234567890abcdef0}}
# End of processable content for MyMacro
```
## Urutan evaluasi makro
Anda dapat mereferensikan beberapa makro dalam templat tertentu, termasuk transformasi yang dihosting oleh CloudFormation, seperti [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/transform-aws-include.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/transform-aws-include.html)dan. [https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/transform-aws-serverless.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/transform-aws-serverless.html)
Macro dievaluasi secara berurutan, berdasarkan lokasi mereka di templat, dari yang paling dalam hingga yang paling umum. Makro di lokasi yang sama dalam template dievaluasi secara serial berdasarkan urutan daftar.
Transformasi seperti `AWS::Include` dan `AWS::Transform` diperlakukan sama seperti makro lainnya dalam hal urutan tindakan dan cakupan.
Misalnya, dalam contoh templat di bawah ini, CloudFormation evaluasi `PolicyAdder` makro terlebih dahulu, karena makro ini adalah makro yang paling dalam di template. CloudFormation kemudian mengevaluasi `MyMacro` sebelum mengevaluasi `AWS::Serverless` karena tercantum sebelumnya `AWS::Serverless` di bagian. `Transform`
```
AWSTemplateFormatVersion: 2010-09-09
Transform: [MyMacro, AWS::Serverless]
Resources:
WaitCondition:
Type: AWS::CloudFormation::WaitCondition
MyBucket:
Type: AWS::S3::Bucket
Properties:
BucketName: {{amzn-s3-demo-bucket}}
Tags: {{[{"key":"value"}]}}
'Fn::Transform':
- Name: PolicyAdder
CorsConfiguration: {{[]}}
MyEc2Instance:
Type: AWS::EC2::Instance
Properties:
ImageID: {{ami-1234567890abcdef0}}
```