Delen via

Parametersbestanden maken voor Bicep-implementatie

  • Artikel

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

Notitie

Het bicep-parametersbestand wordt 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. Deze relatie wordt tot stand gebracht met de using-instructie in het bicep-parametersbestand.

U kunt Bicep-parametersbestanden compileren in JSON-parametersbestanden om te implementeren met een Bicep-bestand. Zie build-params. U kunt ook een JSON-parameterbestand decompileren in een Bicep-parametersbestand. Zie decompile-params.

Parametersbestand

Een parameterbestand gebruikt de volgende indeling:

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

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

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

using './main.bicep'
...

using './azuredeploy.json'
...

using 'br/public:avm/res/storage/storage-account:0.9.0' 
...

using 'br:myacr.azurecr.io/bicep/modules/storage:v1'
...

using 'ts:00000000-0000-0000-0000-000000000000/myResourceGroup/storageSpec:1.0'
...

Zie de using-instructie voor meer informatie.

U kunt expressies gebruiken met de standaardwaarde. Voorbeeld:

using 'main.bicep'

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

U kunt naar omgevingsvariabelen verwijzen als parameterwaarden. Voorbeeld:

using './main.bicep'

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

U kunt variabelen definiëren en gebruiken. Bicep CLI versie 0.21.X of hoger is vereist voor het gebruik van variabelen in .bicepparam-bestanden. Hieronder volgen een aantal voorbeelden:

using './main.bicep'

var storagePrefix = 'myStorage'
param primaryStorageName = '${storagePrefix}Primary'
param secondaryStorageName = '${storagePrefix}Secondary'

using './main.bicep'

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

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

param environmentSettings = {
  test: testSettings
  prod: prodSettings
}

Het is de moeite waard om te vermelden dat het parameterbestand parameterwaarden opslaat als tekst zonder opmaak. Om veiligheidsredenen wordt deze methode niet aanbevolen voor gevoelige waarden, zoals wachtwoorden. Als u een parameter met een gevoelige waarde moet doorgeven, houdt u de waarde in een sleutelkluis. In plaats van een gevoelige waarde toe te voegen aan uw parameterbestand, gebruikt u de functie getSecret om deze op te halen. Zie Azure Key Vault gebruiken om een veilige parameterwaarde door te geven 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.

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

Bicep parameters bestand heeft de bestandsextensie van .bicepparam.

Als u wilt implementeren in verschillende omgevingen, maakt u meer dan één parameterbestand. Wanneer u meerdere parameterbestanden noemt, labelt u het gebruik ervan als ontwikkeling en productie. Gebruik bijvoorbeeld main.dev.bicepparam voor ontwikkeling en main.prod.bicepparam voor productie om resources te implementeren.

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:

@maxLength(11)
param storagePrefix string

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

Het eerste detail in het parameterbestand is de naam van elke parameter. De parameternamen in het parameterbestand moeten overeenkomen met de parameternamen in uw Bicep-bestand.

using 'main.bicep'

param storagePrefix
param storageAccountType

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

Nadat u het trefwoord param in Visual Studio Code hebt getypt, 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 de muisaanwijzer boven een parameternaam beweegt, ziet u het gegevenstype en de beschrijving van de parameter.

Schermopname van het gegevenstype en de beschrijving van de parameter.

Let op het parametertype. De parametertypen in het parameterbestand moeten dezelfde typen gebruiken als uw Bicep-bestand. In dit voorbeeld zijn beide parametertypen tekenreeksen.

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

Controleer het Bicep-bestand op parameters met een standaardwaarde. 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.

using 'main.bicep'

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

Controleer de toegestane waarden van het Bicep-bestand en eventuele beperkingen, zoals maximale lengte. Deze 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.

using 'main.bicep'

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

Parametersbestand genereren

U kunt een parameterbestand op twee manieren maken: met VS 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 VS Code-methode en het parameterbestand genereren voor de Bicep CLI-methode.

Bicep-parametersbestand bouwen

Vanuit 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 Azure CLI kunt u een parameterbestand doorgeven met uw Bicep-bestandsimplementatie.

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.

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

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

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

Zie Resources implementeren met Bicep en Azure CLI voor meer informatie.

Azure PowerShell

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

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:

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

Zie Resources implementeren met Bicep en Azure PowerShell voor meer informatie. Als u BICEP-bestanden wilt implementeren, 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, is het mogelijk om een extern JSON-parameterbestand te gebruiken door de URI aan het bestand op te geven. Wanneer u een bestand met externe parameters gebruikt, geeft u alle parameterwaarden in het externe bestand op, omdat u geen andere waarden inline of vanuit een lokaal bestand kunt doorgeven en alle inlineparameters worden genegeerd.

Conflicten met parameternamen

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

Volgende stappen