Parameters in Bicep

In dit artikel wordt beschreven hoe u parameters in een Bicep-bestand definieert en gebruikt. Door verschillende waarden voor parameters op te geven, kunt u een Bicep-bestand opnieuw gebruiken voor verschillende omgevingen.

Resource Manager lost parameterwaarden op voordat de implementatiebewerkingen worden gestart. Waar de parameter ook wordt gebruikt, vervangt Resource Manager deze door de opgeloste waarde.

Elke parameter moet worden ingesteld op een van de gegevenstypen.

Bicep staat maximaal 256 parameters toe. Zie Sjabloonlimieten voor meer informatie.

Zie Parameters voor aanbevolen procedures voor parameters.

Trainingsmateriaal

Als u liever meer wilt weten over parameters via stapsgewijze richtlijnen, raadpleegt u Herbruikbare Bicep-sjablonen bouwen met behulp van parameters.

Parameters definiëren

Elke parameter heeft een naam en gegevenstype. U kunt desgewenst een standaardwaarde opgeven voor de parameter.

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

Een parameter kan niet dezelfde naam hebben als een variabele, resource, uitvoer of andere parameter in hetzelfde bereik.

In het volgende voorbeeld ziet u basisdeclaraties van parameters.

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

Het param trefwoord wordt ook gebruikt in bicepparam-bestanden. In bicepparam-bestanden hoeft u het gegevenstype niet op te geven zoals het is gedefinieerd in Bicep-bestanden.

param <parameter-name> = <value>

Zie het parameterbestand voor meer informatie.

Door de gebruiker gedefinieerde typeexpressies kunnen worden gebruikt als de typecomponent van een param instructie. Voorbeeld:

param storageAccountConfig {
  name: string
  sku: string
}

Zie Door de gebruiker gedefinieerde gegevenstypen voor meer informatie.

Standaardwaarden instellen

U kunt een standaardwaarde voor een parameter opgeven. De standaardwaarde wordt gebruikt wanneer er tijdens de implementatie geen waarde wordt opgegeven.

param demoParam string = 'Contoso'

U kunt expressies gebruiken met de standaardwaarde. Expressies zijn niet toegestaan met andere parametereigenschappen. U kunt de verwijzingsfunctie of een van de lijstfuncties in de sectie parameters niet gebruiken. Deze functies krijgen de runtimestatus van de resource en kunnen niet worden uitgevoerd voordat de implementatie wordt uitgevoerd wanneer parameters worden opgelost.

param location string = resourceGroup().location

U kunt een andere parameterwaarde gebruiken om een standaardwaarde te maken. Met de volgende sjabloon wordt een hostplannaam samengesteld op basis van de sitenaam.

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

output siteNameOutput string = siteName
output hostingPlanOutput string = hostingPlanName

U kunt echter niet verwijzen naar een variabele als de standaardwaarde.

Decorators gebruiken

Parameters gebruiken decorators voor beperkingen of metagegevens. De decorators hebben de indeling @expression en worden boven de declaratie van de parameter geplaatst. In de volgende tabel ziet u de beschikbare decorators voor parameters.

Decorateur	Van toepassing op	Argument	Beschrijving
toegestaan	Alles	matrix	Gebruik deze decorator om ervoor te zorgen dat de gebruiker de juiste waarden levert. Deze decorator is alleen toegestaan voor param instructies. Als u wilt declareren dat een eigenschap een van een set vooraf gedefinieerde waarden in een type of output instructie moet zijn, gebruikt u de syntaxis van het samenvoegtype. Syntaxis van samenvoegingstype kan ook worden gebruikt in param instructies.
beschrijving	Alles	tekenreeks	Tekst waarin wordt uitgelegd hoe u de parameter gebruikt. De beschrijving wordt weergegeven voor gebruikers via de portal.
Discriminator	object	tekenreeks	Gebruik deze decorator om ervoor te zorgen dat de juiste subklasse wordt geïdentificeerd en beheerd. Zie het gegevenstype Aangepaste samenvoeging voor meer informatie.
maxLength	matrix, tekenreeks	int	De maximale lengte voor tekenreeks- en matrixparameters. De waarde is inclusief.
maxValue	int	int	De maximumwaarde voor de parameter geheel getal. Deze waarde is inclusief.
metagegevens	Alles	object	Aangepaste eigenschappen die moeten worden toegepast op de parameter. Kan een beschrijvingseigenschap bevatten die gelijk is aan de beschrijvingsdecorator.
minLength	matrix, tekenreeks	int	De minimale lengte voor tekenreeks- en matrixparameters. De waarde is inclusief.
minValue	int	int	De minimumwaarde voor de parameter geheel getal. Deze waarde is inclusief.
Verzegeld	object	Geen	Verhoog BCP089 van een waarschuwing naar een fout wanneer een eigenschapsnaam van een gegevenstype use-define waarschijnlijk een type typfout is. Zie Foutniveau verhogen voor meer informatie.
veilig	tekenreeks, object	Geen	Markeert de parameter als veilig. De waarde voor een beveiligde parameter wordt niet opgeslagen in de implementatiegeschiedenis en wordt niet geregistreerd. Zie Beveiligde tekenreeksen en objecten voor meer informatie.

Decorators bevinden zich in de sys-naamruimte. Als u een decorator wilt onderscheiden van een ander item met dezelfde naam, moet u de decorator vooraf laten gaan door sys. Als uw Bicep-bestand bijvoorbeeld een parameter met de naam descriptionbevat, moet u de sys-naamruimte toevoegen wanneer u de beschrijvings decorator gebruikt.

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

Toegestane waarden

U kunt toegestane waarden definiëren voor een parameter. U geeft de toegestane waarden op in een matrix. De implementatie mislukt tijdens de validatie als een waarde wordt doorgegeven voor de parameter die geen van de toegestane waarden is.

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

Als u toegestane waarden definieert voor een matrixparameter, kan de werkelijke waarde een subset van de toegestane waarden zijn.

Beschrijving

Voeg een beschrijving toe aan de parameter om gebruikers inzicht te geven in de waarde die moet worden opgegeven. Wanneer een gebruiker de sjabloon via de portal implementeert, wordt de tekst van de beschrijving automatisch gebruikt als tip voor die parameter. Voeg alleen een beschrijving toe wanneer de tekst meer informatie biedt dan kan worden afgeleid van de parameternaam.

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

Markdown-opgemaakte tekst kan worden gebruikt voor de beschrijvingstekst:

@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

Wanneer u de cursor boven storageAccountName in VS Code plaatst, ziet u de opgemaakte tekst:

Zorg ervoor dat de tekst de juiste Markdown-opmaak volgt; anders wordt deze mogelijk niet correct weergegeven wanneer deze wordt weergegeven.

Discriminator

Zie het gegevenstype Voor een samenvoeging met aangepaste tags.

Beperkingen voor gehele getallen

U kunt minimum- en maximumwaarden instellen voor parameters voor gehele getallen. U kunt een of beide beperkingen instellen.

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

Lengtebeperkingen

U kunt minimum- en maximumlengten opgeven voor tekenreeks- en matrixparameters. U kunt een of beide beperkingen instellen. Voor tekenreeksen geeft de lengte het aantal tekens aan. Voor matrices geeft de lengte het aantal items in de matrix aan.

In het volgende voorbeeld worden twee parameters declareren. Een parameter is voor een opslagaccountnaam die 3-24 tekens moet bevatten. De andere parameter is een matrix die uit 1-5 items moet bestaan.

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

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

Metagegevens

Als u aangepaste eigenschappen hebt die u wilt toepassen op een parameter, voegt u een metagegevensdecorator toe. Definieer binnen de metagegevens een object met de aangepaste namen en waarden. Het object dat u definieert voor de metagegevens kan eigenschappen van elke naam en elk type bevatten.

U kunt deze decorator gebruiken om informatie bij te houden over de parameter die niet zinvol is om aan de beschrijving toe te voegen.

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

Wanneer u een @metadata() decorator verstrekt met een eigenschap die conflicteert met een andere decorator, heeft die decorator altijd voorrang op iets in de @metadata() decorator. De conflicterende eigenschap in de @metadata() waarde is dus redundant en wordt vervangen. Zie Geen conflicterende metagegevens voor meer informatie.

Verzegeld

Zie Foutniveau verhogen.

Beveiligde parameters

U kunt tekenreeks- of objectparameters als veilig markeren. De waarde van een beveiligde parameter wordt niet opgeslagen in de implementatiegeschiedenis en wordt niet geregistreerd.

@secure()
param demoPassword string

@secure()
param demoSecretObject object

Er zijn verschillende linterregels die betrekking hebben op deze decorator: standaard voor beveiligde parameters, beveiligingsparameters in geneste implementaties, geheimen beveiligen in parameters.

Parameters gebruiken

Als u wilt verwijzen naar de waarde voor een parameter, gebruikt u de parameternaam. In het volgende voorbeeld wordt een parameterwaarde gebruikt voor de naam van een sleutelkluis.

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

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

Objecten gebruiken als parameters

Het kan eenvoudiger zijn om gerelateerde waarden te ordenen door ze door te geven als een object. Deze benadering vermindert ook het aantal parameters in de sjabloon.

In het volgende voorbeeld ziet u een parameter die een object is. De standaardwaarde toont de verwachte eigenschappen voor het object. Deze eigenschappen worden gebruikt bij het definiëren van de resource die moet worden geïmplementeerd.

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

Volgende stappen

• Zie De structuur en syntaxis van Bicep-bestanden begrijpen voor meer informatie over de beschikbare eigenschappen voor parameters.
• Zie Een Bicep-parameterbestand maken voor meer informatie over het doorgeven van parameterwaarden als een bestand.
• Zie Implementeren met Azure CLI en Implementeren met Azure PowerShell voor meer informatie over het leveren van parameterwaarden bij de implementatie.