Praktik terbaik untuk Bicep

Artikel
07/11/2024

Artikel ini merekomendasikan praktik yang harus diikuti saat mengembangkan file Bicep. Praktik ini membuat file Bicep Anda lebih mudah dipahami dan digunakan.

Sumber daya pelatihan

Jika Anda lebih suka mempelajari praktik terbaik Bicep melalui panduan langkah demi langkah, lihat Menyusun kode Bicep Anda untuk kolaborasi.

Parameter

Gunakan penamaan yang bagus untuk deklarasi parameter. Nama yang bagus membuat templat Anda mudah dibaca dan dipahami. Pastikan Anda menggunakan nama yang jelas dan deskriptif, dan konsisten dalam penamaan Anda.
Pikirkan dengan cermat parameter yang digunakan templat Anda. Coba gunakan parameter untuk pengaturan yang berubah antar-penyebaran. Variabel dan nilai yang dikodekan secara permanen dapat digunakan untuk pengaturan yang tidak berubah di antara penyebaran.
Berhati-hatilah dengan nilai default yang Anda gunakan. Pastikan nilai default aman bagi siapa saja untuk disebarkan. Misalnya, pertimbangkan untuk menggunakan tingkat harga dan SKU berbiaya rendah sehingga seseorang yang menyebarkan templat ke lingkungan pengujian tidak dikenakan biaya besar yang tidak diperlukan.
Gunakan dekorator @allowed dengan hemat. Jika Anda menggunakan dekorator ini terlalu luas, Anda dapat memblokir penyebaran yang valid. Saat layanan Azure menambahkan SKU dan ukuran, daftar yang diizinkan mungkin belum diperbarui. Misalnya, hanya mengizinkan SKU Premium v3 mungkin masuk akal dalam produksi, tetapi mencegah Anda menggunakan templat yang sama di lingkungan non-produksi.
Ini adalah praktik yang baik untuk memberikan deskripsi untuk parameter Anda. Cobalah untuk membuat deskripsi yang bermanfaat, dan berikan informasi penting tentang apa yang dibutuhkan templat nilai parameter.

Anda juga dapat menggunakan komentar // untuk menambahkan catatan dalam file Bicep Anda.
Anda dapat menempatkan deklarasi parameter di mana saja dalam file templat, meskipun ada baiknya menempatkannya di bagian atas file sehingga kode Bicep Anda mudah dibaca.
Ini adalah praktik yang baik untuk menentukan panjang karakter minimum dan maksimum untuk parameter yang mengontrol penamaan. Batasan ini membantu menghindari kesalahan selama penyebaran.

Untuk informasi selengkapnya tentang parameter Bicep, lihat Parameter di Bicep.

Variabel

Saat Anda menentukan variabel, jenis data tidak diperlukan. Variabel menyimpulkan jenis dari nilai penyelesaian.
Anda dapat menggunakan fungsi Bicep untuk membuat variabel.
Setelah variabel didefinisikan dalam file Bicep, Anda mereferensikan nilai menggunakan nama variabel.

Untuk informasi selengkapnya tentang variabel Bicep, lihat Variabel di Bicep.

Nama

Gunakan gaya penulisan camel case huruf kecil untuk nama, seperti myVariableName atau myResource.
Fungsi uniqueString() berguna untuk membuat nama sumber yang unik secara global. Saat Anda memberikan parameter yang sama, parameter akan mengembalikan string yang sama setiap saat. Meneruskan ID grup sumber daya berarti string sama pada setiap penyebaran ke grup sumber daya yang sama, tetapi berbeda saat Anda menyebarkan ke grup sumber daya atau langganan yang berbeda.
Ini adalah praktik yang baik untuk menggunakan templat ekspresi untuk membuat nama-nama sumber, seperti dalam contoh ini:
```
param shortAppName string = 'toy'
param shortEnvironmentName string = 'prod'
param appServiceAppName string = '${shortAppName}-${shortEnvironmentName}-${uniqueString(resourceGroup().id)}'
```
Menggunakan templat ekspresi dalam membuat nama-nama sumber memberikan Anda beberapa manfaat:
- String yang dibuat berdasarkanuniqueString() tidak bermakna. Penggunaan templat ekspresi sangat membantu untuk membuat nama yang menyertakan informasi yang bermakna, seperti deskriptor singkat nama proyek atau lingkungan, serta komponen acak untuk membuat nama menjadi lebih unik.
- Fungsi uniqueString() ini tidak menjamin nama yang unik secara global. Dengan menambahkan teks tambahan ke nama-nama sumber, Anda kemungkinan mengurangi penggunaan kembali nama sumber daya yang telah ada.
- Terkadang fungsi uniqueString() membuat string yang dimulai dengan angka. Beberapa sumber daya Azure, seperti akun penyimpanan, tidak mengizinkan namanya dimulai dengan angka. Persyaratan ini berarti sebaiknya menggunakan interpolasi string untuk membuat nama sumber daya. Anda dapat menambahkan awalan ke string unik.
- Banyak jenis sumber daya Azure memiliki aturan tentang karakter yang diizinkan dan panjang nama. Menyematkan pembuatan nama sumber daya dalam templat berarti bahwa siapa pun yang menggunakan templat tidak perlu ingat untuk mengikuti aturan ini.

Hindari menggunakan name dalam nama simbolik. Nama simbolik mewakili sumber daya, bukan nama sumber daya. Sebagai contoh, alih-alih sintaks berikut ini:

resource cosmosDBAccountName 'Microsoft.DocumentDB/databaseAccounts@2023-11-15' = {

Gunakan:

resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2023-11-15' = {

Hindari membedakan variabel dan parameter dengan menggunakan akhiran.

Definisi sumber daya

Gunakan variabel untuk memuat ekspresi, bukan menyematkan ekspresi kompleks langsung ke properti sumber daya. Pendekatan ini membuat file Bicep Anda lebih mudah dibaca dan dipahami. Ini menghindari kekacauan definisi sumber daya Anda dengan logika.
Cobalah untuk menggunakan properti sumber daya sebagai output, daripada membuat asumsi tentang bagaimana sumber daya akan berperilaku. Misalnya, jika Anda perlu mengeluarkan URL ke aplikasi App Service, gunakan properti defaultHostname aplikasi, bukan membuat string untuk URL sendiri. Terkadang asumsi ini tidak benar di lingkungan yang berbeda, atau sumber daya mengubah cara kerjanya. Membuat sumber daya memberi tahu Anda propertinya sendiri akan lebih aman.
Ada baiknya menggunakan versi API terbaru untuk setiap sumber daya. Fitur baru dalam layanan Azure terkadang hanya tersedia dalam versi API yang lebih baru.
Jika memungkinkan, hindari menggunakan fungsi referensi danresourceId dalam file Bicep Anda. Anda dapat mengakses sumber daya apa pun di Bicep dengan menggunakan nama simbolis. Misalnya, jika Anda menentukan akun penyimpanan dengan nama simbolis toyDesignDocumentsStorageAccount, Anda dapat mengakses ID sumber dayanya dengan menggunakan ekspresi toyDesignDocumentsStorageAccount.id. Dengan menggunakan nama simbolis, Anda membuat dependensi implisit di antara sumber daya.
Utamakan menggunakan dependensi implisit daripada dependensi eksplisit. Meskipun properti sumber daya dependsOn memungkinkan Anda untuk menyatakan dependensi eksplisit antara sumber daya, biasanya properti sumber daya lain dapat digunakan dengan menggunakan nama simbolisnya. Pendekatan ini menciptakan dependensi implisit antara kedua sumber daya, dan memungkinkan Bicep untuk mengelola hubungan tersebut sendiri.
Jika sumber daya tidak digunakan dalam file Bicep, Anda masih bisa mendapatkan referensi simbolis ke sumber daya menggunakan kata kunci existing.

Sumber daya turunan

Hindari menyarangkan terlalu banyak lapisan dalam. Terlalu banyak penyarangan membuat kode Bicep Anda lebih sulit dibaca dan dikerjakan.
Hindari membangun nama sumber daya untuk sumber daya anak. Anda kehilangan keuntungan yang diberikan Bicep ketika memahami hubungan antara sumber daya Anda. Gunakan properti parent atau penyarangan sebagai gantinya.

Output

Pastikan Anda tidak membuat output untuk data sensitif. Nilai output dapat diakses oleh siapa saja yang memiliki akses ke riwayat penyebaran. Ini tidak tepat untuk menangani rahasia.
Gunakan kata kunci yang sudah ada untuk mencari properti sumber daya yang sudah ada, daripada meneruskan nilai properti melalui output. Ini adalah praktik terbaik untuk mencari kunci dari sumber daya lain dengan cara ini, bukan melewatinya melalui output. Anda akan selalu mendapatkan data terbaru.

Untuk informasi selengkapnya tentang output Bicep, lihat Output dalam Bicep.

Cakupan penyewa

Anda tidak dapat membuat kebijakan atau penetapan peran di cakupan penyewa. Namun, jika Anda perlu memberikan akses atau menerapkan kebijakan di seluruh organisasi, Anda dapat menerapkan sumber daya ini ke grup manajemen akar.

Langkah berikutnya

Untuk pengenalan Bicep, lihat Mulai cepat Bicep.
Untuk informasi tentang bagian-bagian file Bicep, lihat Memahami struktur dan sintaks file Bicep.

Bagikan melalui