Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # CloudFormation dukungan ekstensi bahasa AWS SAMCLIMendukung template yang menggunakan `AWS::LanguageExtensions` transformasi, termasuk`Fn::ForEach`,`Fn::Length`,`Fn::ToJsonString`, dan `Fn::FindInMap` dengan`DefaultValue`. Untuk informasi referensi lengkap tentang konstruksi ini, lihat [AWS::LanguageExtensions mengubah](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/transform-aws-languageextensions.html) dalam *Panduan AWS CloudFormation Pengguna*. Untuk menggunakan ekstensi bahasa dalam AWS SAM templat, daftar `AWS::LanguageExtensions` di `Transform` bagian *sebelumnya*`AWS::Serverless-2016-10-31`: ``` Transform: - AWS::LanguageExtensions - AWS::Serverless-2016-10-31 ``` Ketika AWS SAMCLI mendeteksi `AWS::LanguageExtensions` di `Transform` bagian template *dan* Anda telah memilih untuk pemrosesan lokal, itu memperluas konstruksi ekstensi bahasa secara lokal sebelum menjalankan transformasi. AWS SAM Hal ini memungkinkan `sam build``sam package`,`sam deploy`,`sam sync`,`sam validate`,`sam local invoke`,`sam local start-api`,, dan `sam local start-lambda` untuk bekerja dengan template yang menggunakan konstruksi ini. Pemrosesan lokal dimatikan secara default. Saat mati, AWS SAMCLI melewati templat tanpa perubahan dan CloudFormation memproses sisi server `AWS::LanguageExtensions` transformasi pada waktu penerapan. Untuk metode aktivasi, lihat[Mengaktifkan ekstensi bahasa](#sam-specification-language-extensions-enabling). Ekspansi terjadi dalam dua fase saat diaktifkan: 1. **Fase 1 (Ekstensi Bahasa)** — `Fn::ForEach` loop diperluas, fungsi intrinsik diselesaikan jika memungkinkan, dan template dikonversi ke standar. CloudFormation 1. **Fase 2 (AWS SAM Transform)** - Template yang diperluas diproses oleh AWS SAM Penerjemah seperti biasa. Template asli (dengan `Fn::ForEach` utuh) dipertahankan untuk CloudFormation penerapan, karena CloudFormation memproses `AWS::LanguageExtensions` transformasi sisi server. ## Mengaktifkan ekstensi bahasa Pemrosesan lokal `AWS::LanguageExtensions` adalah opt-in per perintah. Ada tiga metode aktivasi yang setara, tercantum dalam urutan prioritas: 1. **CLIbendera** — `--language-extensions` teruskan satu doa: ``` sam build --language-extensions sam package --language-extensions ... sam deploy --language-extensions ... ``` `--no-language-extensions`menonaktifkan secara eksplisit, mengesampingkan keduanya `samconfig.toml` dan variabel lingkungan yang dijelaskan di bawah ini. 1. **`samconfig.toml`**— mempertahankan pilihan per proyek: ``` [default.build.parameters] language_extensions = true [default.package.parameters] language_extensions = true [default.deploy.parameters] language_extensions = true [default.sync.parameters] language_extensions = true [default.local_invoke.parameters] language_extensions = true [default.local_start_api.parameters] language_extensions = true [default.local_start_lambda.parameters] language_extensions = true [default.validate.parameters] language_extensions = true ``` `samconfig.toml`Entri dimuat sebagai default untuk perintah, sehingga berlaku seolah-olah bendera dilewatkan — dan karenanya menang atas variabel lingkungan. 1. **Variabel lingkungan** - diatur `SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1` untuk mengaktifkan shell saat ini: ``` export SAM_CLI_ENABLE_LANGUAGE_EXTENSIONS=1 sam build sam local invoke MyFunction ``` Nilai-nilai yang benar (case-insensitive) adalah`1`,, dan. `true` `yes` Hal lain, termasuk string kosong, diperlakukan sebagai tidak aktif. Variabel lingkungan dikonsultasikan hanya ketika tidak ada CLI tanda atau `samconfig.toml` menetapkan nilai. **penting** Setiap perintah membutuhkan aktivasi sendiri. Melewati `--language-extensions` ke `sam build` tidak menyebar ke nanti `sam local invoke` — pemrosesan lokal diputuskan per pemanggilan perintah. Gunakan variabel lingkungan atau `samconfig.toml` entri untuk mengaktifkan seluruh perintah tanpa mengulangi bendera. ## Fn:: ForEach `Fn::ForEach`menghasilkan beberapa sumber daya, kondisi, atau output dari satu definisi template: ``` Transform: - AWS::LanguageExtensions - AWS::Serverless-2016-10-31 Parameters: ServiceNames: Type: CommaDelimitedList Default: "Users,Orders,Products" Resources: Fn::ForEach::Services: - Name - !Ref ServiceNames - ${Name}Function: Type: AWS::Serverless::Function Properties: Handler: index.handler Runtime: python3.12 CodeUri: ./services/${Name} ``` Running `sam build` memperluas ini menjadi`UsersFunction`,`OrdersFunction`, dan`ProductsFunction`, masing-masing dibangun dari direktori sumbernya masing-masing. ### Sifat artefak dinamis Ketika properti packageable menggunakan variabel loop (misalnya,`./services/${Name}`), akan AWS SAMCLI menghasilkan CloudFormation `Mappings` bagian yang memetakan setiap nilai koleksi ke Amazon S3-nya. URI `Fn::ForEach`Tubuh ditulis ulang untuk digunakan `Fn::FindInMap` sehingga CloudFormation dapat menyelesaikan artefak yang benar pada waktu penyebaran. Properti artefak yang diakui adalah yang sama yang `sam package` ditulis ulang hari ini. Itu termasuk: **Sifat artefak dinamis yang diakui oleh AWS SAM CLI** | Tipe sumber daya | Properti | | --- | --- | | `AWS::Serverless::Function` | `CodeUri`, `ImageUri` | | `AWS::Serverless::LayerVersion` | `ContentUri` | | `AWS::Serverless::Api` | `DefinitionUri` | | `AWS::Serverless::HttpApi` | `DefinitionUri` | | `AWS::Serverless::StateMachine` | `DefinitionUri` | | `AWS::Serverless::GraphQLApi` | `SchemaUri`, `CodeUri` | | `AWS::Serverless::Application` | `Location` | | `AWS::Lambda::Function` | `Code`, `Code.ImageUri` | | `AWS::Lambda::LayerVersion` | `Content` | | `AWS::ApiGateway::RestApi` | `BodyS3Location` | | `AWS::ApiGatewayV2::Api` | `BodyS3Location` | | `AWS::AppSync::GraphQLSchema` | `DefinitionS3Location` | | `AWS::AppSync::Resolver` | `RequestMappingTemplateS3Location`, `ResponseMappingTemplateS3Location`, `CodeS3Location` | | `AWS::AppSync::FunctionConfiguration` | `RequestMappingTemplateS3Location`, `ResponseMappingTemplateS3Location`, `CodeS3Location` | | `AWS::StepFunctions::StateMachine` | `DefinitionS3Location` | | `AWS::ElasticBeanstalk::ApplicationVersion` | `SourceBundle` | | `AWS::Glue::Job` | `Command.ScriptLocation` | | `AWS::CloudFormation::Stack` | `TemplateURL` | | `AWS::CloudFormation::StackSet` | `TemplateURL` | | `AWS::CloudFormation::ModuleVersion` | `ModulePackage` | | `AWS::CloudFormation::ResourceVersion` | `SchemaHandlerPackage` | Untuk properti bertitik (misalnya, aktif `AWS::Glue::Job` atau `Command.ScriptLocation` `Code.ImageUri` aktif`AWS::Lambda::Function`), nilainya dibaca dan ditulis di lokasi bersarang pada sumber daya. Nama Pemetaan yang dihasilkan hanya menggunakan segmen daun dari jalur properti. Ketika properti di-loop-templated, nama Pemetaan adalah `SAM` (misalnya, atau). `SAMCodeUriServices` `SAMScriptLocationJobs` **penting** Customer-authored pemetaan tidak boleh dimulai dengan `SAM*` awalan ini — mereka dicadangkan untuk. AWS SAMCLI Lihat [Batasan](#sam-specification-language-extensions-limitations). Misalnya, setelah`sam package`: ``` Mappings: SAMCodeUriServices: Users: CodeUri: s3://my-bucket/abc123 Orders: CodeUri: s3://my-bucket/def456 Products: CodeUri: s3://my-bucket/ghi789 Resources: Fn::ForEach::Services: - Name - !Ref ServiceNames - ${Name}Function: Type: AWS::Serverless::Function Properties: Handler: index.handler Runtime: python3.12 CodeUri: !FindInMap [SAMCodeUriServices, !Ref Name, CodeUri] ``` ### Berbagai sumber daya per ForEach tubuh Satu `Fn::ForEach` benda dapat memancarkan lebih dari satu sumber daya per iterasi. Setiap sumber daya dihasilkan untuk setiap nilai koleksi: ``` Resources: Fn::ForEach::Tables: - TableName - [Users, Orders, Products] - ${TableName}Table: Type: AWS::DynamoDB::Table Properties: TableName: !Sub "${AWS::StackName}-${TableName}" # ... ${TableName}StreamProcessor: Type: AWS::Serverless::Function Properties: CodeUri: stream-processors/${TableName}/ Events: DDBStream: Type: DynamoDB Properties: Stream: !GetAtt - !Sub "${TableName}Table" - StreamArn ``` ### Pemetaan resolusi tabrakan nama Ketika dua sumber daya dalam `Fn::ForEach` badan yang sama mendeklarasikan properti artefak dinamis yang sama (misalnya, penggunaan `Api` dan `StateMachine` penggunaan`DefinitionUri`), menambahkan AWS SAMCLI akhiran yang diambil dari bagian statis template Logical-ID sumber daya agar nama Pemetaan tetap unik: **Contoh nama pemetaan dengan sufiks tabrakan** | Template sumber daya | Properti | Nama pemetaan | | --- | --- | --- | | `${Svc}Api` | `DefinitionUri` | `SAMDefinitionUriServicesApi` | | `${Svc}StateMachine` | `DefinitionUri` | `SAMDefinitionUriServicesStateMachine` | Ketika tidak ada tabrakan, nama dasar (misalnya,`SAMDefinitionUriServices`) digunakan. ### Parameter-based koleksi Ketika `Fn::ForEach` koleksi adalah referensi parameter (misalnya,`!Ref ServiceNames`) dan badan loop menggunakan properti artefak dinamis (misalnya,`CodeUri: ./services/${Name}`), AWS SAMCLI kebutuhan nilai koleksi untuk menghasilkan `SAM*` Pemetaan dijelaskan dalam. [Sifat artefak dinamis](#sam-specification-language-extensions-dynamic-artifacts) Ini menyelesaikannya ketika memproses template, dari: 1. `--parameter-overrides`diteruskan ke AWS SAMCLI perintah. 1. `Default`Nilai parameter dalam template. **penting** Karena `SAM*` Pemetaan dibuat pada waktu paket, Anda harus mengemas ulang setiap kali Anda mengubah nilai parameter (misalnya, saat menambahkan layanan baru) sehingga Pemetaan menyertakan entri untuk nilai baru. Ini hanya berlaku ketika parameter menggerakkan loop artefak dinamis; penggantian parameter lainnya dapat diubah pada waktu penerapan seperti biasa. ``` # Package with the values you intend to deploy with sam package --language-extensions --parameter-overrides ServiceNames="Users,Orders,Products" # Deploy with the same values sam deploy --language-extensions --parameter-overrides ServiceNames="Users,Orders,Products" ``` ### Tumpukan nested `Fn::ForEach`di template tumpukan bersarang (`AWS::CloudFormation::Stack`) didukung. AWS SAMCLIMeneruskan `Parameters` properti tumpukan induk ke ekspansi templat anak, sehingga `Fn::ForEach` koleksi anak yang mereferensikan parameter yang disediakan induk diselesaikan dengan benar. ``` # parent.yaml Resources: ChildStack: Type: AWS::CloudFormation::Stack Properties: TemplateURL: ./child.yaml Parameters: ServiceNames: "Users,Orders,Products" ``` ### Fn bersarang:: ForEach Hingga 5 level bersarang didukung, sesuai dengan CloudFormation batas: ``` Resources: Fn::ForEach::Envs: - Env - [Dev, Staging, Prod] - Fn::ForEach::Services: - Svc - [Users, Orders] - ${Env}${Svc}Function: Type: AWS::Serverless::Function Properties: CodeUri: ./services/${Svc} Environment: Variables: STAGE: ${Env} ``` ### ForEach di Output `Fn::ForEach`blok juga diperluas di dalam `Outputs` bagian, sehingga Anda dapat memancarkan satu output per nilai koleksi: ``` Outputs: Fn::ForEach::FunctionArns: - Name - [alpha, beta] - ${Name}FunctionArn: Value: !GetAtt - !Sub "${Name}Function" - Arn ``` ### Kondisi dan DependsOn Sumber daya yang dipancarkan oleh `Fn::ForEach` dapat membawa `Condition` dan `DependsOn` seperti sumber daya lainnya. Kondisi atau ketergantungan direplikasi ke setiap sumber daya yang dihasilkan: ``` Conditions: IsProd: !Equals [!Ref Environment, prod] Resources: SharedTable: Type: AWS::DynamoDB::Table # ... Fn::ForEach::Functions: - Name - [api, worker] - ${Name}Function: Type: AWS::Serverless::Function Condition: IsProd DependsOn: SharedTable Properties: Handler: main.handler CodeUri: functions/${Name}/ ``` ### &{identifier} sintaks `&{identifier}`Sintaks menghapus karakter non-alfanumerik dari nilai substitusi, yang berguna untuk menghasilkan ID logis yang valid dari nilai-nilai seperti alamat IP: ``` Fn::ForEach::Hosts: - IP - ["10.0.0.1", "10.0.0.2"] - Host&{IP}: Type: AWS::EC2::Instance # Expands to Host10001, Host10002 ``` ## Fungsi intrinsik yang didukung Fungsi intrinsik berikut diselesaikan secara lokal selama ekspansi: **Fungsi intrinsik diselesaikan secara lokal selama ekspansi ekstensi bahasa** | Fungsi | Deskripsi | | --- | --- | | `Fn::ForEach` | Ekspansi loop. | | `Fn::Length` | Mengembalikan hitungan elemen daftar. | | `Fn::ToJsonString` | Mengkonversi nilai ke JSON string. | | `Fn::FindInMap` | Pencarian peta, termasuk opsional`DefaultValue`. | | `Fn::If` | Pemilihan nilai bersyarat. | | `Fn::Sub` | Substitusi string. | | `Fn::Join` | Rangkaian string. | | `Fn::Split` | Pemisahan tali. | | `Fn::Select` | Daftar pemilihan elemen. | | `Fn::Base64` | Pengkodean Base64. | | `Fn::Equals`, `Fn::And`, `Fn::Or`, `Fn::Not` | Evaluasi kondisi. | | `Ref` | Referensi parameter dan pseudo-parameter. | Fungsi yang memerlukan sumber daya yang digunakan (`Fn::GetAtt``Fn::ImportValue`,,`Fn::GetAZs`) dipertahankan CloudFormation untuk diselesaikan pada waktu penerapan. ## Kesalahan validasi Masalah template berikut ditangkap secara lokal sebelum AWS SAM transformasi berjalan: **Kesalahan validasi muncul selama ekspansi ekstensi bahasa** | Penyebab | Pesan kesalahan | | --- | --- | | `Fn::ForEach`Nilainya cacat - bukan daftar, tidak memiliki tepat 3 elemen, atau memiliki pengenal loop non-string. | `Fn::ForEach:: layout is incorrect`(dibesarkan sebagai`InvalidTemplateException`). | | Lebih dari 5 level `Fn::ForEach` bersarang. | `Fn::ForEach nesting depth of exceeds the maximum allowed depth of 5. CloudFormation supports up to 5 nested Fn::ForEach loops.` | | Koleksi menyelesaikan ke daftar kosong (misalnya, `CommaDelimitedList` parameter dengan`Default: ""`). | Tidak ada kesalahan - loop dilewati secara diam-diam dan tidak ada sumber daya yang dipancarkan. | | `!Ref`Di titik pengumpulan pada parameter yang tidak dinyatakan dalam template. | Tidak ada kesalahan - referensi yang belum terselesaikan dipertahankan dalam template. Pada waktu penerapan, CloudFormation akan menyelesaikannya di sisi server. | ## Batasan + **Koleksi harus dapat diselesaikan pada waktu build/package .** `Fn::ForEach`koleksi yang menggunakan`Fn::GetAtt`,`Fn::ImportValue`, atau referensi dinamis SSM/Secrets Manajer tidak dapat diperluas secara lokal. Gunakan parameter dengan `--parameter-overrides` sebagai gantinya. + **Pemetaan artefak dinamis ditetapkan pada waktu paket.** Ketika `Fn::ForEach` koleksi adalah referensi parameter dan badan loop menggunakan properti artefak dinamis (misalnya,`CodeUri: ./services/${Name}`), `SAM*` Pemetaan yang dihasilkan hanya berisi entri untuk nilai parameter yang diselesaikan pada waktu paket. Jika Anda mengubah `--parameter-overrides` parameter tersebut pada waktu penerapan tanpa mengemas ulang, nilai baru tidak akan memiliki entri Pemetaan dan penerapan akan gagal. Ini tidak berlaku untuk parameter yang tidak digunakan untuk menggerakkan `Fn::ForEach` artefak dinamis. + **`DeletionPolicy`dan `UpdateReplacePolicy`** divalidasi dan diselesaikan selama ekspansi. Mereka mendukung `Ref` parameter tetapi tidak fungsi intrinsik lainnya. + **Batas bersarang.** Hingga 5 level `Fn::ForEach` mungkin bersarang, cocok dengan batas sisi CloudFormation server. + **Nama Pemetaan Cadangan.** Nama pemetaan yang dimulai dengan salah satu dari berikut ini dicadangkan untuk AWS SAMCLI - jangan buat pemetaan Anda sendiri dengan awalan ini: + `SAMCodeUri`,`SAMImageUri`,,`SAMContentUri`,`SAMDefinitionUri`,`SAMSchemaUri`,`SAMBodyS3Location`,, `SAMDefinitionS3Location` `SAMTemplateURL``SAMCode`, `SAMContent` — dipancarkan oleh `sam package` untuk properti artefak dinamis. Lihat [Sifat artefak dinamis](#sam-specification-language-extensions-dynamic-artifacts) tabelnya. + `SAMLayers`— dipancarkan oleh `sam build` ketika fungsi yang dihasilkan mengambil referensi lapisan ketergantungan `Fn::ForEach` yang dihasilkan secara otomatis (Lambda melapisi build menjadi tumpukan bersarang). AWS SAMCLI Awalan ini tidak memiliki properti yang ditulis pengguna yang sesuai; itu ditambahkan secara otomatis. ## Telemetri AWS SAMCLI*Memancarkan peristiwa `CFNLanguageExtensions` telemetri ketika perintah dipanggil dengan `--language-extensions` (atau ekivalen variabel lingkungannya) dan template mendeklarasikan transformasi.* `AWS::LanguageExtensions` Acara diaktifkan sekali per pemanggilan dan tidak ada konten template yang ditransmisikan. Saat pemrosesan lokal tidak aktif (default), tidak ada peristiwa yang diaktifkan.