Memahami parameter

  • 8 menit

Dengan parameter, Anda dapat memberikan informasi ke templat Bicep pada waktu penyebaran. Anda dapat membuat templat Bicep yang fleksibel dan dapat digunakan kembali dengan menyatakan parameter dalam templat Anda.

Dekorator menyediakan cara untuk melampirkan batasan dan metadata ke parameter, yang membantu siapa pun yang menggunakan templat Anda untuk memahami informasi apa yang perlu mereka berikan.

Di unit ini, Anda akan belajar tentang parameter dan dekorator.

Menyatakan parameter

Dalam templat Bicep, Anda menyatakan parameter menggunakan kata kunci param. Anda dapat menempatkan deklarasi ini di mana saja dalam file templat, meskipun ada baiknya menempatkannya di bagian atas file sehingga kode Bicep Anda mudah dibaca.

Berikut adalah cara Anda menyatakan parameter:

param environmentName string

Mari kita lihat cara kerja setiap bagian:

  • param menunjukkan ke Bicep bahwa Anda menyatakan parameter.

  • environmentName mengacu pada nama parameter. Meskipun nama parameter bisa apa saja, Anda harus membuat nama yang jelas dan dapat dipahami untuk pengguna templat. Dalam templat yang sama, Anda juga dapat merujuk ke parameter menggunakan namanya. Nama parameter harus unik. Nama tidak boleh sama dengan nama variabel atau sumber daya dalam file Bicep yang sama.

    Tip

    Menggunakan konvensi penamaan praktik terbaik untuk deklarasi parameter. Konvensi penamaan yang baik membuat templat Anda mudah dibaca dan dipahami. Pastikan Anda menggunakan nama yang jelas dan deskriptif, serta menerapkan strategi penamaan yang konsisten.

  • string mengacu pada jenis parameter.

    Tip

    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.

Menambahkan nilai default

Anda dapat menetapkan nilai default ke parameter di templat Anda. Dengan menetapkan nilai default, Anda membuat opsional parameter. Jika templat disebarkan tanpa nilai yang ditentukan untuk parameter, nilai default ditetapkan.

Berikut cara menambahkan nilai default:

param environmentName string = 'dev'

Parameter environmentName diberi nilai default dev.

Anda dapat menggunakan ekspresi sebagai nilai default. Berikut adalah contoh parameter string bernama location dengan nilai default yang diatur ke lokasi grup sumber daya saat ini:

param location string = resourceGroup().location

Tip

Berhati-hatilah dengan nilai default yang Anda gunakan. Pastikan seseorang dapat menyebarkan file Bicep dengan nilai default secara aman. Misalnya, pertimbangkan untuk menggunakan tingkat harga dan SKU berbiaya rendah sehingga seseorang yang menyebarkan templat ke lingkungan pengujian tidak dikenakan biaya besar yang tidak perlu.

Memahami jenis parameter

Ketika Anda menyatakan parameter, Anda perlu memberi tahu Bicep jenis informasi apa yang akan tercantum dalam parameter. Bicep akan memastikan nilai yang ditetapkan ke parameter kompatibel dengan jenis parameter.

Parameter dalam Bicep dapat menjadi salah satu jenis berikut:

  • string, yang memungkinkan Anda memasukkan teks arbitrer.
  • int, yang memungkinkan Anda memasukkan angka.
  • bool, yang mewakili nilai Boolean (benar atau salah).
  • object dan array, yang mewakili data dan daftar terstruktur.

Objek

Anda dapat menggunakan parameter objek untuk menggabungkan data terstruktur bersama-sama di satu tempat. Objek dapat memiliki beberapa properti dari jenis yang berbeda. Anda dapat menggunakan objek dalam definisi sumber daya, dalam variabel, atau dalam ekspresi dalam file Bicep Anda. Berikut adalah contoh objek:

param appServicePlanSku object = {
  name: 'F1'
  tier: 'Free'
  capacity: 1
}

Parameter ini adalah objek dengan dua properti string, name dan tier, serta properti bilangan bulat, capacity. Perhatikan bahwa masing-masing properti berada di jalurnya sendiri.

Saat Anda mereferensikan parameter dalam templat, Anda dapat memilih properti individual objek menggunakan titik yang diikuti dengan nama properti, seperti dalam contoh ini:

resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku.name
    tier: appServicePlanSku.tier
    capacity: appServicePlanSku.capacity
  }
}

Penting

Ingat bahwa Anda tidak menentukan jenis masing-masing properti dalam objek. Namun, ketika Anda menggunakan nilai properti, jenisnya harus sesuai dengan apa yang diharapkan. Dalam contoh sebelumnya, nama dan tingkat SKU paket App Service harus berupa string.

Contoh lain tempat Anda mungkin menggunakan parameter objek adalah untuk menentukan tag sumber daya. Anda dapat melampirkan metadata tag kustom ke sumber daya yang Anda sebarkan, yang dapat Anda gunakan untuk mengidentifikasi informasi penting tentang sumber daya.

Tag berguna untuk skenario seperti melacak tim mana yang memiliki sumber daya, atau ketika sumber daya termasuk ke dalam lingkungan produksi atau non-produksi. Biasanya, Anda akan menggunakan tag yang berbeda untuk setiap lingkungan, tetapi Anda harus menggunakan kembali nilai tag yang sama pada semua sumber daya dalam templat Anda. Untuk alasan ini, tag sumber daya adalah penggunaan yang baik untuk parameter objek, seperti dalam contoh ini:

param resourceTags object = {
  EnvironmentName: 'Test'
  CostCenter: '1000100'
  Team: 'Human Resources'
}

Setiap kali Anda menentukan sumber daya dalam file Bicep, Anda dapat menggunakannya kembali di mana pun Anda menentukan properti tags:

resource appServicePlan 'Microsoft.Web/serverfarms@2022-03-01' = {
  name: appServicePlanName
  location: location
  tags: resourceTags
  sku: {
    name: 'S1'
  }
}

resource appServiceApp 'Microsoft.Web/sites@' = {
  name: appServiceAppName
  location: location
  tags: resourceTags
  kind: 'app'
  properties: {
    serverFarmId: appServicePlan.id
  }
}

Larik

Array adalah daftar item. Sebagai contoh, Anda dapat menggunakan array nilai string untuk menyatakan daftar alamat email untuk grup tindakan Azure Monitor. Anda juga dapat menggunakan array objek untuk mewakili daftar subnet untuk jaringan virtual.

Catatan

Anda tidak dapat menentukan jenis item individual yang perlu dimuat array. Misalnya, Anda tidak dapat menentukan bahwa array harus berisi string.

Mari lihat contoh berikut. Azure Cosmos DB memungkinkan Anda membuat akun database yang mencakup beberapa wilayah, dan secara otomatis menangani replikasi data untuk Anda. Saat Anda menyebarkan akun database baru, Anda perlu menentukan daftar wilayah Azure yang Anda inginkan untuk menyebarkan akun tersebut. Sering kali, Anda harus memiliki daftar lokasi yang berbeda untuk lingkungan yang berbeda. Misalnya, untuk menghemat uang di lingkungan pengujian, Anda mungkin hanya menggunakan satu atau dua lokasi. Namun, di lingkungan produksi Anda, Anda mungkin menggunakan beberapa lokasi.

Anda dapat membuat parameter array yang menentukan daftar lokasi:

param cosmosDBAccountLocations array = [
  {
    locationName: 'australiaeast'
  }
  {
    locationName: 'southcentralus'
  }
  {
    locationName: 'westeurope'
  }
]

Tip

Contoh sebelumnya adalah array objek. Setiap objek memiliki properti locationName, yang diharapkan oleh Azure Cosmos DB. Ketika Anda bekerja dengan definisi sumber daya di Visual Studio Code, Anda dapat mulai dengan memasukkan properti sumber daya sehingga Anda mendapatkan IntelliSense dari alat Bicep. Anda dapat membuat beberapa nilai contoh menggunakan pendekatan ini. Setelah Anda puas dengan konfigurasi, pindahkan bagian kode Bicep ke parameter. Dengan cara ini, Anda dapat mengganti properti yang dikodekan secara permanen dengan parameter yang dapat diubah selama masing-masing penyebaran, sambil tetap memastikan bahwa sumber daya dikonfigurasi dengan benar.

Saat Anda menyatakan sumber daya Azure Cosmos DB, sekarang Anda dapat mereferensikan parameter array:

resource account 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  name: accountName
  location: location
  properties: {
    locations: cosmosDBAccountLocations
  }
}

Selanjutnya mudah untuk menggunakan nilai parameter yang berbeda untuk lingkungan pengembangan Anda dengan mengubah nilai parameter. Anda akan segera mempelajari bagaimana Anda dapat memberikan nilai parameter yang berbeda tanpa memodifikasi templat asli Anda.

Menentukan daftar nilai yang diizinkan

Terkadang Anda perlu memastikan parameter memiliki nilai tertentu. Misalnya, tim Anda mungkin memutuskan paket App Service produksi harus disebarkan menggunakan SKU Premium v3. Untuk menerapkan aturan ini, Anda dapat menggunakan dekorator parameter @allowed. Dekorator parameter adalah cara untuk memberi Bicep informasi tentang nilai parameter yang diperlukan. Berikut adalah bagaimana parameter string bernama appServicePlanSkuName dapat dibatasi sehingga hanya beberapa nilai tertentu yang dapat ditetapkan:

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
param appServicePlanSkuName string

Tip

Gunakan dekorator @allowed dengan hemat. Jika Anda menggunakan dekorator ini terlalu luas, Anda dapat memblokir penyebaran yang valid jika Anda tidak selalu memperbarui daftar. Contoh sebelumnya hanya memungkinkan Premium v3 dalam produksi. Jika Anda harus menggunakan templat yang sama untuk menyebarkan beberapa lingkungan non-produksi yang lebih murah, daftar nilai yang diizinkan mungkin menghentikan Anda menggunakan SKU lain yang perlu Anda gunakan.

Membatasi panjang dan nilai parameter

Saat Anda menggunakan parameter string, Anda sering kali perlu membatasi panjang string. Mari kita pertimbangkan contoh penamaan sumber daya Azure. Semua jenis sumber daya Azure memiliki batasan seputar panjang namanya. Ini adalah praktik yang baik untuk menentukan panjang karakter minimum dan maksimum untuk parameter yang mengontrol penamaan, untuk menghindari kesalahan selama penyebaran nanti. Anda dapat menggunakan dekorator @minLength dan @maxLength untuk panjang karakter minimum dan maksimum yang ingin Anda izinkan untuk parameter.

Berikut adalah contoh yang menyatakan parameter string bernama storageAccountName, yang panjangnya hanya bisa antara 5 dan 24 karakter:

@minLength(5)
@maxLength(24)
param storageAccountName string

Parameter ini mencakup dua dekorator. Anda dapat menerapkan beberapa dekorator ke parameter dengan menempatkan setiap dekorator pada garisnya sendiri.

Catatan

Anda juga dapat menerapkan dekorator @minLength dan @maxLength ke parameter array, untuk mengontrol berapa banyak item yang diizinkan berada dalam array.

Saat Anda bekerja dengan parameter numerik, Anda mungkin memerlukan nilai untuk berada dalam rentang tertentu. Misalnya, perusahaan mainan Anda mungkin memutuskan bahwa setiap kali ada yang menyebarkan paket App Service, mereka harus selalu menyebarkan setidaknya satu instans, tetapi tidak lebih dari 10 instans paket. Untuk memenuhi persyaratan, Anda dapat menggunakan dekorator @minValue dan @maxValue untuk menentukan nilai minimum dan maksimum yang diizinkan. Contoh berikut menyatakan parameter bilangan bulat appServicePlanInstanceCount yang nilainya hanya bisa antara 1 dan 10 (inklusif):

@minValue(1)
@maxValue(10)
param appServicePlanInstanceCount int

Menambahkan deskripsi ke parameter

Parameter adalah cara yang bagus untuk membuat templat Anda dapat digunakan kembali oleh orang lain. Saat mereka menggunakan templat Anda, mereka harus memahami fungsi setiap parameter sehingga mereka dapat memberikan nilai yang tepat. Bicep menyediakan dekorator @description sehingga Anda dapat mendokumentasikan tujuan parameter Anda dengan cara yang dapat dibaca manusia.

@description('The locations into which this Cosmos DB account should be configured. This parameter needs to be a list of objects, each of which has a locationName property.')
param cosmosDBAccountLocations array

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.

Catatan

Templat Bicep terkadang dapat disediakan di portal Microsoft Azure untuk disebarkan pengguna, seperti saat Anda menggunakan spesifikasi templat. Portal menggunakan deskripsi dan dekorator lain pada parameter untuk membantu pengguna memahami apa yang perlu menjadi nilai parameter.