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.