Freigeben über

Parameter in Bicep

  • Artikel

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.

Bicep erlaubt maximal 256 Parameter. 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.

Parameter definieren

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

@<decorator>(<argument>)
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.

Festlegen von Standardwerten

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

Sie können jedoch nicht auf eine Variable als Standardwert verweisen.

Verwenden von Decorator-Elementen

Parameter verwenden Decorators für Einschränkungen oder Metadaten. Die Decorators haben das Format @expression und werden über der Deklaration des Parameters platziert. In der folgenden Tabelle werden die für Parameter verfügbaren Decorator-Elemente gezeigt.

Decorator Anwenden auf Argument Beschreibung
Zugelassen all array Verwenden Sie diesen Decorator, um sicherzustellen, dass der Benutzer korrekte Werte bereitstellt. Dieses Decorator-Element ist nur für param-Anweisungen zulässig. Um zu deklarieren, dass eine Eigenschaft einer Gruppe vordefinierter Werte in einer type- oder output-Anweisung angehören muss, verwenden Sie die Union-Typsyntax. Die Union-Typsyntax kann auch in param-Anweisungen verwendet werden.
Beschreibung all Zeichenfolge Text, der erklärt, wie der Parameter zu verwenden ist. Die Beschreibung wird den Benutzern über das Portal angezeigt.
discriminator Objekt Zeichenfolge Verwenden Sie dieses Decorator-Element, um sicherzustellen, dass die richtige Unterklasse identifiziert und verwaltet wird. Weitere Informationen finden Sie unter Benutzerdefinierter markierter Union-Datentyp.
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.
sealed Objekt none Erhöhen Sie BCP089 von einer Warnung auf einen Fehler, wenn ein Eigenschaftenname eines benutzerdefinierten Datentyps wahrscheinlich einen Tippfehler enthält. Weitere Informationen finden Sie unter Erhöhen der Fehlerebene.
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

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.

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:

Verwenden Sie Markdown-formatierten Text in VSCode

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

Diskriminator

Weitere Informationen finden Sie unter Benutzerdefinierter markierter Union-Datentyp.

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

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

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.

Versiegelt

Weitere Informationen finden Sie unter Erhöhen der Fehlerebene.

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

Es gibt mehrere Linter-Regeln für dieses Decorator-Element: Parameter sichern Standard, Parameter in geschachtelten Bereitstellungen sichern und Geheimnisse in Parametern sichern.

Parameter verwenden

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

Verwenden von Objekten 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@2023-11-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