Freigeben über

Erstellen einer Parameterdatei für die Bicep-Bereitstellung

  • Artikel

In diesem Artikel wird erläutert, wie Sie eine Parameterdatei erstellen, die Sie verwenden können, anstatt Parameter als Inlinewerte in Ihrem Skript zu übergeben. Sie können entweder eine Bicep-Parameterdatei mit der .bicepparam-Dateierweiterung oder eine JSON-Parameterdatei verwenden, die den Parameterwert enthält.

Hinweis

Bicep-Parameterdateien werden nur in Bicep CLI ab Version 0.18.4, Azure CLI ab Version 2.47.0 und Azure PowerShell ab Version 9.7.1 unterstützt.

Einer einzelnen Bicep-Datei können mehrere Bicep-Parameterdateien zugeordnet sein. Jede Bicep-Parameterdatei ist jedoch für eine bestimmte Bicep-Datei vorgesehen. Sie können diese Beziehung mithilfe der using-Anweisung in der Bicep-Parameterdatei herstellen.

Sie können Bicep-Parameterdateien in JSON-Parameterdateien kompilieren, die Sie mit einer Bicep-Datei bereitstellen können. Weitere Informationen finden Sie unter build-params. Sie können eine JSON-Parameterdatei auch in eine Bicep-Parameterdatei dekompilieren. Weitere Informationen finden Sie unter decompile-params.

Parameterdatei

Eine Parameterdatei verwendet das folgende Format:

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

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

Sie können die using-Anweisung mit einer Bicep-Datei, Azure Resource Manager-JSON-Vorlagen, Bicep-Modulen und Vorlagenspezifikationen anwenden. Zum Beispiel:

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

Weitere Informationen finden Sie unter Using-Anweisung.

Ausdrücke können mit dem Standardwert verwendet werden. Beispiel:

using 'main.bicep'

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

Sie können auf Umgebungsvariablen als Parameterwerte verweisen. Beispiel:

using './main.bicep'

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

Sie können Variablen definieren und verwenden. Sie müssen Bicep CLI Version 0.21.X oder höher für die Verwendung von Variablen in .bicepparam-Dateien verwenden. Hierzu folgende Beispiele:

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
}

Hinweis

Eine Parameterdatei speichert Parameterwerte als Nur-Text. Aus Sicherheitsgründen wird dieser Ansatz für vertrauliche Werte wie Kennwörter nicht empfohlen.

Wenn Sie einen Parameter mit einem vertraulichen Wert übergeben müssen, sollten Sie den Wert in einem Schlüsseltresor aufbewahren. Anstatt den vertraulichen Wert Ihrer Parameterdatei hinzuzufügen, verwenden Sie die getSecret-Funktion, um ihn abzurufen. Weitere Informationen finden Sie unter Verwenden von Azure Key Vault zum Übergeben eines Geheimnisses als Parameter während der Bicep-Bereitstellung.

Parametertypformate

Das folgende Beispiel zeigt die Formate verschiedener Parametertypen: Zeichenfolge, ganze Zahl, Boolean, Array und 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'
}

Verwenden Sie die Bicep-Syntax, um Objekte und Arrays zu deklarieren.

Dateiname

Die Dateierweiterung für eine Bicep-Parameterdatei ist .bicepparam.

Erstellen Sie mehr als eine Parameterdatei, um in mehreren Umgebungen Bereitstellungen durchzuführen. Wenn Sie mehrere Parameterdateien verwenden, bezeichnen Sie sie entsprechend ihrer Verwendung. Verwenden Sie beispielsweise bei der Bereitstellung von Ressourcen die Bezeichnung main.dev.bicepparam für die Entwicklung und die Bezeichnung main.prod.bicepparam für die Produktion.

Definieren von Parameterwerten

Um zu bestimmen, wie die Parameternamen und -werte definiert werden, öffnen Sie Ihre Bicep-Datei. Sehen Sie sich den Abschnitt parameters in der Bicep-Datei an. Die folgenden Beispiele zeigen die Parameter aus einer Bicep-Datei namens main.bicep:

@maxLength(11)
param storagePrefix string

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

Suchen Sie in der Parameterdatei nach dem Namen der einzelnen Parameter. Der Parameternamen in der Parameterdatei müssen mit den Parameternamen in der Bicep-Datei identisch sein.

using 'main.bicep'

param storagePrefix
param storageAccountType

Die using-Anweisung verknüpft die Bicep-Parameterdatei mit einer Bicep-Datei. Weitere Informationen finden Sie unter Using-Anweisung.

Wenn Sie das Schlüsselwort param in Visual Studio Code eingeben, werden Sie zur Eingabe der verfügbaren Parameter und ihrer Beschreibungen aus der verknüpften Bicep-Datei aufgefordert.

Screenshot der Eingabeaufforderung der verfügbaren Parameter.

Wenn Sie mit dem Mauszeiger auf einen param-Namen zeigen, können Sie den Parameterdatentyp und die Beschreibung sehen.

Screenshot der Parameterdatentypen und der Beschreibung.

Überprüfen Sie den Parametertypen, da die Parametertypen in Ihrer Parameterdatei die gleichen Typen wie Ihre Bicep-Datei verwenden müssen. In diesem Beispiel sind beide Parametertypen Zeichenfolgen:

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

Überprüfen Sie die Bicep-Datei auf Parameter, die einen Standardwert enthalten. Wenn ein Parameter über einen Standardwert verfügt, können Sie einen Wert in der Parameterdatei angeben, dies ist aber nicht erforderlich. Der Wert der Parameterdatei überschreibt den Standardwert der Bicep-Datei.

using 'main.bicep'

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

Überprüfen Sie die zulässigen Werte der Bicep-Datei, um herauszufinden, ob Einschränkungen, z. B. eine Maximallänge, vorhanden sind. Die zulässigen Werte geben den Wertebereich an, den Sie für einen Parameter angeben können. In diesem Beispiel darf storagePrefix maximal 11 Zeichen enthalten, und storageAccountType muss einen zulässigen Wert angeben.

using 'main.bicep'

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

Generieren der Parameterdatei

Sie können eine Parameterdatei entweder mit Visual Studio Code oder mit der Bicep CLI erstellen. Bei beiden Tools können Sie eine Bicep-Datei verwenden, um eine Parameterdatei zu generieren. Weitere Informationen zur Vorgehensweise in Visual Studio Code finden Sie unter Generieren von Parameterdateien und für die Bicep CLI unter Generieren von Parameterdateien.

Erstellen einer Bicep-Parameterdatei

Über die Bicep-CLI können Sie eine Bicep-Parameterdatei als JSON-Parameterdatei erstellen. Weitere Informationen finden Sie unter Erstellen einer Parameterdatei.

Bereitstellen der Bicep-Datei mit Parameterdatei

Azure-Befehlszeilenschnittstelle

Über die Azure CLI können Sie eine Parameterdatei während Ihrer Bicep-Dateibereitstellung übergeben.

Ab der Azure CLI-Version 2.53.0 und der Bicep CLI-Version 0.22.X oder höher können Sie eine Bicep-Datei mithilfe einer Bicep-Parameterdatei bereitstellen. Mit der using-Anweisung in der Bicep-Parameterdatei müssen Sie den --template-file-Schalter nicht angeben, wenn Sie eine Bicep-Parameterdatei für den --parameters-Schalter festlegen.

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

Sie können Inlineparameter und eine Standortparameterdatei im selben Bereitstellungsvorgang verwenden. Zum Beispiel:

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

Weitere Informationen finden Sie unter Bereitstellen von Bicep-Dateien mit der Azure CLI.

Azure PowerShell

Übergeben Sie in Azure PowerShell eine lokale Parameterdatei mithilfe des TemplateParameterFile-Parameters.

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

Sie können Inlineparameter und eine Standortparameterdatei im selben Bereitstellungsvorgang verwenden. Zum Beispiel:

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

Weitere Informationen finden Sie unter Bereitstellen von Bicep-Dateien mit PowerShell. Zum Bereitstellen von .bicep-Dateien benötigen Sie Version 5.6.0 oder höher von Azure PowerShell.

Parameterrangfolge

Sie können Inlineparameter und eine lokale Parameterdatei im selben Bereitstellungsvorgang verwenden. Sie können beispielsweise einige Werte in der lokalen Parameterdatei angeben und weitere Werte während der Bereitstellung inline hinzufügen. Wenn Sie Werte für einen Parameter sowohl in der lokalen Parameterdatei als auch inline bereitstellen, haben die Inlinewerte Vorrang.

Obwohl externe Bicep-Parameterdateien derzeit nicht unterstützt werden, ist möglich, eine externe JSON-Parameterdatei zu verwenden, indem Sie den URI der Datei bereitstellt. Wenn Sie eine externe Parameterdatei verwenden, geben Sie alle Parameterwerte in der externen Datei an. Wenn Sie eine externe Parameterdatei verwenden, können Sie keine anderen Werte (weder Inline-Werte noch Werte aus einer lokalen Datei) übergeben, und alle Inline-Parameter werden ignoriert.

Parameternamenskonflikte

Wenn Ihre Bicep-Datei einen Parameter enthält, der denselben Namen besitzt wie einer der Parameter des Azure PowerShell-Befehls, zeigt Azure PowerShell den Parameter der Bicep-Datei mit dem Postfix FromTemplate an. Wenn beispielsweise ein Parameter namens ResourceGroupName in Ihrer Bicep-Datei einen Konflikt mit dem Parameter ResourceGroupName im Cmdlet New-AzResourceGroupDeployment verursacht, werden Sie zur Eingabe eines Werts für ResourceGroupNameFromTemplate aufgefordert. Verwenden Sie Parameternamen, die nicht für Bereitstellungsbefehle verwendet werden, um diese Verwechslung zu vermeiden.

Zugehöriger Inhalt