Parameter dalam Bicep

Artikel ini menjelaskan cara menentukan dan menggunakan parameter dalam file Bicep. Dengan menyediakan nilai parameter yang berbeda, Anda dapat menggunakan kembali file Bicep terhadap lingkungan yang berbeda.

Azure Resource Manager menyelesaikan nilai parameter sebelum memulai operasi penyebaran. Di mana pun parameter digunakan, Resource Manager menggantinya dengan nilai yang diselesaikan.

Setiap parameter harus diatur ke salah satu jenis data.

Bicep memungkinkan maksimum 256 parameter. Untuk informasi selengkapnya, lihat Batas templat.

Untuk praktik terbaik parameter, lihat Parameter.

Sumber daya pelatihan

Lihat Templat Bicep yang dapat digunakan kembali build dengan menggunakan parameter Pelajari modul untuk panduan langkah demi langkah tentang parameter.

Tentukan parameter

Setiap parameter memiliki nama dan jenis data. Atau, Anda dapat memberikan nilai default untuk parameter.

@<decorator>(<argument>)
param <parameter-name> <parameter-data-type> = <default-value>

Parameter tidak boleh memiliki nama yang sama dengan variabel, sumber daya, output, atau parameter lain dalam cakupan yang sama.

Contoh berikut menunjukkan deklarasi dasar parameter.

param demoString string
param demoInt int
param demoBool bool
param demoObject object
param demoArray array

Kata param kunci juga digunakan dalam .bicepparam file. Anda tidak perlu menentukan jenis data dalam .bicepparam file karena ditentukan dalam file Bicep.

param <parameter-name> = <value>

Ekspresi jenis yang ditentukan pengguna dapat digunakan sebagai klausul param jenis pernyataan. Contohnya:

param storageAccountConfig {
  name: string
  sku: string
}

Untuk informasi selengkapnya, lihat Jenis data yang ditentukan pengguna.

Mengatur nilai default

Anda dapat menentukan nilai default untuk parameter. Nilai default digunakan saat nilai tidak diberikan selama penyebaran.

param demoParam string = 'Contoso'

Anda dapat menggunakan ekspresi dengan nilai default. Ekspresi tidak diperbolehkan dengan properti parameter lainnya. Anda tidak dapat menggunakan fungsi referensi atau fungsi daftar apa pun di bagian parameter. Fungsi tersebut mendapatkan status runtime sumber daya, dan tidak dapat dijalankan sebelum penyebaran saat parameter diselesaikan.

param location string = resourceGroup().location

Anda dapat menggunakan nilai parameter lain untuk membangun nilai default. Templat berikut menyusun nama paket host dari nama situs.

param siteName string = 'site${uniqueString(resourceGroup().id)}'
param hostingPlanName string = '${siteName}-plan'

output siteNameOutput string = siteName
output hostingPlanOutput string = hostingPlanName

Namun, Anda tidak dapat mereferensikan variabel sebagai nilai default.

Menggunakan dekorator

Parameter menggunakan dekorator untuk batasan atau metadata. Dekorator berformat @expression dan ditempatkan di atas deklarasi parameter. Tabel berikut menunjukkan dekorator yang tersedia untuk parameter.

Dekotaror berada dalam namespace layanan sys. Jika Anda perlu membedakan suatu dekorator dari item lainnya dengan nama yang sama, awali dekorator dengan sys. Contohnya, jika file Bicep Anda mencakup parameter bernama description, Anda harus menambahkan namespace layanan sys saat menggunakan dekorator deskripsi.

@sys.description('The name of the instance.')
param name string
@sys.description('The description of the instance to display.')
param description string

Nilai yang diizinkan

Anda dapat menentukan nilai yang diizinkan untuk parameter. Anda memberikan nilai yang diizinkan dalam array. Penyebaran gagal selama validasi jika nilai diteruskan untuk parameter yang bukan salah satu nilai yang diizinkan.

@allowed([
  'one'
  'two'
])
param demoEnum string

Jika Anda menentukan nilai yang diizinkan untuk parameter array, nilai aktual dapat menjadi subset dari nilai yang diizinkan.

Deskripsi

Untuk membantu pengguna memahami nilai yang akan diberikan, tambahkan deskripsi ke parameter. Saat pengguna menyebarkan templat melalui portal Azure, teks deskripsi secara otomatis digunakan sebagai tip untuk parameter tersebut. Hanya tambahkan deskripsi ketika teks memberikan lebih banyak informasi daripada yang dapat disimpulkan dari nama parameter.

@description('Must be at least Standard_A3 to support 2 NICs.')
param virtualMachineSize string = 'Standard_DS1_v2'

Teks berformat markdown dapat digunakan untuk teks deskripsi:

@description('''
Storage account name restrictions:
- Storage account names must be between 3 and 24 characters in length and may contain numbers and lowercase letters only.
- Your storage account name must be unique within Azure. No two storage accounts can have the same name.
''')
@minLength(3)
@maxLength(24)
param storageAccountName string

Saat mengarahkan kursor ke storageAccountName di Visual Studio Code, Anda akan melihat teks yang diformat:

Pastikan teks mengikuti pemformatan Markdown yang tepat; jika tidak, mungkin tidak ditampilkan dengan benar saat dirender.

Diskriminator

Lihat Jenis data union yang ditandai kustom.

Batasan bilangan bulat

Anda dapat mengatur nilai minimum dan maksimum untuk parameter bilangan bulat. Anda dapat mengatur salah satu atau kedua batasan.

@minValue(1)
@maxValue(12)
param month int

Batasan panjang

Anda dapat menentukan panjang minimum dan maksimum untuk parameter string dan array. Anda dapat mengatur salah satu atau kedua batasan. Untuk string, panjangnya menunjukkan jumlah karakter. Untuk array, panjangnya menunjukkan jumlah item dalam array.

Contoh berikut menjelaskan dua parameter. Salah satu parameter adalah untuk nama akun penyimpanan yang harus memiliki 3-24 karakter. Parameter lainnya adalah array yang harus memiliki dari 1-5 item.

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

@minLength(1)
@maxLength(5)
param appNames array

Metadata

Tambahkan dekorator metadata jika Anda memiliki properti kustom yang ingin Anda terapkan ke parameter. Dalam metadata, tentukan objek dengan nama dan nilai kustom. Objek yang Anda tentukan untuk metadata dapat berisi properti nama dan jenis apa pun.

Anda dapat menggunakan dekorator ini untuk melacak informasi mengenai parameter yang tidak masuk akal untuk ditambahkan ke deskripsi.

@description('Configuration values that are applied when the application starts.')
@metadata({
  source: 'database'
  contact: 'Web team'
})
param settings object

Ketika Anda menyediakan @metadata() dekorator dengan properti yang bertentangan dengan dekorator lain, dekorator itu selalu lebih diutamakan daripada apa pun di @metadata() dekorator. Jadi, properti yang bertentangan dalam @metadata() nilai berlebihan dan akan diganti. Untuk informasi selengkapnya, lihat Tidak ada metadata yang bertentangan.

Disegel

Lihat Meningkatkan tingkat kesalahan.

Parameter aman

Anda dapat menandai parameter string atau objek sebagai aman. Nilai parameter aman tidak disimpan ke riwayat penyebaran dan tidak dicatat.

@secure()
param demoPassword string

@secure()
param demoSecretObject object

Ada beberapa aturan linter yang terkait dengan dekorator ini: Parameter aman default, Parameter aman dalam penyebaran berlapis, Rahasia aman dalam parameter.

Menggunakan parameter

Untuk mereferensikan nilai untuk parameter, gunakan nama parameter. Contoh berikut menggunakan nilai parameter untuk nama brankas kunci.

param vaultName string = 'keyVault${uniqueString(resourceGroup().id)}'

resource keyvault 'Microsoft.KeyVault/vaults@2019-09-01' = {
  name: vaultName
  ...
}

Menggunakan objek sebagai parameter

Mungkin lebih mudah untuk mengatur nilai-nilai terkait dengan meneruskannya sebagai objek. Pendekatan ini juga mengurangi jumlah parameter dalam templat.

Contoh berikut menunjukkan parameter yang merupakan objek. Nilai default menunjukkan properti yang diharapkan untuk objek. Properti tersebut digunakan saat menentukan sumber daya untuk disebarkan.

param vNetSettings object = {
  name: 'VNet1'
  location: 'eastus'
  addressPrefixes: [
    {
      name: 'firstPrefix'
      addressPrefix: '10.0.0.0/22'
    }
  ]
  subnets: [
    {
      name: 'firstSubnet'
      addressPrefix: '10.0.0.0/24'
    }
    {
      name: 'secondSubnet'
      addressPrefix: '10.0.1.0/24'
    }
  ]
}

resource vnet 'Microsoft.Network/virtualNetworks@2023-11-01' = {
  name: vNetSettings.name
  location: vNetSettings.location
  properties: {
    addressSpace: {
      addressPrefixes: [
        vNetSettings.addressPrefixes[0].addressPrefix
      ]
    }
    subnets: [
      {
        name: vNetSettings.subnets[0].name
        properties: {
          addressPrefix: vNetSettings.subnets[0].addressPrefix
        }
      }
      {
        name: vNetSettings.subnets[1].name
        properties: {
          addressPrefix: vNetSettings.subnets[1].addressPrefix
        }
      }
    ]
  }
}

Langkah berikutnya

• Untuk mempelajari tentang properti yang tersedia untuk parameter, lihat Memahami struktur dan sintaks file Bicep.
• Untuk mempelajari tentang meneruskan nilai parameter sebagai file, lihat Membuat file parameter untuk penyebaran Bicep.
• Untuk mempelajari tentang menyediakan nilai parameter saat penyebaran, lihat Menyebarkan file Bicep dengan Azure CLI dan Azure PowerShell.