Parameter in Bicep

Dieser Artikel beschreibt, wie Sie in Ihrer Bicep-Datei Parameter definieren und verwenden. Durch Angeben verschiedener Werte für Parameter können Sie eine Bicep-Datei für verschiedene Umgebungen wiederverwenden.

Resource Manager löst Parameterwerte vor Beginn der Bereitstellungsvorgänge auf. Jedes Vorkommen des Parameters wird von Resource Manager durch den aufgelösten Wert ersetzt.

Jeder Parameter muss auf einen der Datentypen festgelegt werden.

Maximal 256 Parameter sind in einer Bicep-Datei zulässig. Weitere Informationen finden Sie unter Vorlagengrenzwerte.

Informationen zu bewährten Methoden für Parameter finden Sie unter Parameter.

Schulungsressourcen

Wenn Sie sich lieber anhand einer Schritt-für-Schritt-Anleitung über Parameter informieren möchten, lesen Sie den Abschnitt Wiederverwendbare Bizeps-Vorlagen mithilfe von Parametern erstellen.

Deklaration

Jeder Parameter hat einen Namen und einen Datentyp. Optional können Sie einen Standardwert für den Parameter angeben.

param <parameter-name> <parameter-data-type> = <default-value>

Ein Parameter kann nicht den gleichen Namen wie eine Variable, eine Ressource, eine Ausgabe oder ein anderer Parameter im gleichen Geltungsbereich aufweisen.

Das folgende Beispiel zeigt grundlegende Deklarationen von Parametern.

param demoString string
param demoInt int
param demoBool bool
param demoObject object
param demoArray array

Das Schlüsselwort param wird auch in Dateien vom Typ „bicepparam“ verwendet. In Dateien vom Typ „bicepparam“ müssen Sie nicht den Datentyp angeben, da er in Bicep-Dateien definiert ist.

param <parameter-name> = <value>

Weitere Informationen finden Sie unter Parameterdatei.

Benutzerdefinierte Typausdrücke können als Typklausel einer param-Anweisung verwendet werden. Beispiel:

param storageAccountConfig {
  name: string
  sku: string
}

Weitere Informationen finden Sie unter Benutzerdefinierte Datentypen.

Standardwert

Sie können für einen Parameter keinen Standardwert angeben. Der Standardwert wird verwendet, wenn während der Bereitstellung kein Wert angegeben wird.

param demoParam string = 'Contoso'

Ausdrücke können mit dem Standardwert verwendet werden. In Ausdrücken dürfen keine anderen Parametereigenschaften verwendet werden. Im Parameterabschnitt kann weder die reference-Funktion noch eine der list-Funktionen verwendet werden. Diese Funktionen rufen den Laufzeitstatus der Ressource ab und können nicht vor der Bereitstellung ausgeführt werden, wenn Parameter aufgelöst werden.

param location string = resourceGroup().location

Sie können einen anderen Parameterwert verwenden, um einen Standardwert zu erstellen. Mit der folgenden Vorlage wird aus dem Websitenamen ein Name für den Hostplan erstellt.

param siteName string = 'site${uniqueString(resourceGroup().id)}'
param hostingPlanName string = '${siteName}-plan'

output siteNameOutput string = siteName
output hostingPlanOutput string = hostingPlanName

Decorator-Elemente

Parameter verwenden Decorators für Einschränkungen oder Metadaten. Die Decorators haben das Format @expression und werden über der Deklaration des Parameters platziert. Sie können einen Parameter als sicher markieren, zulässige Werte angeben, die minimale und maximale Länge für eine Zeichenkette festlegen, den minimalen und maximalen Wert für eine ganze Zahl festlegen und eine Beschreibung des Parameters angeben.

Das folgende Beispiel zeigt zwei gängige Verwendungen für Dekoratoren.

@secure()
param demoPassword string

@description('Must be at least Standard_A3 to support 2 NICs.')
param virtualMachineSize string = 'Standard_DS1_v2'

In der folgenden Tabelle werden die verfügbaren Decorator-Elemente und deren Verwendung beschrieben.

Decorator	Anwenden auf	Argument	Beschreibung
Zugelassen	all	array	Zulässige Werte für den Parameter. Verwenden Sie diesen Decorator, um sicherzustellen, dass der Benutzer korrekte Werte bereitstellt.
description	all	Zeichenfolge	Text, der erklärt, wie der Parameter zu verwenden ist. Die Beschreibung wird den Benutzern über das Portal angezeigt.
maxLength	Array, Zeichenfolge	INT	Die maximale Länge für Zeichenfolge- und Array-Parameter. Der Stop-Wert ist inklusiv.
maxValue	INT	INT	Der maximale Wert für den ganzzahligen Parameter. Der Stop-Wert ist inklusiv.
metadata	all	Objekt	Benutzerdefinierte Eigenschaften, die auf den Parameter angewendet werden sollen. Kann eine Beschreibungseigenschaft enthalten, die dem Description-Decorator entspricht.
minLength	Array, Zeichenfolge	INT	Die minimale Länge für Zeichenfolge- und Array-Parameter. Der Stop-Wert ist inklusiv.
minValue	INT	INT	Der minimale Wert für den ganzzahligen Parameter. Der Stop-Wert ist inklusiv.
secure	String-Objekt	none	Markiert den Parameter als sicher. Der Wert eines sicheren Parameters wird weder im Bereitstellungsverlauf gespeichert noch protokolliert. Weitere Informationen finden Sie unter Sichern von Zeichenfolgen und Objekten.

Decorators befinden sich im sys-Namespace. Wenn Sie diesen Decorator von einem anderen Element gleichen Namens unterscheiden müssen, stellen Sie dem Decorator sys voran. Zum Beispiel, wenn Ihre Bicep Datei einen Parameter mit dem Namen description enthält, müssen Sie den sys Namespace hinzufügen, wenn Sie den description Dekorator verwenden.

@sys.description('The name of the instance.')
param name string
@sys.description('The description of the instance to display.')
param description string

Die verfügbaren Dekoratoren werden in den folgenden Abschnitten beschrieben.

Sichere Parameter

Sie können Zeichenfolgen- oder Objektparameter als sicher kennzeichnen. Der Wert eines sicheren Parameters wird weder im Bereitstellungsverlauf gespeichert noch protokolliert.

@secure()
param demoPassword string

@secure()
param demoSecretObject object

Zulässige Werte

Sie können für einen Parameter zulässige Werte definieren. Diese werden in einem Array bereitgestellt. Wenn für den Parameter ein Wert übergeben wird, der nicht zu den zulässigen Werten gehört, schlägt die Bereitstellung während der Überprüfung fehl.

@allowed([
  'one'
  'two'
])
param demoEnum string

Wenn Sie zulässige Werte für einen Arrayparameter definieren, kann der tatsächliche Wert eine beliebige Teilmenge der zulässigen Werte sein.

Längenbeschränkungen

Sie können die minimale und maximale Länge von Zeichenfolgen- und Arrayparametern angeben. Sie können eine oder beide Einschränkungen festlegen. Bei Zeichenfolgen gibt die Länge die Anzahl der Zeichen an. Bei Arrays gibt die Länge die Anzahl der Elemente im Array an.

Im folgenden Beispiel werden zwei Parameter deklariert. Ein Parameter ist für den Namen eines Speicherkontos, der 3–24 Zeichen enthalten muss. Der andere Parameter ist ein Array, das 1–5 Elemente aufweisen muss.

@minLength(3)
@maxLength(24)
param storageAccountName string

@minLength(1)
@maxLength(5)
param appNames array

Ganzzahlige Einschränkungen

Sie können die minimalen und maximalen Werte für ganzzahlige Parameter festlegen. Sie können eine oder beide Einschränkungen festlegen.

@minValue(1)
@maxValue(12)
param month int

BESCHREIBUNG

Fügen Sie dem Parameter eine Beschreibung hinzu, damit Benutzer verstehen, welchen Wert sie angeben sollen. Wenn ein Benutzer die Vorlage über das Portal bereitstellt, wird der in der Beschreibung angegebene Text automatisch als Tipp für diesen Parameter verwendet. Beschreibungen sollten nur hinzugefügt werden, wenn der Text mehr Informationen bietet, als aus dem Parameternamen abgeleitet werden können.

@description('Must be at least Standard_A3 to support 2 NICs.')
param virtualMachineSize string = 'Standard_DS1_v2'

Mit Markdown formatierter Text kann für den Beschreibungstext verwendet werden:

@description('''
Storage account name restrictions:
- Storage account names must be between 3 and 24 characters in length and may contain numbers and lowercase letters only.
- Your storage account name must be unique within Azure. No two storage accounts can have the same name.
''')
@minLength(3)
@maxLength(24)
param storageAccountName string

Wenn Sie den Cursor über storageAccountName in VS Code bewegen, wird der formatierte Text angezeigt:

Stellen Sie sicher, dass der Text die richtige Markdown-Formatierung aufweist. Andernfalls wird er beim Rendern möglicherweise nicht ordnungsgemäß angezeigt.

Metadaten

Wenn Sie benutzerdefinierte Eigenschaften haben, die Sie auf einen Parameter anwenden möchten, fügen Sie einen Metadaten-Decorator hinzu. Definieren Sie innerhalb der Metadaten ein Objekt mit den benutzerdefinierten Namen und Werten. Das Objekt, das Sie für die Metadaten definieren, kann Eigenschaften eines beliebigen Namens und Typs enthalten.

Sie können diesen Decorator verwenden, um Informationen über den Parameter nachzuverfolgen, für die es nicht sinnvoll wäre, sie in die Beschreibung aufzunehmen.

@description('Configuration values that are applied when the application starts.')
@metadata({
  source: 'database'
  contact: 'Web team'
})
param settings object

Wenn Sie ein @metadata()-Decorator-Element mit einer Eigenschaft bereitstellen, die mit einem anderen Decorator-Element in Konflikt steht, hat dieses Decorator-Element immer Vorrang vor allen Elementen im @metadata()-Decorator-Element. Daher ist die in Konflikt stehende Eigenschaft innerhalb des Werts @metadata() redundant und wird ersetzt. Weitere Informationen finden Sie unter Keine widersprüchlichen Metadaten.

Verwenden eines Parameters

Um auf den Wert des Parameters zu verweisen, verwenden Sie den Parameternamen. Im folgenden Beispiel wird ein Parameterwert für den Namen eines Schlüsseltresors verwendet.

param vaultName string = 'keyVault${uniqueString(resourceGroup().id)}'

resource keyvault 'Microsoft.KeyVault/vaults@2019-09-01' = {
  name: vaultName
  ...
}

Objekte als Parameter

Es kann einfacher sein, in Beziehung stehende Werte zu organisieren, indem sie als Objekt übergeben werden. Diese Vorgehensweise verringert auch die Anzahl der Parameter in der Vorlage.

Das folgende Beispiel zeigt einen Parameter, bei dem es sich um ein Objekt handelt. Der Standardwert gibt die erwarteten Eigenschaften für das Objekt an. Diese Eigenschaften werden in der Definition der bereitzustellenden Ressource verwendet.

param vNetSettings object = {
  name: 'VNet1'
  location: 'eastus'
  addressPrefixes: [
    {
      name: 'firstPrefix'
      addressPrefix: '10.0.0.0/22'
    }
  ]
  subnets: [
    {
      name: 'firstSubnet'
      addressPrefix: '10.0.0.0/24'
    }
    {
      name: 'secondSubnet'
      addressPrefix: '10.0.1.0/24'
    }
  ]
}

resource vnet 'Microsoft.Network/virtualNetworks@2020-06-01' = {
  name: vNetSettings.name
  location: vNetSettings.location
  properties: {
    addressSpace: {
      addressPrefixes: [
        vNetSettings.addressPrefixes[0].addressPrefix
      ]
    }
    subnets: [
      {
        name: vNetSettings.subnets[0].name
        properties: {
          addressPrefix: vNetSettings.subnets[0].addressPrefix
        }
      }
      {
        name: vNetSettings.subnets[1].name
        properties: {
          addressPrefix: vNetSettings.subnets[1].addressPrefix
        }
      }
    ]
  }
}

Nächste Schritte

• Weitere Informationen zu den verfügbaren Eigenschaften für Parameter finden Sie unter Verstehen der Struktur und Syntax von Bicep-Dateien.
• Weitere Informationen zum Übergeben von Parameterwerten als Datei finden Sie unter Erstellen einer Bicep-Parameterdatei.
• Informationen zum Bereitstellen von Parameterwerten bei der Bereitstellung finden Sie unter Bereitstellen mit Azure CLIund Bereitstellen mit Azure PowerShell.