Parametrar i Bicep

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.

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

Bicep tillåter högst 256 parametrar. Mer information finns i Mallgränser.

Metodtips för parametrar finns i Parametrar.

Utbildningsresurser

Mer stegvis vägledning om parametrar finns i Skapa återanvändbara Bicep-filer med hjälp av parametrarna Learn-modulen.

Definiera parametrar

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

@<decorator>(<argument>)
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. Du behöver inte ange datatypen i .bicepparam filer eftersom den har definierats i Bicep-filer.

param <parameter-name> = <value>

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 i Bicep.

Ange standardvärden

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 reference funktionen eller någon av list funktionerna 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

Du kan dock inte referera till en variabel som standardvärde.

Använd 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. I följande tabell visas tillgängliga dekoratörer för parametrar:

Dekoratorer finns i sys-namnområdet. Om du behöver skilja en dekoratör från ett annat objekt med samma namn, ange dekoratören med sys först. 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

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.

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

När du hovra markören över storageAccountName i Visual Studio Code visas den formaterade texten:

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

Diskriminator

Se Anpassad taggad unionsdatatyp.

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

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 till 24 tecken. Den andra parametern är en matris som måste ha 1 till 5 objekt.

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

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

Metainformation

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 tilldelar en @metadata() dekoratör en egenskap som kommer i konflikt med en annan dekoratör, så har den dekoratören alltid företräde framför allt i @metadata() dekoratören, vilket gör att den motstridiga egenskapen inom @metadata() värdet blir redundant och ersätts. Mer information finns i Linter-regeln – inga metadata i konflikt.

Stängd

Mer information finns i Höja felnivå.

Säkra parametrar

Du kan markera sträng- eller objektparametrar som säkra. När en parameter är dekorerad med @secure()behandlar Azure Resource Manager parametervärdet som känsligt, vilket förhindrar att det loggas eller visas i distributionshistorik, Azure Portal eller kommandoradsutdata.

@secure()
param demoPassword string

@secure()
param demoSecretObject object

Det finns flera linterregler som är relaterade till den här dekoratören: Standard för säker parameter, Säkra parametrar i kapslade distributioner, Säkra hemligheter i parametrar.

Använda parametrar

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@2024-11-01' = {
  name: vaultName
  ...
}

Dekoratören @secure() är endast giltig för parametrar av typen sträng eller objekt, eftersom dessa överensstämmer med secureString - och secureObject-typerna i ARM-mallar. Om du vill skicka matriser eller tal på ett säkert sätt omsluter du dem i en secureObject eller serialiserar dem som en secureString.

Använda 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@2024-07-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

• Mer information om de egenskaper som är tillgängliga för parametrar finns i Bicep-filstruktur och syntax.
• Mer information om hur du skickar in parametervärden som en fil finns i Skapa en parameterfil för Bicep-distribution.
• Mer information om hur du tillhandahåller parametervärden vid distribution finns i Distribuera Bicep-filer med Azure CLI och Azure PowerShell.