Lezen in het Engels

Share via

Een parameterbestand maken voor Bicep-implementatie

  • Artikel

In dit artikel leest u hoe u een parameterbestand maakt, dat u kunt gebruiken in plaats van parameters door te geven als inlinewaarden in uw script. U kunt een Bicep-parametersbestand gebruiken met de .bicepparam bestandsextensie of een JSON-parameterbestand dat de parameterwaarde bevat.

Notitie

Bicep-parametersbestanden worden alleen ondersteund in Bicep CLI versie 0.18.4 of hoger, Azure CLI versie 2.47.0 of hoger en Azure PowerShell versie 9.7.1 of hoger.

Aan één Bicep-bestand kunnen meerdere Bicep-parametersbestanden zijn gekoppeld. Elk Bicep-parametersbestand is echter bedoeld voor één bepaald Bicep-bestand. U kunt deze relatie tot stand brengen door de using instructie toe te passen in het bicep-parametersbestand.

U kunt Bicep-parametersbestanden compileren in JSON-parametersbestanden die u kunt implementeren met behulp van een Bicep-bestand. Zie build-params voor meer informatie. U kunt ook een JSON-parameterbestand decompileren in een Bicep-parametersbestand. Zie decompile-params voor meer informatie.

Parametersbestand

Een parameterbestand gebruikt de volgende indeling:

Bicep 
using '<path>/<file-name>.bicep'

param <first-parameter-name> = <first-value>
param <second-parameter-name> = <second-value>

U kunt de using instructie toepassen met behulp van een Bicep-bestand, JSON Azure Resource Manager-sjablonen, Bicep-modules en sjabloonspecificaties. Voorbeeld:

Bicep 
using './main.bicep'
...
Bicep 
using './azuredeploy.json'
...
Bicep 
using 'br/public:avm/res/storage/storage-account:0.9.0' 
...
Bicep 
using 'br:myacr.azurecr.io/bicep/modules/storage:v1'
...
Bicep 
using 'ts:00000000-0000-0000-0000-000000000000/myResourceGroup/storageSpec:1.0'
...

Zie Using-instructie voor meer informatie.

U kunt expressies gebruiken met de standaardwaarde. Voorbeeld:

Bicep 
using 'main.bicep'

param storageName = toLower('MyStorageAccount')
param intValue = 2 + 2

U kunt naar omgevingsvariabelen verwijzen als parameterwaarden. Voorbeeld:

Bicep 
using './main.bicep'

param intFromEnvironmentVariables = int(readEnvironmentVariable('intEnvVariableName'))

U kunt variabelen definiëren en gebruiken. U moet Bicep CLI versie 0.21.X of hoger gebruiken om variabelen in .bicepparam bestanden te kunnen gebruiken. Zie de volgende voorbeelden:

Bicep 
using './main.bicep'

var storagePrefix = 'myStorage'
param primaryStorageName = '${storagePrefix}Primary'
param secondaryStorageName = '${storagePrefix}Secondary'
Bicep 
using './main.bicep'

var testSettings = {
  instanceSize: 'Small'
  instanceCount: 1
}

var prodSettings = {
  instanceSize: 'Large'
  instanceCount: 4
}

param environmentSettings = {
  test: testSettings
  prod: prodSettings
}

Notitie

In een parameterbestand worden parameterwaarden opgeslagen als tekst zonder opmaak. Om veiligheidsredenen raden we u niet aan deze benadering te gebruiken met gevoelige waarden, zoals wachtwoorden.

Als u een parameter met een gevoelige waarde moet doorgeven, moet u de waarde in een sleutelkluis behouden. In plaats van een gevoelige waarde toe te voegen aan uw parameterbestand, gebruikt u de getSecret functie om deze op te halen. Zie Azure Key Vault gebruiken om een geheim door te geven als parameter tijdens de bicep-implementatie voor meer informatie.

Parametertype-indelingen

In het volgende voorbeeld ziet u de indelingen van verschillende parametertypen: tekenreeks, geheel getal, Booleaanse waarde, matrix en object.

Bicep 
using './main.bicep'

param exampleString = 'test string'
param exampleInt = 2 + 2
param exampleBool = true
param exampleArray = [
  'value 1'
  'value 2'
]
param exampleObject = {
  property1: 'value 1'
  property2: 'value 2'
}

Gebruik bicep-syntaxis om objecten en matrices te declareren.

Bestandsnaam

De bestandsextensie voor een Bicep-parametersbestand is .bicepparam.

Als u wilt implementeren in meerdere omgevingen, maakt u meer dan één parameterbestand. Wanneer u meerdere parameterbestanden gebruikt, moet u ze labelen op basis van hun gebruik. Als u bijvoorbeeld resources wilt implementeren, gebruikt u het label main.dev.bicepparam voor ontwikkeling en het label main.prod.bicepparam voor productie.

Parameterwaarden definiëren

Als u wilt bepalen hoe u parameternamen en -waarden definieert, opent u het Bicep-bestand. Bekijk de parameterssectie van het Bicep-bestand. In de volgende voorbeelden ziet u de parameters uit een Bicep-bestand met de naam main.bicep:

Bicep 
@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

Zoek in het parameterbestand naar de naam van elke parameter. De parameternamen in het parameterbestand moeten overeenkomen met de parameternamen in uw Bicep-bestand.

Bicep 
using 'main.bicep'

param storagePrefix
param storageAccountType

De using instructie koppelt het Bicep-parametersbestand aan een Bicep-bestand. Zie Using-instructie voor meer informatie.

Wanneer u het trefwoord param in Visual Studio Code typt, wordt u gevraagd om de beschikbare parameters en de bijbehorende beschrijvingen uit het gekoppelde Bicep-bestand.

Schermopname van de prompt van de beschikbare parameters.

Wanneer u een param naam aanwijst, ziet u het gegevenstype en de beschrijving van de parameter.

Schermopname van het gegevenstype en de beschrijving van de parameter.

Controleer het parametertype, omdat de parametertypen in het parameterbestand dezelfde typen moeten gebruiken als uw Bicep-bestand. In dit voorbeeld zijn beide parametertypen tekenreeksen:

Bicep 
using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

Controleer het Bicep-bestand op parameters die een standaardwaarde bevatten. Als een parameter een standaardwaarde heeft, kunt u een waarde opgeven in het parameterbestand, maar deze is niet vereist. De parameterbestandswaarde overschrijft de standaardwaarde van het Bicep-bestand.

Bicep 
using 'main.bicep'

param storagePrefix = '' // This value must be provided.
param storageAccountType = '' // This value is optional. Bicep uses default value if not provided.

Als u wilt zien of er beperkingen zijn zoals maximale lengte, controleert u de toegestane waarden van het Bicep-bestand. De toegestane waarden geven het bereik van waarden op dat u voor een parameter kunt opgeven. In dit voorbeeld storagePrefix mogen maximaal 11 tekens zijn en storageAccountType moet een toegestane waarde worden opgegeven.

Bicep 
using 'main.bicep'

param storagePrefix = 'storage'
param storageAccountType = 'Standard_ZRS'

Parametersbestand genereren

U kunt een parameterbestand maken met Visual Studio Code of de Bicep CLI. Met beide hulpprogramma's kunt u een Bicep-bestand gebruiken om een parameterbestand te genereren. Zie Het bestand Parameters genereren voor de Methode Visual Studio Code en het parameterbestand Genereren voor de Bicep CLI-methode.

Bicep-parametersbestand bouwen

Vanuit de Bicep CLI kunt u een Bicep-parametersbestand bouwen in een JSON-parametersbestand. Zie buildparametersbestand voor meer informatie.

Bicep-bestand met parametersbestand implementeren

Azure-CLI

Vanuit de Azure CLI kunt u een parameterbestand doorgeven met de implementatie van uw Bicep-bestand.

U kunt een Bicep-bestand implementeren met behulp van een Bicep-parametersbestand met Azure CLI versie 2.53.0 of hoger en Bicep CLI versie 0.22.X of hoger. Met de using instructie in het Bicep-parametersbestand hoeft u de --template-file schakeloptie niet op te geven bij het opgeven van een Bicep-parametersbestand voor de --parameters switch.

Azure CLI 
az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam

U kunt inlineparameters en een locatieparametersbestand gebruiken in dezelfde implementatiebewerking. Voorbeeld:

Azure CLI 
az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam \
  --parameters storageAccountType=Standard_LRS

Zie Bicep-bestanden implementeren met behulp van de Azure CLI voor meer informatie.

Azure PowerShell

Geef vanuit Azure PowerShell een lokaal parameterbestand door met behulp van de TemplateParameterFile parameter.

Azure PowerShell 
New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.bicepparam

U kunt inlineparameters en een locatieparametersbestand gebruiken in dezelfde implementatiebewerking. Voorbeeld:

Azure PowerShell 
New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.bicepparam `
  -storageAccountType Standard_LRS

Zie Bicep-bestanden implementeren met behulp van Azure PowerShell voor meer informatie. Als u bestanden wilt implementeren .bicep , hebt u Azure PowerShell versie 5.6.0 of hoger nodig.

Parameterprioriteit

U kunt inlineparameters en een lokaal parameterbestand in dezelfde implementatiebewerking gebruiken. U kunt bijvoorbeeld bepaalde waarden opgeven in het bestand met lokale parameters en andere waarden inline toevoegen tijdens de implementatie. Als u waarden opgeeft voor een parameter in zowel het lokale parameterbestand als inline, heeft de inlinewaarde voorrang.

Hoewel externe Bicep-parametersbestanden momenteel niet worden ondersteund, kunt u een extern JSON-parameterbestand gebruiken door de URI aan het bestand op te geven. Wanneer u een bestand met externe parameters gebruikt, geeft u alle parameterwaarden op in het externe bestand. Wanneer u een extern bestand gebruikt, kunt u geen andere waarden inline of vanuit een lokaal bestand doorgeven en worden alle inlineparameters genegeerd.

Conflicten met parameternamen

Als uw Bicep-bestand een parameter bevat met dezelfde naam als een van de parameters in de Azure PowerShell-opdracht, geeft Azure PowerShell de parameter uit uw Bicep-bestand weer met het FromTemplate achtervoegsel. Als een parameter met de naam ResourceGroupName in uw Bicep-bestand bijvoorbeeld conflicteert met de ResourceGroupName parameter in de New-AzResourceGroupDeployment cmdlet, wordt u gevraagd een waarde op te geven voor ResourceGroupNameFromTemplate. Gebruik parameternamen die niet worden gebruikt voor implementatieopdrachten om deze verwarring te voorkomen.

Gerelateerde inhoud