Paraméterek a Bicepben

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 részletes útmutatásért tekintse meg a Build újrahasználható Bicep-sablonjait a Learn modul paraméterekkel.

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.

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. Nem használhatja a referenciafüggvényt vagy a paraméterek szakaszban található listafüggvényeket . 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 gazdagépterv-nevet hoz 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. A dekorátorok formátuma @expression a paraméter deklarációja fölé kerül. Az alábbi táblázat a paraméterekhez elérhető dekorátorokat mutatja be.

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: . Ha például a Bicep-fájl tartalmaz egy elnevezett descriptionparamétert, akkor a leírás-dekorátor használatakor hozzá kell adnia a sys névteret.

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

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.

Diszkriminatív

Lásd: Egyéni címkével ellátott egyesítő adattípus.

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 elemből állhat.

@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 dekoratőrnek @metadata() olyan tulajdonságot ad meg, amely ütközik egy másik dekoratorral, az a dekorátor mindig elsőbbséget élvez a @metadata() dekorátor minden tulajdonságával szemben. Az értéken belüli @metadata() ütköző tulajdonság tehát redundáns, és lecserélődik. További információ: Nem ütköző metaadatok.

Lezárt

Lásd: Elevate error level.

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: A biztonságos paraméter alapértelmezett értéke, a beágyazott üzemelő példányok biztonságos paraméterei, a paraméterek titkos kulcsainak védelme.

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 számító 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ájlok szerkezetének és szintaxisának ismertetése című témakörben olvashat.
• A paraméterértékek fájlként való átadásáról további információt a Paraméterfájlok 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.