Bagikan melalui

Parameter dalam Bicep

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

Azure Resource Manager menyelesaikan nilai parameter sebelum memulai operasi penyebaran. Setiap kali parameter digunakan, Resource Manager menggantinya dengan nilai yang telah diproses.

Setiap parameter harus diatur ke salah satu jenis data.

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

Untuk praktik terbaik parameter, lihat Parameter.

Tentukan parameter

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

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

Parameter tidak dapat 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 file .bicepparam karena ditentukan dalam file Bicep.

param <parameter-name> = <value>

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

param storageAccountConfig {
  name: string
  sku: string
}

Untuk informasi selengkapnya, lihat Jenis Data yang Ditentukan Pengguna di Bicep.

Mengatur nilai default

Anda dapat menentukan nilai default untuk parameter. Nilai default digunakan ketika suatu nilai tidak diberikan selama proses penyebaran.

param demoParam string = 'Contoso'

Anda dapat menggunakan ekspresi dengan nilai default. Ekspresi tidak diperbolehkan dengan properti parameter lainnya. Anda tidak dapat menggunakan reference fungsi atau fungsi apa pun list di bagian parameter. Fungsi-fungsi ini 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 dalam format @expression dan ditempatkan di atas deklarasi parameter. Tabel berikut ini memperlihatkan dekorator yang tersedia untuk parameter:

Dekorator Aplikasikan pada Argumen Deskripsi
Diperbolehkan semua array Gunakan dekorator ini untuk memastikan pengguna memberikan nilai yang benar. Dekorator ini hanya diizinkan pada param pernyataan. Untuk menyatakan bahwa properti harus merupakan salah satu dari sekumpulan nilai yang telah ditentukan sebelumnya dalam pernyataan type atau output , gunakan sintaks jenis union. Sintaks jenis union juga dapat digunakan dalam param pernyataan.
deskripsi semua string Teks yang menjelaskan cara menggunakan parameter . Deskripsi ditampilkan kepada pengguna di portal Azure.
diskriminator objek string Gunakan dekorator ini untuk memastikan subkelas yang benar diidentifikasi dan dikelola. Untuk informasi selengkapnya, lihat Tipe data gabungan bertanda khusus.
maxLength larik, teks int (integer) Panjang maksimum untuk parameter string dan array. Nilainya inklusif.
maxValue int (integer) int (integer) Nilai maksimum untuk parameter bilangan bulat. Nilai ini inklusif.
metadata semua objek Properti kustom untuk diterapkan ke parameter. Dapat mencakup properti deskripsi yang setara dengan dekorator deskripsi.
minLength larik, teks int (integer) Panjang minimum untuk parameter string dan array. Nilainya inklusif.
minValue int (integer) int (integer) Nilai minimum untuk parameter bilangan bulat. Nilai ini inklusif.
disegel objek tidak ada Tingkatkan BCP089 dari peringatan ke kesalahan ketika nama properti dari tipe data yang ditentukan penggunaannya kemungkinan merupakan salah ketik. Untuk informasi selengkapnya, lihat Tingkatkan level kesalahan.
aman string, objek tidak ada Menandai parameter sebagai aman. Nilai parameter aman tidak disimpan ke riwayat penyebaran dan tidak dicatat ke dalam log. Untuk informasi lebih lanjut, lihat Untai (karakter) dan objek yang aman.

Dekorator berada di namespace sys. Jika Anda perlu membedakan suatu dekorator dari item lainnya dengan nama yang sama, awali dekorator dengan sys. Misalnya, jika file Bicep Anda menyertakan parameter bernama description, Anda harus menambahkan namespace sys saat menggunakan dekorator description.

@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 diberikan 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 can only contain numbers and lowercase letters.
- 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 Anda mengarahkan kursor ke storageAccountName di Visual Studio Code, Anda akan melihat teks yang diformat:

Menggunakan teks berformat Markdown dalam Visual Studio Code

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

Diskriminator

Lihat Jenis data union berpenanda khusus.

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 parameternya adalah untuk nama akun penyimpanan yang harus memiliki 3 hingga 24 karakter. Parameter lainnya adalah array yang harus memiliki 1 hingga 5 item.

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

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

Metainformasi

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

Anda mungkin menggunakan dekorator ini untuk melacak informasi tentang 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 dekorator @metadata() apa pun, yang akan membuat properti yang bertentangan dalam nilai @metadata() menjadi redundan dan akan diganti. Untuk informasi selengkapnya, lihat aturan Linter - tidak ada metadata yang bertentangan.

Disegel

Lihat Meningkatkan tingkat kesalahan.

Parameter aman

Anda dapat menandai parameter string atau objek sebagai aman. Ketika parameter dihiasi dengan @secure(), Azure Resource Manager memperlakukan nilai parameter sebagai sensitif, mencegahnya dicatat atau ditampilkan dalam riwayat penyebaran, portal Azure, atau output baris perintah.

@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.

Gunakan 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@2025-05-01' = {
  name: vaultName
  ...
}

Dekorator @secure() hanya valid untuk parameter jenis string atau objek, karena ini selaras dengan jenis secureString dan secureObject dalam templat ARM. Untuk meneruskan array atau angka dengan aman, bungkus dalam secureObject atau serialisasikan sebagai secureString.

Menggunakan objek sebagai parameter

Kita lebih mudah mengatur nilai-nilai terkait dengan memasukkannya 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@2025-01-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 selanjutnya

  • Last updated on