Delen via

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.

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

Trainingsmateriaal

Zie de leer-module herbruikbare Bicep-bestanden bouwen met parameters voor stapsgewijze begeleiding over 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. U hoeft het gegevenstype niet op te geven in .bicepparam bestanden, omdat dit is gedefinieerd in Bicep-bestanden.

param <parameter-name> = <value>

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 in Bicep 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 reference functie of een van de list functies in de sectie parameters niet gebruiken. Deze functies bepalen de runtimestatus van de resource en kunnen niet worden uitgevoerd voordat de implementatie plaatsvindt en totdat de parameters zijn verwerkt.

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.

Gebruik decorateurs

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 Argumentatie Beschrijving
toegestaan alle array Gebruik deze decorator om ervoor te zorgen dat de gebruiker de juiste waarden levert. Deze decorator is alleen toegestaan op param instructies. Als u wilt aangeven dat een eigenschap een van een reeks vooraf gedefinieerde waarden in een type of output instructie moet zijn, gebruikt u de unietypesyntaxis. De syntaxis van het unietype kan ook worden gebruikt in param uitspraken.
beschrijving alle touw Tekst waarin wordt uitgelegd hoe u de parameter gebruikt. De beschrijving wordt weergegeven voor gebruikers in Azure Portal.
Discriminator Voorwerp touw Gebruik deze decorator om ervoor te zorgen dat de juiste subklasse wordt geïdentificeerd en beheerd. Voor meer informatie, zie Gecombineerd gegevenstype met aangepaste labels.
maxLength array, tekenreeks int (integer) De maximale lengte voor tekenreeks- en matrixparameters. De waarde is inclusief.
maxValue int (integer) int (integer) De maximumwaarde voor de parameter geheel getal. Deze waarde is inclusief.
metagegevens alle Voorwerp Aangepaste eigenschappen die moeten worden toegepast op de parameter. Kan de eigenschap 'beschrijving' bevatten die gelijk is aan de beschrijvingsdecorator.
minLength array, tekenreeks int (integer) De minimale lengte voor tekenreeks- en matrixparameters. De waarde is inclusief.
minValue int (integer) int (integer) De minimumwaarde voor de parameter geheel getal. Deze waarde is inclusief.
Verzegeld Voorwerp Geen Verhoog BCP089 van een waarschuwing naar een fout wanneer een eigenschapsnaam van een use-defined gegevenstype waarschijnlijk een 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 implementeert via Azure Portal, 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 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

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

Met Markdown opgemaakte tekst gebruiken in VS Code

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

Onderscheider

Zie aangepast gemarkeerd verenigingsgegevenstype.

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 gedeclareerd. Een parameter is voor een opslagaccountnaam die 3 tot 24 tekens moet bevatten. De andere parameter is een matrix die 1 tot 5 items moet bevatten.

@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 opgeeft met een eigenschap die conflicteert met een andere decorator, heeft die decorator altijd voorrang op iets in de @metadata() decorator, zodat de conflicterende eigenschap binnen de @metadata() waarde overbodig is en wordt vervangen. Zie Linter-regel voor meer informatie: geen conflicterende metagegevens.

Verzegeld

Zie Foutniveau verhogen.

Beveiligde parameters

U kunt string- of objectparameters als veilig markeren. Wanneer een parameter is voorzien van @secure(), behandelt Azure Resource Manager de parameterwaarde als gevoelig, waardoor deze niet kan worden gelogd of getoond in de uitrolgeschiedenis, Azure Portal of opdrachtregeluitvoer.

@secure()
param demoPassword string

@secure()
param demoSecretObject object

Er zijn verschillende linterregels die betrekking hebben op deze decorateur: Beveiligde standaardwaarde voor parameters, Parameters beveiligen in geneste implementaties, Geheimen veiligstellen 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
  ...
}

De @secure() decorator is alleen geldig voor parameters van het type tekenreeks of object, omdat deze overeenkomen met de typen secureString en secureObject in ARM-sjablonen. Als u matrices of getallen veilig wilt doorgeven, verpakt u ze in een secureObject of serialiseert u ze als secureString.

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