Parameters in Bicep

Ez a cikk azt ismerteti, hogyan definiálhat és használhat paramétereket egy Bicep-fájlban. A paraméterek különböző értékeinek megadásával újra felhasználhatja a Bicep-fájlokat a különböző környezetekhez.

Az Azure Resource Manager az üzembe helyezési műveletek megkezdése előtt feloldja a paraméterértékeket. Bárhol is használja a paramétert, a Resource Manager lecseréli a feloldott értékre.

Minden paramétert az egyik adattípusra kell állítani.

A Bicep legfeljebb 256 paramétert engedélyez. További információ: Sablonkorlátok.

A paraméterekkel kapcsolatos ajánlott eljárásokért tekintse meg a Paraméterek című témakört.

Képzési erőforrások

A paraméterekkel kapcsolatos lépésről-lépésre útmutatásért tekintse meg a Paraméterek segítségével újrahasználható Bicep sablonok készítése című modul a Learn oldalon.

Paraméterek megadása

Minden paraméter rendelkezik névvel és adattípussal. Opcionálisan megadhat egy alapértelmezett értéket a paraméterhez.

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

Egy paraméter neve nem lehet azonos egy változóval, erőforrással, kimenettel vagy más paraméterrel ugyanabban a hatókörben.

Az alábbi példa a paraméterek alapvető deklarációit mutatja be.

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

A param kulcsszó fájlokban .bicepparamis használatos. Nem kell megadnia az adattípust a fájlokban .bicepparam , mivel az Bicep-fájlokban van definiálva.

param <parameter-name> = <value>

A felhasználó által definiált típuskifejezések egy utasítás típusmondataként param használhatók. Példa:

param storageAccountConfig {
  name: string
  sku: string
}

További információ: Felhasználó által definiált adattípusok a Bicepben.

Alapértelmezett értékek beállítása

Megadhatja egy paraméter alapértelmezett értékét. Az alapértelmezett érték akkor használatos, ha az üzembe helyezés során nincs megadva érték.

param demoParam string = 'Contoso'

Az alapértelmezett értékkel rendelkező kifejezéseket használhatja. A kifejezések más paramétertulajdonságokkal nem használhatók. A paraméterek szakaszban nem használhatja a reference függvényt vagy bármelyik list függvényt. Ezek a függvények lekérik az erőforrás futtatókörnyezeti állapotát, és nem hajthatók végre az üzembe helyezés előtt a paraméterek feloldásakor.

param location string = resourceGroup().location

Egy másik paraméterértéket is használhat egy alapértelmezett érték létrehozásához. Az alábbi sablon egy hosztingterv nevét hozza létre a webhely nevéből.

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

output siteNameOutput string = siteName
output hostingPlanOutput string = hostingPlanName

A változókra azonban nem hivatkozhat alapértelmezett értékként.

Dekorátorok használata

A paraméterek dekorátorokat használnak a korlátozásokhoz vagy metaadatokhoz. The decorators are in the format @expression and are placed above the parameter's declaration. Az alábbi táblázat a paraméterekhez elérhető dekorátorokat mutatja be:

Lakberendező	Apply to	Argumentum	Leírás
allowed	all	array	Ezzel a dekorátorsal győződjön meg arról, hogy a felhasználó helyes értékeket ad meg. This decorator is only permitted on param statements. Ha azt szeretné deklarálni, hogy egy tulajdonságnak az előre meghatározott értékek egyikének kell lennie egy type vagy output utasításban, használja az unió típus szintaxisát. Union type syntax can also be used in param statements.
leírás	all	string	A paraméter használatát ismertető szöveg. A leírás az Azure Portalon jelenik meg a felhasználók számára.
diszkriminátor	object	string	Ezzel a dekorátor használatával győződjön meg arról, hogy a megfelelő alosztályt azonosítja és kezeli. További információ: Egyéni címkével ellátott egyesítő adattípus.
maxLength	array, string	int	A sztring- és tömbparaméterek maximális hossza. The value is inclusive.
maxValue	int	int	Az egész szám paraméter maximális értéke. This value is inclusive.
metaadatok	all	object	A paraméterre alkalmazandó egyéni tulajdonságok. Olyan leírástulajdonságokat is tartalmazhat, amelyek egyenértékűek a leírás dekorátorával.
minLength	array, string	int	A sztring- és tömbparaméterek minimális hossza. The value is inclusive.
minValue	int	int	Az egész szám paraméter minimális értéke. This value is inclusive.
lezárt	object	Nincs	Elevate BCP089 from a warning to an error when a property name of a use-define data type is likely a typo. További információ: Hibaszint emelés.
biztonságos	sztring, objektum	Nincs	A paramétert biztonságosként jelöli meg. A biztonságos paraméter értékét a rendszer nem menti az üzembe helyezési előzményekbe, és nincs naplózva. További információ: Biztonságos sztringek és objektumok.

A dekorátorok a sys névtérben találhatók. Ha meg kell különböztetnie egy dekoratőrt egy másik, azonos nevű elemtől, akkor a dekoratőrt a következővel kell előtagolnia sys: . For example, if your Bicep file includes a parameter named description, you must add the sys namespace when using the description decorator.

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

Megengedett értékek

Paraméterhez megadhat engedélyezett értékeket. Megadhatja az engedélyezett értékeket egy tömbben. Az üzembe helyezés sikertelen az ellenőrzés során, ha egy olyan értéket ad át a paraméternek, amely nem az engedélyezett értékek egyike.

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

Ha egy tömbparaméterhez engedélyezett értékeket határoz meg, a tényleges érték az engedélyezett értékek bármely részhalmaza lehet.

Leírás

Annak érdekében, hogy a felhasználók megértsék a megadható értéket, adjon hozzá egy leírást a paraméterhez. Amikor egy felhasználó üzembe helyezi a sablont az Azure Portalon keresztül, a rendszer automatikusan a leírás szövegét használja a paraméter tippjeként. Csak akkor adjon hozzá leírást, ha a szöveg több információt tartalmaz, mint amennyit a paraméter nevéből lehet következtetni.

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

Markdown formátumú szöveg használható a leírás szövegéhez:

@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

Amikor a kurzort a StorageAccountName fölé viszi a Visual Studio Code-ban, megjelenik a formázott szöveg:

Győződjön meg arról, hogy a szöveg a megfelelő Markdown-formázást követi; ellenkező esetben előfordulhat, hogy a megjelenítéskor nem jelenik meg megfelelően.

Diszkriminátor

See Custom-tagged union data type.

Egész számra vonatkozó korlátozások

Az egész számparaméterek minimális és maximális értékeit megadhatja. Beállíthat egy vagy mindkét korlátozást.

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

Hosszkorlátozások

Megadhatja a sztring- és tömbparaméterek minimális és maximális hosszát. Beállíthat egy vagy mindkét korlátozást. Sztringek esetén a hossz a karakterek számát jelzi. Tömbök esetén a hossz a tömb elemeinek számát jelzi.

Az alábbi példa két paramétert deklarál. Az egyik paraméter egy 3–24 karakter hosszúságú tárfióknév. A másik paraméter egy tömb, amely 1–5 elemet tartalmaz.

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

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

Metaadatok

Ha egyéni tulajdonságokat szeretne alkalmazni egy paraméterre, adjon hozzá egy metaadat-dekorátort. A metaadatokon belül definiáljon egy egyéni neveket és értékeket tartalmazó objektumot. A metaadatokhoz definiált objektum bármilyen nevet és típust tartalmazhat.

Ezt a dekorátort arra használhatja, hogy nyomon kövesse annak a paraméternek az adatait, amelyet nem érdemes hozzáadni a leíráshoz.

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

Ha egy dekorátornak @metadata() olyan tulajdonságot ad meg, amely ütközik egy másik dekorátorral, az a dekorátor mindig elsőbbséget élvez a @metadata() dekorátor bármely tulajdonságával szemben, így az @metadata() értéken belüli ütköző tulajdonság feleslegessé válik, és lecserélésre kerül. További információ: Linter-szabály – nem ütköző metaadatok.

Lezárt

Lásd: Hibaszint növelése.

Biztonságos paraméterek

A sztring- vagy objektumparamétereket biztonságosként jelölheti meg. A biztonságos paraméter értékét a rendszer nem menti az üzembe helyezési előzményekbe, és nincs naplózva.

@secure()
param demoPassword string

@secure()
param demoSecretObject object

A dekoratőrhöz több linter-szabály is kapcsolódik: Biztonságos paraméter alapértelmezés, Beágyazott üzembe helyezések biztonságos paraméterei, Paraméterek biztonságos szekréciói.

Paraméterek használata

Ha egy paraméter értékére szeretne hivatkozni, használja a paraméter nevét. Az alábbi példa egy paraméterértéket használ egy kulcstartónévhez.

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

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

Objektumok használata paraméterekként

Egyszerűbben rendszerezheti a kapcsolódó értékeket, ha objektumként adja át őket. Ez a módszer a sablonban lévő paraméterek számát is csökkenti.

Az alábbi példa egy objektumnak megfelelő paramétert mutat be. Az alapértelmezett érték az objektum várt tulajdonságait jeleníti meg. Ezeket a tulajdonságokat a rendszer az üzembe helyezendő erőforrás meghatározásakor használja.

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

Következő lépések

• A paraméterekhez elérhető tulajdonságokról a Bicep-fájlstruktúra és a szintaxis című témakörben tájékozódhat.
• A paraméterértékek fájlként való átadásáról további információt a Paraméterfájl létrehozása a Bicep üzembe helyezéséhez című témakörben talál.
• A paraméterértékek üzembe helyezéskor történő megadásáról további információt a Bicep-fájlok üzembe helyezése az Azure CLI-vel és az Azure PowerShell-lel című témakörben talál.