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:

Bicep-Parameterdatei

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

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

Sie können die Anweisung mit Bicep-Datei, ARM-JSON-Vorlagen, Bicep-Modulen und Vorlagenspezifikationen verwenden. Zum Beispiel:

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

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

JSON-Parameterdatei

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "<first-parameter-name>": {
      "value": "<first-value>"
    },
    "<second-parameter-name>": {
      "value": "<second-value>"
    }
  }
}

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.

Bicep-Parameterdatei

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.

JSON-Parameterdatei

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "exampleString": {
      "value": "test string"
    },
    "exampleInt": {
      "value": 4
    },
    "exampleBool": {
      "value": true
    },
    "exampleArray": {
      "value": [
        "value 1",
        "value 2"
      ]
    },
    "exampleObject": {
      "value": {
        "property1": "value1",
        "property2": "value2"
      }
    }
  }
}

Dateiname

Bicep-Parameterdatei

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.

JSON-Parameterdatei

Die allgemeine Konvention für das Benennen der Parameterdatei ist das Hinzufügen von Parametern zum Namen der Bicep-Datei. Wenn Ihre Bicep-Datei beispielsweise den Namen azuredeploy.bicep hat, ergibt sich für Ihre Parameterdatei der Name azuredeploy.parameters.json. Anhand dieser Namenskonvention können Sie die Verbindung zwischen der Bicep-Datei und den Parametern erkennen.

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 azuredeploy.parameters-dev.json und azuredeploy.parameters-prod.json, 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.

Bicep-Parameterdatei

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:

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

JSON-Parameterdatei

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
    },
    "storageAccountType": {
    }
  }
}

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.

Bicep-Parameterdatei

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

JSON-Parameterdatei

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": ""
    },
    "storageAccountType": {
      "value": ""
    }
  }
}

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

Bicep-Parameterdatei

using 'main.bicep'

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

JSON-Parameterdatei

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": "" // This value must be provided.
    },
    "storageAccountType": {
      "value": "" // This value is optional. Bicep will use default value if not provided.
    }
  }
}

Hinweis

Für Inlinekommentare können Sie entweder „//“ oder „/* ... */“ verwenden. Speichern Sie die Parameterdateien in Visual Studio Code mit dem Dateityp JSONC. Andernfalls wird eine Fehlermeldung angezeigt, die besagt, dass Kommentare in JSON nicht zulässig sind.

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

Bicep-Parameterdatei

using 'main.bicep'

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

JSON-Parameterdatei

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": "storage"
    },
    "storageAccountType": {
      "value": "Standard_ZRS"
    }
  }
}

Hinweis

Ihre Parameterdatei kann nur Werte für Parameter enthalten, die in der Bicep-Datei definiert sind. Wenn die Parameterdatei zusätzliche Parameter enthält, die nicht mit den Parametern in der Bicep-Datei identisch sind, erhalten Sie eine Fehlermeldung.

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

Azure CLI

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

Bicep-Parameterdatei

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. Mit der using-Anweisung in der Bizeps-Parameterdatei brauchen Sie den --template-file-Schalter nicht anzugeben, wenn Sie eine Bizeps-Parameterdatei für den --parameters-Schalter spezifizieren.

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

JSON-Parameterdatei

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.bicep \
  --parameters storage.parameters.json

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

Bicep-Parameterdatei

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

JSON-Parameterdatei

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.bicep \
  --parameters storage.parameters.json \
  --parameters storageAccountType=Standard_LRS

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

Azure PowerShell

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

Bicep-Parameterdatei

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

JSON-Parameterdatei

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

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

Bicep-Parameterdatei

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

JSON-Parameterdatei

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

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 JSON Parameterdatei verwenden, indem Sie den URI der Datei bereitstellen. Die Externe Bicep-Parameterdatei wird derzeit nicht unterstützt. 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

• Weitere Informationen zum Definieren von Parametern in einer Bicep-Datei finden Sie unter Parameter in Bicep.
• Informationen zum Abrufen von vertraulichen Werten finden Sie unter Verwenden von Azure Key Vault zum Übergeben eines sicheren Parameterwerts während der Bereitstellung.