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.

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

Egy Bicep-fájlban legfeljebb 256 paraméter szerepelhet. 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

Ha lépésről lépésre szeretne többet megtudni a paraméterekről, tekintse meg az újrafelhasználható Bicep-sablonok paraméterekkel történő összeállítását ismertető témakört.

Nyilatkozat

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

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ó a .bicepparam fájlokban is használatos. A .bicepparam-fájlokban nem kell megadnia az adattípust, mivel az bicep-fájlokban van definiálva.

param <parameter-name> = <value>

További információ: Parameters file.

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

param storageAccountConfig {
  name: string
  sku: string
}

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

Default value

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

Dekorátorok

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. A paramétereket biztonságosként jelölheti meg, megadhatja az engedélyezett értékeket, beállíthatja egy sztring minimális és maximális hosszát, beállíthatja egy egész szám minimális és maximális értékét, és megadhatja a paraméter leírását.

Az alábbi példa két gyakori felhasználási módszert mutat be a dekorátorok számára.

@secure()
param demoPassword string

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

Az alábbi táblázat a rendelkezésre álló dekorátorokról és azok használatáról szól.

Dekoratőr Alkalmazás Argumentum Description
Engedélyezett mind array A paraméter engedélyezett értékei. Ezzel a dekorátorsal győződjön meg arról, hogy a felhasználó helyes értékeket ad meg.
leírás mind sztring A paraméter használatát ismertető szöveg. A leírás a portálon keresztül jelenik meg a felhasználók számára.
Maxlength tömb, sztring egész A sztring- és tömbparaméterek maximális hossza. Az érték befogadó.
maxValue egész egész Az egész szám paraméter maximális értéke. Ez az érték a befogadó.
metaadatok mind 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 tömb, sztring egész A sztring- és tömbparaméterek minimális hossza. Az érték befogadó.
minValue egész egész Az egész szám paraméter minimális értéke. Ez az érték a befogadó.
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: . 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

A rendelkezésre álló dekorátorokról a következő szakaszokban olvashat.

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

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.

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

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

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 a portálon 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 rámutat a kurzorra a VS Code StorageAccountName elemére, a formázott szöveg jelenik meg:

Use Markdown-formatted text in VSCode

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

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.

Paraméter 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 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@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
        }
      }
    ]
  }
}

További lépések