Sdílet prostřednictvím

Parametry v Bicep

Tento článek popisuje, jak definovat a používat parametry v souboru Bicep. Zadáním různých hodnot parametrů můžete znovu použít soubor Bicep pro různá prostředí.

Nástroj Azure Resource Manager vyřeší hodnoty parametrů před zahájením operací nasazení. Kdykoli se použije parametr, Resource Manager ho nahradí přeloženou hodnotou.

Každý parametr musí být nastavený na jeden z datových typů.

Bicep umožňuje maximálně 256 parametrů. Další informace najdete v tématu Omezení šablon.

Osvědčené postupy pro parametry najdete v tématu Parametry.

Školicí materiály

Podrobné pokyny k parametrům najdete v modulu Learn s možností sestavení opakovaně použitelných souborů Bicep .

Definování parametrů

Každý parametr má název a datový typ. Volitelně můžete zadat výchozí hodnotu parametru.

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

Parametr nemůže mít stejný název jako proměnná, prostředek, výstup nebo jiný parametr ve stejném oboru.

Následující příklad ukazuje základní deklarace parametrů.

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

Klíčové param slovo se také používá v .bicepparam souborech. Datový typ .bicepparam v souborech nemusíte zadávat, protože je definovaný v souborech Bicep.

param <parameter-name> = <value>

Výrazy typu definované uživatelem lze použít jako klauzuli param typu příkazu. Například:

param storageAccountConfig {
  name: string
  sku: string
}

Další informace naleznete v tématu Uživatelem definované datové typy v Bicep.

Nastavení výchozích hodnot

Můžete zadat výchozí hodnotu parametru. Výchozí hodnota se použije, když není během nasazení zadaná hodnota.

param demoParam string = 'Contoso'

Výrazy můžete použít s výchozí hodnotou. Výrazy nejsou povoleny s jinými vlastnostmi parametrů. Funkci reference ani žádnou z funkcí list v sekci parametrů nemůžete použít. Tyto funkce získají běhový stav prostředku a nelze je spustit před nasazením, kdy jsou parametry vyřešeny.

param location string = resourceGroup().location

K vytvoření výchozí hodnoty můžete použít jinou hodnotu parametru. Následující šablona vytvoří název plánu hostitele z názvu webu.

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

output siteNameOutput string = siteName
output hostingPlanOutput string = hostingPlanName

Na proměnnou ale nemůžete odkazovat jako na výchozí hodnotu.

Použití dekorátorů

Parametry používají dekorátory pro omezení nebo metadata. Dekorátory jsou ve formátu @expression a jsou umístěny nad deklaraci parametru. V následující tabulce jsou uvedeny dostupné dekorátory parametrů:

Dekoratér Přihlásit se Důvod Popis
povolený všichni pole Pomocí tohoto dekorátoru se ujistěte, že uživatel poskytuje správné hodnoty. Tento dekorátor je povolen pouze u příkazu param. Chcete-li deklarovat, že vlastnost musí být jednou ze sady předdefinovaných hodnot v type příkazu nebo output příkazu, použijte syntaxi sjednocovacího typu. Syntaxi sjednocovacího typu lze použít také v param příkazech.
popis všichni řetězec Text, který vysvětluje použití parametru. Popis se zobrazí uživatelům na webu Azure Portal.
diskriminátor objekt řetězec Pomocí tohoto dekorátoru zajistěte, aby byla správná podtřída správně identifikována a spravována. Další informace naleznete v tématu Datový typ unie s vlastními značkami.
maxLength pole, řetězec int (integer) Maximální délka parametrů řetězce a pole. Hodnota je inkluzivní.
maxValue int (integer) int (integer) Maximální hodnota celočíselného parametru. Tato hodnota je inkluzivní.
metadata všichni objekt Vlastní vlastnosti, které se mají použít u parametru. Může obsahovat vlastnost popisu, která je ekvivalentní popis dekorátoru.
minLength pole, řetězec int (integer) Minimální délka parametrů řetězce a pole. Hodnota je inkluzivní.
minValue int (integer) int (integer) Minimální hodnota celočíselného parametru. Tato hodnota je inkluzivní.
zapečetěno objekt Žádná Stanovte BCP089 jako chybu místo upozornění, když je název vlastnosti uživatelsky definovaného datového typu pravděpodobně překlep. Další informace naleznete v tématu Zvýšení úrovně chyby.
zajistit řetězec, objekt Žádná Označí parametr jako zabezpečený. Hodnota zabezpečeného parametru se neuloží do historie nasazení a nezaprotokoluje se. Další informace naleznete v tématu Zabezpečení řetězců a objektů.

Dekorátory jsou v sys namespace. Pokud potřebujete odlišit dekorátor od jiné položky se stejným názvem, předřaďte dekorátor pomocí sys. Pokud například váš soubor Bicep obsahuje parametr s názvem description, musíte přidat obor názvů sys při použití dekorátoru popisu .

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

Povolené hodnoty

Pro parametr můžete definovat povolené hodnoty. Do pole zadáte povolené hodnoty. Nasazení selže během ověřování, pokud je hodnota předána pro parametr, který není jednou z povolených hodnot.

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

Pokud definujete povolené hodnoty pro parametr pole, skutečná hodnota může být libovolná podmnožina povolených hodnot.

Popis

Pokud chcete uživatelům pomoct pochopit hodnotu, kterou chcete poskytnout, přidejte do parametru popis. Když uživatel nasadí šablonu prostřednictvím webu Azure Portal, text popisu se automaticky použije jako tip pro tento parametr. Přidejte popis pouze v případech, kdy text poskytuje více informací, než lze odvodit z názvu parametru.

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

Text ve formátu Markdownu lze použít pro text popisu:

@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

Když v editoru Visual Studio Code najedete myší na storageAccountName , zobrazí se formátovaný text:

Použití textu ve formátu Markdown v editoru VS Code

Ujistěte se, že text odpovídá správnému formátování Markdownu; jinak se při vykreslení nemusí zobrazit správně.

Diskriminátor

Viz uživatelsky definovaný označený sjednocený datový typ.

Celočíselná omezení

Pro celočíselné parametry můžete nastavit minimální a maximální hodnoty. Můžete nastavit jedno nebo obě omezení.

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

Omezení délky

Pro parametry řetězce a pole můžete zadat minimální a maximální délku. Můžete nastavit jedno nebo obě omezení. U řetězců délka označuje počet znaků. U polí určuje délka počet položek v matici.

Následující příklad deklaruje dva parametry. Jedním parametrem je název účtu úložiště, který musí mít 3 až 24 znaků. Druhý parametr je pole, které musí mít 1 až 5 položek.

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

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

Metadatové informace

Pokud máte vlastní vlastnosti, které chcete použít u parametru, přidejte dekorátor metadat. V metadatech definujte objekt s vlastními názvy a hodnotami. Objekt, který definujete pro metadata, může obsahovat vlastnosti libovolného názvu a typu.

Tento dekorátor můžete použít ke sledování informací o parametru, který nemá smysl přidat do popisu.

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

Když určíte @metadata() dekorátor s vlastností, která je v konfliktu s jiným dekorátorem, tento konkrétní dekorátor vždy dostává přednost před čímkoli v dekorátoru @metadata(), takže konfliktní vlastnost v hodnotě @metadata() je zbytečná a bude nahrazena. Další informace najdete v tématu Pravidlo Linter – žádná konfliktní metadata.

Zapečetěný

Viz Zvýšení úrovně chyby.

Zabezpečené parametry

Parametry řetězce nebo objektu můžete označit jako bezpečné. Když je parametr zdobený @secure(), Azure Resource Manager považuje hodnotu parametru za citlivou, brání jejímu zaprotokolování nebo zobrazení v historii nasazení, webu Azure Portal nebo výstupech příkazového řádku.

@secure()
param demoPassword string

@secure()
param demoSecretObject object

K tomuto dekorátoru se vztahuje několik pravidel linteru: Výchozí nastavení zabezpečeného parametru, zabezpečené parametry v vnořených nasazeních, Zabezpečené tajné kódy v parametrech.

Použití parametrů

Pokud chcete odkazovat na hodnotu parametru, použijte název parametru. Následující příklad používá hodnotu parametru pro název trezoru klíčů.

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

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

Dekorátor @secure() je platný pouze pro parametry typu řetězec nebo objekt, protože jsou v souladu s typy secureString a secureObject v šablonách ARM. Chcete-li bezpečně předat pole nebo čísla, zabalte je do objektu secureObject nebo je serializujte jako řetězec secureString.

Použití objektů jako parametrů

Uspořádání souvisejících hodnot může být jednodušší jejich předáním jako objektu. Tento přístup také snižuje počet parametrů v šabloně.

Následující příklad ukazuje parametr, který je objektem. Výchozí hodnota zobrazuje očekávané vlastnosti objektu. Tyto vlastnosti se používají při definování prostředku, který se má nasadit.

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

Další kroky