Parameters in Bicep

  • Artikel

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.

U bent beperkt tot 256 parameters in een Bicep-bestand. 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.

Verklaring

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

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.

Default value

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

Decorators

Parameters gebruiken decorators voor beperkingen of metagegevens. De decorators hebben de indeling @expression en worden boven de declaratie van de parameter geplaatst. U kunt een parameter markeren als veilig, toegestane waarden opgeven, de minimum- en maximumlengte voor een tekenreeks instellen, de minimum- en maximumwaarde voor een geheel getal instellen en een beschrijving van de parameter opgeven.

In het volgende voorbeeld ziet u twee veelvoorkomende toepassingen voor decorators.

@secure()
param demoPassword string

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

In de volgende tabel worden de beschikbare decorators beschreven en hoe u deze kunt gebruiken.

Decorator Van toepassing op Argument Beschrijving
Toegestaan Alles matrix Toegestane waarden voor de parameter. Gebruik deze decorator om ervoor te zorgen dat de gebruiker de juiste waarden levert.
beschrijving Alles tekenreeks Tekst waarin wordt uitgelegd hoe u de parameter gebruikt. De beschrijving wordt weergegeven voor gebruikers via de portal.
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.
Veilige 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

De beschikbare decorators worden beschreven in de volgende secties.

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

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.

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

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

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:

Markdown-opgemaakte tekst gebruiken in VSCode

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

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.

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

Volgende stappen