Skapa parameterfiler för Bicep-distribution

  • Artikel

I stället för att skicka parametrar som infogade värden i skriptet kan du använda en Bicep-parameterfil med filnamnstillägget .bicepparam eller en JSON-parameterfil som innehåller parametervärdena. Den här artikeln visar hur du skapar parameterfiler.

Kommentar

Bicep-parameterfilen stöds endast i Bicep CLI version 0.18.4 eller senare, Azure CLI version 2.47.0 eller senare och Azure PowerShell version 9.7.1 eller senare.

En enda Bicep-fil kan ha flera Bicep-parameterfiler associerade med den. Varje Bicep-parameterfil är dock avsedd för en viss Bicep-fil. Den här relationen upprättas med hjälp av -instruktionen using i Bicep-parameterfilen.

Du kan kompilera Bicep-parameterfiler till JSON-parameterfiler för distribution med en Bicep-fil. Se build-params. Du kan också dela upp en JSON-parameterfil i en Bicep-parameterfil. Se decompile-params.

Parameterfil

En parameterfil använder följande format:

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

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

Du kan använda instruktionen using med Bicep-fil, ARM JSON-mallar, Bicep-moduler och mallspecifikationer. Till exempel:

using './main.bicep'
...

using './azuredeploy.json'
...

using 'br/public:storage/storage-account:3.0.1'
...

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

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

Mer information finns i using-instruktionen.

Du kan använda uttryck med standardvärdet. Till exempel:

using 'main.bicep'

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

Du kan referera till miljövariabler som parametervärden. Till exempel:

using './main.bicep'

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

Du kan definiera och använda variabler. Bicep CLI version 0.21.X eller senare krävs för att använda variabler i .bicepparam-filen. Nedan följer några exempel:

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
}

Det är värt att notera att parameterfilen sparar parametervärden som oformaterad text. Av säkerhetsskäl rekommenderas inte den här metoden för känsliga värden som lösenord. Om du måste skicka en parameter med ett känsligt värde behåller du värdet i ett nyckelvalv. I stället för att lägga till det känsliga värdet i parameterfilen använder du funktionen getSecret för att hämta det. Mer information finns i Använda Azure Key Vault för att skicka säkert parametervärde under Bicep-distributionen.

Format för parametertyper

I följande exempel visas formaten för olika parametertyper: sträng, heltal, boolesk, matris och objekt.

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

Använd Bicep-syntax för att deklarera objekt och matriser.

Filnamn

Bicep-parameterfilen har filnamnstillägget .bicepparam.

Om du vill distribuera till olika miljöer skapar du fler än en parameterfil. När du namnger parameterfilerna identifierar du deras användning, till exempel utveckling och produktion. Använd till exempel main.dev.bicepparam och main.prod.bicepparam för att distribuera resurser.

Definiera parametervärden

Om du vill fastställa hur du definierar parameternamn och -värden öppnar du Bicep-filen. Titta på avsnittet parametrar i Bicep-filen. I följande exempel visas parametrarna från en Bicep-fil med namnet main.bicep.

@maxLength(11)
param storagePrefix string

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

I parameterfilen är den första informationen som ska märkas namnet på varje parameter. Parameternamnen i parameterfilen måste matcha parameternamnen i Bicep-filen.

using 'main.bicep'

param storagePrefix
param storageAccountType

Instruktionen using kopplar Bicep-parameterfilen till en Bicep-fil. Mer information finns i använda -instruktion.

När du har skrivit nyckelordet param i Visual Studio Code uppmanas du att ange tillgängliga parametrar och deras beskrivningar från den länkade Bicep-filen:

Skärmbild av frågan om tillgängliga parametrar.

När du hovrar över ett paramnamn kan du se parameterdatatypen och beskrivningen.

Skärmbild av parameterdatatypen och beskrivningen.

Observera parametertypen. Parametertyperna i parameterfilen måste använda samma typer som din Bicep-fil. I det här exemplet är båda parametertyperna strängar.

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

Kontrollera Bicep-filen efter parametrar med ett standardvärde. Om en parameter har ett standardvärde kan du ange ett värde i parameterfilen, men det krävs inte. Parameterfilens värde åsidosätter Bicep-filens standardvärde.

using 'main.bicep'

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

Kontrollera Biceps tillåtna värden och eventuella begränsningar, till exempel maximal längd. Dessa värden anger det värdeintervall som du kan ange för en parameter. I det här exemplet storagePrefix kan ha högst 11 tecken och storageAccountType måste ange ett tillåtet värde.

using 'main.bicep'

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

Generera parameterfil

För att generera en parameterfil har du två alternativ: antingen via Visual Studio Code eller med hjälp av Bicep CLI. Med båda metoderna kan du härleda parameterfilen från en Bicep-fil. Från Visual Studio Code, se Generera parameterfil. Från Bicep CLI, se Generera parameterfil.

Skapa Bicep-parameterfil

Från Bicep CLI kan du skapa en Bicep-parameterfil till en JSON-parameterfil. Mer information finns i Skapa parameterfil.

Distribuera Bicep-fil med parameterfilen

Azure CLI

Från Azure CLI kan du skicka en parameterfil med din Bicep-fildistribution.

Med Azure CLI version 2.53.0 eller senare och Bicep CLI version 0.22.X eller senare kan du distribuera en Bicep-fil genom att använda en Bicep-parameterfil. Med -instruktionen using i Bicep-parameterfilen behöver du inte ange växeln --template-file när du anger en Bicep-parameterfil för växeln --parameters .

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

Du kan använda infogade parametrar och en platsparametrarfil i samma distributionsåtgärd. Till exempel:

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

Mer information finns i Distribuera resurser med Bicep och Azure CLI.

Azure PowerShell

Från Azure PowerShell skickar du en lokal parameterfil med hjälp av parametern TemplateParameterFile .

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

Du kan använda infogade parametrar och en platsparametrarfil i samma distributionsåtgärd. Till exempel:

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

Mer information finns i Distribuera resurser med Bicep och Azure PowerShell. För att distribuera .bicep-filer behöver du Azure PowerShell version 5.6.0 eller senare.

Parameterpriorence

Du kan använda infogade parametrar och en lokal parameterfil i samma distributionsåtgärd. Du kan till exempel ange vissa värden i filen med lokala parametrar och lägga till andra värden infogade under distributionen. Om du anger värden för en parameter i både den lokala parameterfilen och infogade värden har det infogade värdet företräde.

Du kan använda en extern JSON-parameterfil genom att ange URI:n för filen. Den externa Bicep-parameterfilen stöds inte för närvarande. När du använder en extern parameterfil kan du inte skicka andra värden antingen infogade eller från en lokal fil. Alla infogade parametrar ignoreras. Ange alla parametervärden i den externa filen.

Parameternamnkonflikter

Om Bicep-filen innehåller en parameter med samma namn som en av parametrarna i PowerShell-kommandot presenterar PowerShell parametern från Bicep-filen med postfixet FromTemplate. En parameter med namnet ResourceGroupName i Bicep-filen står till exempel i konflikt med parametern ResourceGroupName i cmdleten New-AzResourceGroupDeployment . Du uppmanas att ange ett värde för ResourceGroupNameFromTemplate. Undvik den här förvirringen genom att använda parameternamn som inte används för distributionskommandon.

Nästa steg