Erstellen von Parameterdateien für die Bicep-Bereitstellung

Anstatt Parameter als Inlinewerte in Ihrem Skript zu übergeben, können Sie eine Bicep-Parameterdatei mit der .bicepparam-Dateierweiterung oder eine JSON-Parameterdatei verwenden, die die Parameterwerte enthält. In diesem Artikel erfahren Sie, wie Sie Parameterdateien erstellen.

Hinweis

Die Bicep-Parameterdatei wird 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. Diese Beziehung wird mithilfe der using-Anweisung in der Bicep-Parameterdatei hergestellt.

Sie können Bicep-Parameterdateien in JSON-Parameterdateien kompilieren, um sie mit einer Bicep-Datei bereitzustellen. Siehe build-params. Sie können eine JSON-Parameterdatei auch in eine Bicep-Parameterdatei dekompilieren. Siehe 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>

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 benötigen Bicep CLI Version 0.21.X oder höher für die Verwendung von Variablen in einer .bicepparam-Datei. Im Folgenden finden Sie einige 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
}

Beachten Sie, dass die Parameterdatei Parameterwerte als Nur-Text speichert. 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, bewahren Sie den Wert in einem Schlüsseltresor auf. Anstatt den vertraulichen Wert Ihrer Parameterdatei hinzuzufügen, verwenden Sie die Funktion „getSecret“, um ihn abzurufen. Weitere Informationen finden Sie unter Verwenden von Azure Key Vault zum Übergeben eines sicheren Parameterwerts 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 Bicep-Parameterdatei hat die Dateierweiterung .bicepparam.

Erstellen Sie mehr als eine Parameterdatei, wenn Sie die Bereitstellung in unterschiedlichen Umgebungen durchführen möchten. Wenn Sie die Parameterdateien benennen, identifizieren Sie deren Verwendung, z. B. Entwicklung und Produktion. Verwenden Sie beispielsweise main.dev.bicepparam und main.prod.bicepparam, um Ressourcen bereitzustellen.

Definieren von Parameterwerten

Um zu bestimmen, wie die Parameternamen und -werte definiert werden, öffnen Sie Ihre Bicep-Datei. Sehen Sie sich den Parameterabschnitt 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'

In der Parameterdatei ist das erste Detail der Name 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.

Nachdem Sie das Schlüsselwort „param“ in Visual Studio Code eingegeben haben, werden Sie zur Eingabe der verfügbaren Parameter und ihrer Beschreibungen aus der verknüpften Bicep-Datei aufgefordert:

Screenshot of the prompt of the available parameters.

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

Screenshot of the parameter data type and description.

Beachten Sie die Parametertypskala. Die Parametertypen in ihrer Parameterdatei müssen die gleichen Typen wie Ihre Bicep-Datei verwenden. In diesem Beispiel sind beide Parametertypen Zeichenfolgen.

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

Überprüfen Sie die Bicep-Datei auf Parameter mit einem Standardwert. Wenn ein Parameter über einen Standardwert verfügt, können Sie einen Wert in der Parameterdatei angeben, aber er ist 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 will use default value if not provided.

Überprüfen Sie die zulässigen Werte der Bicep-Datei und alle Einschränkungen, z. B. die maximale Länge. Diese Werte geben den Wertebereich an, den Sie für einen Parameter angeben können. In diesem Beispiel kannstoragePrefix 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

Es gibt zwei Optionen, mit denen Sie eine Parameterdatei generieren können: entweder über Visual Studio Code oder mithilfe der Bicep-Befehlszeilenschnittstelle. Mit beiden Methoden können Sie die Parameterdatei von einer Bicep-Datei ableiten. Für die Option mit Visual Studio Code siehe Generieren der Parameterdatei. Für die Option mit der Bicep-Befehlszeilenschnittstelle siehe Generieren der Parameterdatei.

Erstellen einer Bicep-Parameterdatei

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

Bereitstellen der Bicep-Datei mit Parameterdatei

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

Mit Azure CLI Version 2.53.0 oder höher und Bicep CLI Version 0.22.X oder höher können Sie eine Bicep-Datei mithilfe einer Bicep-Parameterdatei bereitstellen. Bei der using-Anweisung in der Bicep-Parameterdatei muss die Option --template-file nicht angegeben werden, wenn Sie eine Bicep-Parameterdatei für die Option --parameters angeben. Das Einschließen der Option --template-file führt zum Fehler „Mit einer BICEPPARAM-Datei ist nur eine BICEP-Vorlage zulässig“.

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

Weitere Informationen finden Sie unter Bereitstellen von Ressourcen mit Bicep und der Azure CLI.

Ü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

Weitere Informationen finden Sie unter Bereitstellen von Ressourcen mit Bicep und Azure 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.

Sie können eine externe Parameterdatei verwenden, indem Sie den URI der Datei bereitstellen. Wenn Sie eine externe Parameterdatei verwenden, können Sie keine anderen Werte (weder inline noch aus einer lokalen Datei) übergeben. Alle Inlineparameter werden ignoriert. Stellen Sie alle Parameterwerte in der externen Datei bereit.

Parameternamenskonflikte

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

Nächste Schritte