Teilen über

Verstehen der Struktur und Syntax von ARM-Vorlagen

  • Artikel

In diesem Artikel wird die Struktur und Syntax einer Bicep-Datei beschrieben. Er zeigt die verschiedenen Abschnitte der Datei und die Eigenschaften, die in diesen Abschnitten verfügbar sind.

Ein schrittweises Tutorial über den Erstellungsprozess einer Bicep-Datei finden Sie unter Schnellstart: Erstellen von Bicep-Dateien mit Visual Studio Code.

Bicep-Format

Bicep ist eine deklarative Sprache, was bedeutet, dass die Elemente in beliebiger Reihenfolge enthalten sein können. Im Gegensatz zu imperativen Sprachen wirkt sich die Reihenfolge der Elemente nicht darauf aus, wie die Bereitstellung verarbeitet wird.

Eine Bicep Datei verfügt über die folgenden Elemente.

@<decorator>(<argument>)
metadata <metadata-name> = ANY

targetScope = '<scope>'

@<decorator>(<argument>)
type <user-defined-data-type-name> = <type-expression>

@<decorator>(<argument>)
func <user-defined-function-name> (<argument-name> <data-type>, <argument-name> <data-type>, ...) <function-data-type> => <expression>

@<decorator>(<argument>)
param <parameter-name> <parameter-data-type> = <default-value>

@<decorator>(<argument>)
var <variable-name> = <variable-value>

@<decorator>(<argument>)
resource <resource-symbolic-name> '<resource-type>@<api-version>' = {
  <resource-properties>
}

@<decorator>(<argument>)
module <module-symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

@<decorator>(<argument>)
output <output-name> <output-data-type> = <output-value>

Das folgende Beispiel zeigt eine Implementierung dieser Elemente.

metadata description = 'Creates a storage account and a web app'

@description('The prefix to use for the storage account name.')
@minLength(3)
@maxLength(11)
param storagePrefix string

param storageSKU string = 'Standard_LRS'
param location string = resourceGroup().location

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

module webModule './webApp.bicep' = {
  name: 'webDeploy'
  params: {
    skuName: 'S1'
    location: location
  }
}

Metadaten

Metadaten sind in Bicep ein nicht typisierter Wert, der in Bicep-Dateien enthalten sein kann. Sie können damit zusätzliche Informationen über Ihre Bicep-Dateien bereitstellen, einschließlich Details wie Name, Beschreibung, Autor, Erstellungsdatum und mehr.

Zielbereich

Standardmäßig ist der Zielbereich auf festgelegt resourceGroup. Wenn Sie auf der Ebene der Ressourcengruppe bereitstellen, müssen Sie den Zielbereich in Ihrer Bicep-Datei nicht festlegen.

Zulässige Werte sind:

In einem Modul können Sie einen Bereich definieren, der sich vom Bereich für den Rest der Bicep-Datei unterscheiden kann. Weitere Informationen finden Sie unter Online-Backup konfigurieren.

Decorator-Elemente

Sie können für jedes der folgenden Elemente eine oder mehrere Decorator-Elemente hinzufügen:

Zu den Decorators gehören:

Decorator Auf Element anwenden Auf Datentyp anwenden Argument Beschreibung
Zulässig param 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.
batchSize module, resource N/V integer Richten Sie Instanzen so ein, dass sie sequenziell bereitgestellt werden.
Beschreibung func, param, module, output, resource, type, var all Zeichenfolge Geben Sie Beschreibungen für die Elemente an. Markdown-formatierter Text kann für den Beschreibungstext verwendet werden.
discriminator param, type, output 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.
Export func, type, var all none Gibt an, dass das Element von einer anderen Bicep-Datei importiert werden kann.
maxLength param, output, type Array, Zeichenfolge int Die maximale Länge für Zeichenfolgen- und Arrayelemente. Der Stop-Wert ist inklusiv.
maxValue param, output, type int int Der maximale Wert für die ganzzahligen Elemente. Der Stop-Wert ist inklusiv.
metadata func, output, param, type all Objekt Benutzerdefinierte Eigenschaften, die auf die Elemente angewendet werden sollen. Kann eine Beschreibungseigenschaft enthalten, die dem Description-Decorator entspricht.
minLength param, output, type Array, Zeichenfolge int Die minimale Länge für Zeichenfolgen- und Arrayelemente. Der Stop-Wert ist inklusiv.
minValue param, output, type int int Der minimale Wert für die ganzzahligen Elemente. Der Stop-Wert ist inklusiv.
sealed param, type, output 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 param, type 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.

Parameter

Verwenden Sie Parameter für Werte, die für verschiedene Bereitstellungen variieren müssen. Sie können einen Standardwert für den Parameter definieren, der verwendet wird, wenn während der Bereitstellung kein Wert angegeben wird.

Beispielsweise können Sie einen SKU-Parameter hinzufügen, um unterschiedliche Größen für eine Ressource anzugeben. Sie können unterschiedliche Werte übergeben, je nachdem, ob Sie die Bereitstellung in einer Test- oder Produktionsumgebungen durchführen.

param storageSKU string = 'Standard_LRS'

Der Parameter kann in Ihrer Bicep-Datei verwendet werden.

sku: {
  name: storageSKU
}

Sie können für jeden Parameter ein oder mehrere Decorator-Zeichen hinzufügen. Weitere Informationen finden Sie unter Verwenden von Decorator-Elementen.

Weitere Informationen finden Sie unter Parameter in Bicep.

Variablen

Sie können die Lesbarkeit Ihrer Bicep-Datei verbessern, indem Sie komplexe Ausdrücke in einer Variable kapseln. Beispielsweise können Sie eine Variable für einen Ressourcennamen hinzufügen, der durch Verkettung mehrerer Werte erstellt wird.

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

Wenden Sie diese Variable überall an, wo Sie den komplexen Ausdruck benötigen.

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: uniqueStorageName

Sie können für jede Variable ein oder mehrere Decorator-Elemente hinzufügen. Weitere Informationen finden Sie unter Verwenden von Decorator-Elementen.

Weitere Informationen finden Sie unter Variablen in Bicep.

Typen

Sie können die Anweisung „type“ verwenden, um benutzerdefinierte Datentypen zu definieren.

param location string = resourceGroup().location

type storageAccountSkuType = 'Standard_LRS' | 'Standard_GRS'

type storageAccountConfigType = {
  name: string
  sku: storageAccountSkuType
}

param storageAccountConfig storageAccountConfigType = {
  name: 'storage${uniqueString(resourceGroup().id)}'
  sku: 'Standard_LRS'
}

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

Sie können für jeden benutzerdefinierten Datentyp ein oder mehrere Decorator-Elemente hinzufügen. Weitere Informationen finden Sie unter Verwenden von Decorator-Elementen.

Weitere Informationen finden Sie unter Benutzerdefinierte Datentypen.

Functions

In Ihrer Bicep-Datei können Sie ihre eigenen Funktionen erstellen und zusätzlich die standardmäßigen Bicep-Funktionen verwenden, die automatisch in Ihren Bicep-Dateien verfügbar sind. Erstellen Sie eigene Funktionen, wenn Sie über komplizierte Ausdrücke verfügen, die in Ihrer Bicep-Dateien wiederholt verwendet werden.

func buildUrl(https bool, hostname string, path string) string => '${https ? 'https' : 'http'}://${hostname}${empty(path) ? '' : '/${path}'}'

output azureUrl string = buildUrl(true, 'microsoft.com', 'azure')

Weitere Informationen finden Sie unter Benutzerdefinierte Funktionen.

Ressourcen

Verwenden resource Sie das Schlüsselwort, um eine bereitzustellende Ressource zu definieren. Die Ressourcendeklaration enthält einen symbolischen Namen für die Ressource. Sie verwenden diesen symbolischen Namen in anderen Teilen der Bicep-Datei, um einen Wert aus der Ressource abzurufen.

Die Ressourcendeklaration enthält den Ressourcentyp und die API-Version. Schließen Sie im Text der Ressourcendeklaration Eigenschaften ein, die für den Ressourcentyp spezifisch sind.

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

Sie können für jede Ressource ein oder mehrere Decorator-Elemente hinzufügen. Weitere Informationen finden Sie unter Verwenden von Decorator-Elementen.

Weitere Informationen finden Sie unter Ressourcendeklaration in Bicep.

Einige Ressourcen stehen in einer hierarchischen Beziehung zueinander. Sie können eine untergeordnete Ressource entweder innerhalb oder außerhalb der übergeordneten Ressource definieren.

Das folgende Beispiel zeigt, wie Sie eine untergeordnete Ressource in einer übergeordneten Ressource definieren. Sie enthält ein Speicherkonto mit einer untergeordneten Ressource (Dateidienst), der innerhalb des Speicherkontos definiert ist. Der Dateidienst verfügt ebenfalls über eine untergeordnete Ressource (Freigabe), die im Dienst definiert ist.

resource storage 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: 'examplestorage'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }

  resource service 'fileServices' = {
    name: 'default'

    resource share 'shares' = {
      name: 'exampleshare'
    }
  }
}

Das nächste Beispiel zeigt, wie eine untergeordnete Ressource außerhalb der übergeordneten Ressource definiert wird. Sie verwenden die übergeordnete Eigenschaft, um eine hierarchische Beziehung zu ermitteln. Es werden dieselben drei Ressourcen definiert.

resource storage 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: 'examplestorage'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

resource service 'Microsoft.Storage/storageAccounts/fileServices@2023-04-01' = {
  name: 'default'
  parent: storage
}

resource share 'Microsoft.Storage/storageAccounts/fileServices/shares@2023-04-01' = {
  name: 'exampleshare'
  parent: service
}

Weitere Informationen finden Sie unter Festlegen von Name und Typ für untergeordnete Ressourcen in Bicep.

Module

Mit Modulen können Sie Code aus einer Bicep-Datei in anderen Bicep-Dateien wiederverwenden. Sie geben in der Moduldeklaration einen Link zu der Datei an, die Sie wiederverwenden möchten. Wenn Sie die Bicep-Datei bereitstellen, werden auch die Ressourcen im Modul bereitgestellt.

module webModule './webApp.bicep' = {
  name: 'webDeploy'
  params: {
    skuName: 'S1'
    location: location
  }
}

Mit dem symbolischen Namen können Sie von einer anderen Stelle in der Datei auf das Modul verweisen. Beispielsweise können Sie einen Ausgabewert aus einem Modul mit dem symbolischen Namen und dem Namen des Ausgabewerts erhalten.

Sie können für jedes Modul ein oder mehrere Decorator-Elemente hinzufügen. Weitere Informationen finden Sie unter Verwenden von Decorator-Elementen.

Weitere Informationen finden Sie unter Was ist Bicep (Vorschau)?.

Ausgaben

Verwenden Sie Ausgänge, um Werte aus der Bereitstellung zurückzugeben. In der Regel geben Sie einen Wert aus einer bereitgestellten Ressource zurück, wenn Sie diesen Wert für einen anderen Vorgang wieder verwenden müssen.

output storageEndpoint object = stg.properties.primaryEndpoints

Sie können für jede Ausgabe ein oder mehrere Decorator-Elemente hinzufügen. Weitere Informationen finden Sie unter Verwenden von Decorator-Elementen.

Weitere Informationen finden Sie unter Ausgaben in Bicep.

Schleifen

Sie können Ihrer Bicep-Datei iterative Schleifen hinzufügen, um mehrere Kopien von folgenden Elementen zu definieren:

  • resource
  • module
  • -Variable
  • property
  • output

Verwenden Sie den for-Ausdruck, um eine Schleife zu definieren.

param moduleCount int = 2

module stgModule './example.bicep' = [for i in range(0, moduleCount): {
  name: '${i}deployModule'
  params: {
  }
}]

Sie können ein Array, ein Objekt oder einen ganzzahligen Index durchlaufen.

Weitere Informationen finden Sie unter Iterative Schleifen in Bicep.

Bedingte Bereitstellung

Sie können Ihrer Bicep-Datei eine Ressource oder ein Modul hinzufügen, die bzw. das bedingt bereitgestellt wird. Während der Bereitstellung wird die Bedingung ausgewertet. Das Ergebnis bestimmt dann, ob die Ressource oder das Modul bereitgestellt wird. Verwenden Sie den if-Ausdruck, um eine bedingte Bereitstellung zu definieren.

param deployZone bool

resource dnsZone 'Microsoft.Network/dnsZones@2023-07-01-preview' = if (deployZone) {
  name: 'myZone'
  location: 'global'
}

Für weitere Informationen siehe Bedingter Einsatz in Bicep.

Leerraum

Leerzeichen und Tabstoppzeichen werden beim Erstellen von Bicep-Dateien ignoriert.

Bicep reagiert empfindlich auf Zeilenvorschübe. Zum Beispiel:

resource sa 'Microsoft.Storage/storageAccounts@2023-04-01' = if (newOrExisting == 'new') {
  ...
}

Kann nicht wie folgt geschrieben werden:

resource sa 'Microsoft.Storage/storageAccounts@2023-04-01' =
    if (newOrExisting == 'new') {
      ...
    }

Definieren Sie Objekte und Arrays auf mehreren Zeilen.

Kommentare

Wird // für einzeilige Kommentare oder /* ... */ für mehrzeilenbasierte Kommentare verwendet.

Das folgende Beispiel zeigt einen einzeiligen Kommentar.

// This is your primary NIC.
resource nic1 'Microsoft.Network/networkInterfaces@2023-11-01' = {
  ...
}

Das folgende Beispiel zeigt einen mehrzeiligen Kommentar.

/*
  This Bicep file assumes the key vault already exists and
  is in same subscription and resource group as the deployment.
*/
param existingKeyVaultName string

Mehrzeilige Zeichenfolgen

Sie können eine Zeichenfolge in mehrere Zeilen unterteilen. Verwenden Sie drei einfache Anführungszeichen ''', um die mehrzeilige Zeichenfolge zu starten und zu beenden.

Zeichen innerhalb der mehrzeiligen Zeichenfolge werden unverändert behandelt. Escapezeichen sind nicht erforderlich. Sie können nicht ''' in die mehrzeilige Zeichenfolge einschließen. Zeichen folgen Interpolationen werden zurzeit nicht unterstützt.

Sie können entweder die Zeichenfolge direkt nach dem Öffnen ''' oder eine neue Zeile einschließen. In beiden Fällen enthält die resultierende Zeichenfolge keine neue Zeile. Abhängig von den Zeilenenden in der BICEP-Datei werden neue Zeilen als \r\n oder \ninterpretiert.

Das folgende Beispiel zeigt eine mehrzeilige Zeichenkette.

var stringVar = '''
this is multi-line
  string with formatting
  preserved.
'''

Das vorangegangene Beispiel entspricht dem folgenden JSON.

"variables": {
  "stringVar": "this is multi-line\r\n  string with formatting\r\n  preserved.\r\n"
}

Mehrzeilige Deklarationen

Sie können jetzt mehrere Zeilen in Funktions-, Array- und Objektdeklarationen verwenden. Diese Funktion erfordert Bicep CLI Version 0.7.X oder höher.

Im folgenden Beispiel ist die resourceGroup()-Definition in mehrere Zeilen unterteilt.

var foo = resourceGroup(
  mySubscription,
  myRgName)

Beispiele für mehrzeilige Deklarationen finden Sie unter Arrays und unter Objekte.

Bekannte Einschränkungen

  • Keine Unterstützung für das „apiProfile“-Konzept, das für die Zuordnung eines einzelnen „apiProfile“ zu einer festgelegten „apiVersion“ für jeden Ressourcentyp verwendet wird.
  • Benutzerdefinierte Funktionen werden zurzeit nicht unterstützt. Ein experimentelles Feature ist derzeit jedoch verfügbar. Weitere Informationen finden Sie unter Benutzerdefinierte Funktionen in Bicep.
  • Einige Bicep-Features erfordern eine entsprechende Änderung an der Zwischensprache (JSON-Vorlagen von Azure Resource Manager). Wir kündigen die Verfügbarkeit dieser Features an, wenn alle erforderlichen Updates für die globale Azure-Plattform bereitgestellt wurden. Wenn Sie eine andere Umgebung wie Azure Stack verwenden, kann es zu einer Verzögerung bei der Verfügbarkeit des Features kommen. Das Bicep-Feature ist nur verfügbar, wenn die Zwischensprache in dieser Umgebung ebenfalls aktualisiert wurde.

Nächste Schritte

Eine Einführung in BICEP finden Sie unter Was ist BICEP?. Informationen zu Bicep-Datentypen finden Sie unter Datentypen.