Parameter dalam Bicep

  • Artikel

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.

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.

Anda dibatasi hingga 256 parameter dalam file Bicep. Untuk informasi selengkapnya, lihat Batas templat.

Untuk praktik terbaik parameter, lihat Parameter.

Sumber daya pelatihan

Jika Anda ingin mempelajari parameter melalui panduan langkah demi langkah, lihat Membangun template Bicep yang dapat digunakan kembali dengan menggunakan parameter.

Deklarasi

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

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 file .bicepparam. Dalam file .bicepparam, Anda tidak perlu menentukan jenis data seperti yang didefinisikan dalam file Bicep.

param <parameter-name> = <value>

Untuk informasi selengkapnya, lihat File parameter.

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.

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

Dekorator

Parameter menggunakan dekorator untuk batasan atau metadata. Dekorator berformat @expression dan ditempatkan di atas deklarasi parameter. Anda dapat menandai parameter sebagai aman, menentukan nilai yang diizinkan, mengatur panjang minimum dan maksimum untuk untai (karakter), mengatur nilai minimum dan maksimum untuk bilangan bulat, dan memberikan deskripsi parameter.

Contoh berikut menunjukkan dua kegunaan umum untuk dekorator.

@secure()
param demoPassword string

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

Tabel berikut ini menjelaskan dekorator yang tersedia dan cara menggunakannya.

Dekorator Terapkan ke Argumen Deskripsi
diizinkan all array Nilai yang diizinkan untuk parameter. Gunakan dekorator ini untuk memastikan pengguna memberikan nilai yang benar.
description all string Teks yang menjelaskan cara menggunakan parameter. Deskripsi ditampilkan kepada pengguna melalui portal.
maxLength array, untai (karakter) int Panjang maksimum untuk parameter untai (karakter) dan array. Nilainya inklusif.
maxValue int int Nilai maksimum untuk parameter bilangan bulat. Nilai ini inklusif.
metadata all object Properti kustom untuk diterapkan ke parameter. Dapat mencakup properti deskripsi yang setara dengan dekorator deskripsi.
minLength array, untai (karakter) int Panjang minimum untuk parameter untai (karakter) dan array. Nilainya inklusif.
minValue int int Nilai minimum untuk parameter bilangan bulat. Nilai ini inklusif.
aman untai (karakter), 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.

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

Dekorator yang tersedia dijelaskan di bagian berikut.

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

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.

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

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

Deskripsi

Untuk membantu pengguna memahami nilai yang akan diberikan, tambahkan deskripsi ke parameter. Saat pengguna menyebarkan templat melalui portal, teks deskripsi 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:

Gunakan teks terformat Markdown di VSCode

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

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.

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

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@2020-06-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