Parametrar i Bicep

  • Artikel

I den här artikeln beskrivs hur du definierar och använder parametrar i en Bicep-fil. Genom att ange olika värden för parametrar kan du återanvända en Bicep-fil för olika miljöer.

Resource Manager löser parametervärden innan distributionsåtgärderna startas. Oavsett var parametern används ersätter Resource Manager den med det lösta värdet.

Varje parameter måste anges till en av datatyperna.

Du är begränsad till 256 parametrar i en Bicep-fil. Mer information finns i Mallgränser.

Metodtips för parametrar finns i Parametrar.

Utbildningsresurser

Om du hellre vill lära dig mer om parametrar via stegvis vägledning kan du läsa Skapa återanvändbara Bicep-mallar med hjälp av parametrar.

Förklaring

Varje parameter har ett namn och en datatyp. Du kan också ange ett standardvärde för parametern.

param <parameter-name> <parameter-data-type> = <default-value>

En parameter kan inte ha samma namn som en variabel, resurs, utdata eller annan parameter i samma omfång.

I följande exempel visas grundläggande deklarationer av parametrar.

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

Nyckelordet param används också i .bicepparam-filer. I .bicepparam-filer behöver du inte ange datatypen eftersom den definieras i Bicep-filer.

param <parameter-name> = <value>

Mer information finns i Parameterfil.

Användardefinierade typuttryck kan användas som typsatsen för en param -instruktion. Till exempel:

param storageAccountConfig {
  name: string
  sku: string
}

Mer information finns i Användardefinierade datatyper.

Standardvärde

Du kan ange ett standardvärde för en parameter. Standardvärdet används när ett värde inte anges under distributionen.

param demoParam string = 'Contoso'

Du kan använda uttryck med standardvärdet. Uttryck tillåts inte med andra parameteregenskaper. Du kan inte använda referensfunktionen eller någon av listfunktionerna i avsnittet parametrar. Dessa funktioner hämtar resursens körningstillstånd och kan inte köras före distributionen när parametrarna har lösts.

param location string = resourceGroup().location

Du kan använda ett annat parametervärde för att skapa ett standardvärde. Följande mall konstruerar ett värdplansnamn från platsnamnet.

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

output siteNameOutput string = siteName
output hostingPlanOutput string = hostingPlanName

Dekoratörer

Parametrar använder dekoratörer för begränsningar eller metadata. Dekoratörerna är i formatet @expression och placeras ovanför parameterns deklaration. Du kan markera en parameter som säker, ange tillåtna värden, ange minsta och högsta längd för en sträng, ange det lägsta och högsta värdet för ett heltal och ange en beskrivning av parametern.

I följande exempel visas två vanliga användningsområden för dekoratörer.

@secure()
param demoPassword string

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

I följande tabell beskrivs tillgängliga dekoratörer och hur du använder dem.

Dekoratör Tillämpa på Argument beskrivning
Tillåtet alla matris Tillåtna värden för parametern. Använd den här dekoratören för att se till att användaren tillhandahåller rätt värden.
Beskrivning alla sträng Text som förklarar hur du använder parametern. Beskrivningen visas för användare via portalen.
Maxlength matris, sträng heltal Maximal längd för sträng- och matrisparametrar. Värdet är inkluderande.
Maxvalue heltal heltal Det maximala värdet för heltalsparametern. Det här värdet är inkluderande.
metadata alla objekt Anpassade egenskaper som ska tillämpas på parametern. Kan innehålla en beskrivningsegenskap som motsvarar beskrivningsdekoratören.
Minlength matris, sträng heltal Minsta längd för sträng- och matrisparametrar. Värdet är inkluderande.
minValue heltal heltal Minsta värde för heltalsparametern. Det här värdet är inkluderande.
Säker sträng, objekt inget Markerar parametern som säker. Värdet för en säker parameter sparas inte i distributionshistoriken och loggas inte. Mer information finns i Skydda strängar och objekt.

Dekoratörer finns i sys-namnområdet. Om du behöver skilja en dekoratör från ett annat objekt med samma namn, förorda dekoratören med sys. Om din Bicep-fil till exempel innehåller en parameter med namnet descriptionmåste du lägga till sys-namnområdet när du använder beskrivningsdekoratören.

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

De tillgängliga dekoratörerna beskrivs i följande avsnitt.

Säkra parametrar

Du kan markera sträng- eller objektparametrar som säkra. Värdet för en säker parameter sparas inte i distributionshistoriken och loggas inte.

@secure()
param demoPassword string

@secure()
param demoSecretObject object

Tillåtna värden

Du kan definiera tillåtna värden för en parameter. Du anger de tillåtna värdena i en matris. Distributionen misslyckas under valideringen om ett värde skickas in för parametern som inte är ett av de tillåtna värdena.

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

Om du definierar tillåtna värden för en matrisparameter kan det faktiska värdet vara valfri delmängd av de tillåtna värdena.

Längdbegränsningar

Du kan ange minsta och högsta längd för sträng- och matrisparametrar. Du kan ange en eller båda begränsningarna. För strängar anger längden antalet tecken. För matriser anger längden antalet objekt i matrisen.

I följande exempel deklareras två parametrar. En parameter är för ett lagringskontonamn som måste innehålla 3–24 tecken. Den andra parametern är en matris som måste ha mellan 1 och 5 objekt.

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

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

Heltalsbegränsningar

Du kan ange lägsta och högsta värden för heltalsparametrar. Du kan ange en eller båda begränsningarna.

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

beskrivning

Lägg till en beskrivning i parametern för att hjälpa användarna att förstå värdet som ska anges. När en användare distribuerar mallen via portalen används beskrivningens text automatiskt som ett tips för den parametern. Lägg bara till en beskrivning när texten innehåller mer information än vad som kan härledas från parameternamnet.

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

Markdown-formaterad text kan användas för beskrivningstexten:

@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

När du hovrar markören över storageAccountName i VS Code visas den formaterade texten:

Använda Markdown-formaterad text i VSCode

Kontrollera att texten följer korrekt Markdown-formatering. annars kanske den inte visas korrekt när den återges

Metadata

Om du har anpassade egenskaper som du vill tillämpa på en parameter lägger du till en metadatadekoratör. I metadata definierar du ett objekt med anpassade namn och värden. Objektet som du definierar för metadata kan innehålla egenskaper för valfritt namn och typ.

Du kan använda den här dekoratören för att spåra information om parametern som inte är lämplig att lägga till i beskrivningen.

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

När du ger en @metadata() dekoratör en egenskap som står i konflikt med en annan dekoratör, har den dekoratören alltid företräde framför allt i dekoratören @metadata() . Därför är den motstridiga egenskapen i @metadata() värdet redundant och kommer att ersättas. Mer information finns i Inga metadata i konflikt.

Använda parameter

Om du vill referera till värdet för en parameter använder du parameternamnet. I följande exempel används ett parametervärde för ett nyckelvalvnamn.

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

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

Objekt som parametrar

Det kan vara enklare att ordna relaterade värden genom att skicka in dem som ett objekt. Den här metoden minskar också antalet parametrar i mallen.

I följande exempel visas en parameter som är ett objekt. Standardvärdet visar de förväntade egenskaperna för objektet. Dessa egenskaper används när du definierar resursen som ska distribueras.

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

Nästa steg