Verständnis von Parametern

  • 8 Minuten

Mit Parameternkönnen Sie einer Bicep-Vorlage zum Zeitpunkt der Bereitstellung Informationen bereitstellen. Sie können eine Bicep-Vorlage flexibel und wiederverwendbar gestalten, indem Sie Parameter in Ihrer Vorlage deklarieren.

Decorators bieten eine Möglichkeit, Einschränkungen und Metadaten an einen Parameter anzufügen, die jedem, der Ihre Vorlagen verwendet, mitteilen, welche Informationen er bereitstellen muss.

In dieser Lerneinheit erfahren Sie mehr über Parameter und Decorators.

Deklarieren eines Parameters

In einer Bicep-Vorlage deklarieren Sie einen Parameter mithilfe des Schlüsselworts param. Sie können diese Deklarationen an einer beliebigen Stelle in der Vorlagendatei einfügen, obwohl es in der Regel eine gute Idee ist, sie an den Anfang der Datei zu stellen, damit Ihr Bicep-Code leicht zu lesen ist.

So deklarieren Sie einen Parameter:

param environmentName string

Sehen Sie sich an, wie die einzelnen Teile funktionieren:

  • param zeigt Bicep an, dass Sie einen Parameter deklarieren.

  • environmentName verweist auf den Namen des Parameters. Obwohl der Parametername alles sein kann, sollten Sie den Namen für die Vorlagenbenutzer klar und verständlich wählen. Innerhalb derselben Vorlage können Sie auch mithilfe seines Namens auf den Parameter verweisen. Parameternamen müssen eindeutig sein. Sein Name kann nicht denselben Namen wie eine Variable oder Ressource in derselben Bicep-Datei haben.

    Tipp

    Verwenden Sie bewährte Methoden für die Benennung von Parameterdeklarationen. Eine gute Namenskonvention sorgt dafür, dass Ihre Vorlagen problemlos les- und nachvollziehbar sind. Verwenden Sie klare, aussagekräftige Namen und eine konsistente Benennungsstrategie.

  • string verweist auf den Typ des Parameters.

    Tipp

    Denken Sie sorgfältig über die Parameter nach, die Ihre Vorlage verwendet. Verwenden Sie nach Möglichkeit Parameter für Einstellungen, die sich zwischen Bereitstellungen ändern. Variablen und hartcodierte Werte können für Einstellungen verwendet werden, die sich zwischen Bereitstellungen nicht ändern.

Hinzufügen eines Standardwerts

Sie können Parametern in Ihren Vorlagen Standardwerte zuweisen. Durch das Zuweisen eines Standardwerts machen Sie den Parameter optional. Wenn die Vorlage ohne Angabe eines Werts für den Parameter bereitgestellt wird, wird der Standardwert zugewiesen.

So fügen Sie einen Standardwert hinzu:

param environmentName string = 'dev'

Dem Parameter environmentName wird der Standardwert dev zugewiesen.

Sie können Ausdrücke als Standardwerte verwenden. Hier sehen Sie ein Beispiel für einen Zeichenfolgenparameter namens location mit einem Standardwert, der auf den Ort der aktuellen Ressourcengruppe festgelegt ist:

param location string = resourceGroup().location

Tipp

Gehen Sie sorgsam bei den Standardwerten vor, die Sie verwenden. Vergewissern Sie sich, dass die Bereitstellung der Bicep-Datei mit den Standardwerten für den Benutzer sicher ist. Ziehen Sie beispielsweise die Verwendung kostengünstiger Tarife und SKUs in Betracht, damit eine Bereitstellung der Vorlage in einer Testumgebung keine unnötigen hohen Kosten verursacht.

Grundlegendes zu Parametertypen

Wenn Sie einen Parameter deklarieren, müssen Sie Bicep mitteilen, welche Art von Informationen der Parameter enthalten soll. Bicep stellt sicher, dass der dem Parameter zugewiesene Wert mit dem Parametertyp kompatibel ist.

Parameter in Bicep können einen der folgenden Typen aufweisen:

  • string, mit dem Sie beliebigen Text eingeben können.
  • int, mit dem Sie eine Zahl eingeben können.
  • bool, der einen booleschen Wert („wahr“ oder „falsch“) darstellt.
  • object und array, die strukturierte Daten und Listen darstellen.

Objekte

Sie können Objektparameter verwenden, um strukturierte Daten an einem Ort zu kombinieren. Ein Objekt kann mehrere Eigenschaften unterschiedlicher Typen aufweisen. Sie können Objekte in Ressourcendefinitionen, in Variablen oder in Ausdrücken in Ihrer Bicep-Datei verwenden. Hier sehen Sie ein Beispiel für ein Objekt:

param appServicePlanSku object = {
  name: 'F1'
  tier: 'Free'
  capacity: 1
}

Dieser Parameter ist ein Objekt mit den zwei Zeichenfolgeneigenschaften name und tier sowie einer ganzzahligen Eigenschaft capacity. Beachten Sie, dass sich jede der Eigenschaften in einer eigenen Zeile befindet.

Wenn Sie auf den Parameter in der Vorlage verweisen, können Sie die einzelnen Eigenschaften des Objekts auswählen, indem Sie einen Punkt gefolgt von dem Namen der Eigenschaft verwenden, wie in diesem Beispiel:

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku.name
    tier: appServicePlanSku.tier
    capacity: appServicePlanSku.capacity
  }
}

Wichtig

Denken Sie daran, dass Sie nicht den Typ jeder Eigenschaft innerhalb eines Objekts angeben. Wenn Sie jedoch den Wert einer Eigenschaft verwenden, muss ihr Typ mit dem erwarteten Wert übereinstimmen. Im vorherigen Beispiel müssen sowohl der Name als auch die Dienstebene des App Service-Plans der SKU Zeichenfolgen sein.

Ein weiteres Beispiel für die Verwendung eines Objektparameters ist die Angabe von Ressourcentags. Sie können den von Ihnen bereitgestellten Ressourcen benutzerdefinierte Tagmetadaten anfügen, mit denen Sie wichtige Informationen zu einer Ressource identifizieren können.

Tags sind nützlich für Szenarien wie das Nachverfolgen, welches Team eine Ressource besitzt, oder ob eine Ressource zu einer Produktions- oder Nichtproduktionsumgebung gehört. In der Regel verwenden Sie für jede Umgebung unterschiedliche Tags, aber Sie sollten dieselben Tagwerte für alle Ressourcen in Ihrer Vorlage wiederverwenden. Aus diesem Grund sind Ressourcentags eine gute Verwendung für einen Objektparameter, wie in diesem Beispiel:

param resourceTags object = {
  EnvironmentName: 'Test'
  CostCenter: '1000100'
  Team: 'Human Resources'
}

Wenn Sie eine Ressource in Ihrer Bicep-Datei definieren, können Sie sie überall dort wiederverwenden, wo Sie die Eigenschaft tags definieren:

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  tags: resourceTags
  sku: {
    name: 'S1'
  }
}

resource appServiceApp 'Microsoft.Web/sites@' = {
  name: appServiceAppName
  location: location
  tags: resourceTags
  kind: 'app'
  properties: {
    serverFarmId: appServicePlan.id
  }
}

Arrays

Ein Array ist eine Liste von Elementen. Beispielsweise können Sie ein Array von Zeichenfolgenwerten verwenden, um eine Liste mit E-Mail-Adressen für eine Azure Monitor-Aktionsgruppe zu deklarieren. Sie können auch ein Array von Objekten verwenden, um eine Liste von Subnetzen für ein virtuelles Netzwerk darzustellen.

Hinweis

Sie können nicht den Typ einzelner Elemente angeben, die ein Array enthalten muss. Beispielsweise können Sie nicht angeben, dass ein Array Zeichenfolgen enthalten muss.

Wir sehen uns hierzu ein Beispiel an. Mit Azure Cosmos DB können Sie Datenbankkonten erstellen, die sich über mehrere Regionen erstrecken, und die Datenreplikation wird automatisch für Sie übernommen. Wenn Sie ein neues Datenbankkonto bereitstellen, müssen Sie die Liste der Azure-Regionen angeben, in denen das Konto bereitgestellt werden soll. Häufig benötigen Sie eine andere Liste von Standorten für verschiedene Umgebungen. Um beispielsweise Geld in Ihrer Testumgebung zu sparen, können Sie nur einen oder zwei Standorte verwenden. In Ihrer Produktionsumgebung können Sie jedoch mehrere Standorte verwenden.

Sie können einen Arrayparameter erstellen, der eine Liste von Standorten angibt:

param cosmosDBAccountLocations array = [
  {
    locationName: 'australiaeast'
  }
  {
    locationName: 'southcentralus'
  }
  {
    locationName: 'westeurope'
  }
]

Tipp

Das voranstehende Beispiel ist ein Array von Objekten. Jedes Objekt verfügt über eine locationName-Eigenschaft, die von Azure Cosmos DB erwartet wird. Wenn Sie mit einer Ressourcendefinition in Visual Studio Code arbeiten, können Sie zunächst Ressourceneigenschaften eingeben, damit Sie IntelliSense von den Bicep-Tools erhalten. Mit diesem Ansatz können Sie einige Beispielwerte erstellen. Nachdem Sie mit der Konfiguration zufrieden sind, verschieben Sie diesen Abschnitt des Bicep-Codes in den Parameter. Auf diese Weise können Sie eine hartcodierte Eigenschaft durch einen Parameter ersetzen, der während jeder Bereitstellung geändert werden kann, während gleichzeitig sichergestellt ist, dass die Ressource ordnungsgemäß konfiguriert ist.

Wenn Sie Ihre Azure Cosmos DB-Ressource deklarieren, können Sie jetzt auf den Arrayparameter verweisen:

resource account 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  name: accountName
  location: location
  properties: {
    locations: cosmosDBAccountLocations
  }
}

Es ist dann einfach, einen anderen Parameterwert für Ihre Entwicklungsumgebung zu verwenden, indem Sie den Wert des Parameters ändern. In Kürze erfahren Sie, wie Sie verschiedene Parameterwerte bereitstellen können, ohne Ihre ursprüngliche Vorlage zu ändern.

Angeben einer Liste zulässiger Werte

Manchmal müssen Sie sicherstellen, dass ein Parameter bestimmte Werte hat. Beispielsweise kann Ihr Team entscheiden, dass App Service-Pläne für die Produktion mittels Premium v3-SKUs bereitgestellt werden sollen. Um diese Regel zu erzwingen, können Sie den Parameter-Decorator @allowed verwenden. Ein Parameter-Decorator ist eine Möglichkeit, Informationen an Bicep zu übergeben, was der Wert eines Parameters sein muss. Im Folgenden sehen Sie, wie ein Zeichenfolgenparameter namens appServicePlanSkuName so eingeschränkt werden kann, dass nur ein paar spezifische Werte zugewiesen werden können:

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
param appServicePlanSkuName string

Tipp

Verwenden Sie den Decorator @allowed sparsam. Wenn Sie diesen Decorator zu häufig verwenden, blockieren Sie möglicherweise gültige Bereitstellungen, wenn Sie die Liste nicht auf dem neuesten Stand halten. Im vorherigen Beispiel sind nur Premium v3-SKUs in der Produktion zulässig. Wenn Sie dieselbe Vorlage verwenden müssen, um kostengünstigere Nichtproduktionsumgebungen bereitzustellen, kann die Liste der zulässigen Werte an der Verwendung anderer SKUs verhindern, die Sie verwenden müssen.

Einschränken von Parameterlänge und -werten

Wenn Sie Zeichenfolgenparameter verwenden, müssen Sie häufig die Länge der Zeichenfolge begrenzen. Sehen wir uns das Beispiel der Benennung von Azure-Ressourcen an. Für alle Azure-Ressourcentypen gelten Grenzwerte für die Länge ihrer Namen. Es ist eine bewährte Methode, die minimale und maximale Zeichenlänge für Parameter anzugeben, die die Benennung steuern, um Fehler zu einem späteren Zeitpunkt während der Bereitstellung zu vermeiden. Sie können die Decorators @minLength und @maxLength für die minimale und maximale Zeichenlänge verwenden, die Sie für einen Parameter zulassen möchten.

Im Folgenden Beispiel wird ein Zeichenfolgenparameter namens storageAccountName deklariert, dessen Länge nur zwischen 5 und 24 Zeichen betragen darf:

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

Dieser Parameter enthält zwei Decorators. Sie können mehrere Decorators auf einen Parameter anwenden, indem Sie jeden Decorator in eine eigene Zeile schreiben.

Hinweis

Sie können die Decorators @minLength und @maxLength auch auf Arrayparameter anwenden, um zu steuern, wie viele Elemente im Array zulässig sind.

Wenn Sie mit numerischen Parametern arbeiten, benötigen Sie möglicherweise Werte aus einem bestimmten Bereich. Beispielsweise kann Ihr Spielzeugunternehmen entscheiden, dass jedes Mal, wenn jemand einen App Service-Plan bereitgestellt, immer mindestens eine Instanz, aber nicht mehr als 10 Instanzen des Plans bereitgestellt werden sollen. Um die Anforderungen zu erfüllen, können Sie die Decorators @minValue und @maxValue verwenden, um die zulässigen minimalen und maximalen Werte anzugeben. Im folgenden Beispiel wird der ganzzahlige Parameter appServicePlanInstanceCount deklariert, dessen Wert nur zwischen 1 und 10 (einschließlich) liegen kann:

@minValue(1)
@maxValue(10)
param appServicePlanInstanceCount int

Hinzufügen von Beschreibungen zu Parametern

Parameter sind eine hervorragende Möglichkeit, um ihre Vorlagen für andere Benutzer wiederverwendbar zu machen. Wenn sie Ihre Vorlagen verwenden, müssen sie verstehen, was die einzelnen Parameter tun, damit sie die richtigen Werte bereitstellen können. Bicep stellt den Decorator @description zur Verfügung, damit Sie den Zweck Ihrer Parameter auf lesbare Weise dokumentieren können.

@description('The locations into which this Cosmos DB account should be configured. This parameter needs to be a list of objects, each of which has a locationName property.')
param cosmosDBAccountLocations array

Es ist eine bewährte Methode, Beschreibungen für Ihre Parameter bereitzustellen. Versuchen Sie, die Beschreibungen hilfreich zu gestalten, und geben Sie alle wichtigen Informationen darüber an, welche Anforderungen der Vorlage die Parameterwerte erfüllen müssen.

Hinweis

Bicep-Vorlagen können Benutzern zur Bereitstellung manchmal im Azure-Portal bereitgestellt werden, z. B. bei Verwendung von Vorlagenspezifikationen. Das Portal verwendet die Beschreibungen und andere Decorators von Parametern, um Benutzern zu erklären, was ein Parameterwert sein muss.