Verstehen der Struktur und Syntax von ARM-Vorlagen

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.

metadata <metadata-name> = ANY

targetScope = '<scope>'

type <user-defined-data-type-name> = <type-expression>

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>

var <variable-name> = <variable-value>

resource <resource-symbolic-name> '<resource-type>@<api-version>' = {
  <resource-properties>
}

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

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@2022-09-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:

• ResourceGroup : Standardwert, der für Ressourcengruppen-Bereitstellungenverwendet wird.
• Abonnement : wird für Abonnement-Bereitstellungenverwendet.
• managementGroup - wird für Bereitstellungen der Verwaltungsgruppe verwendet.
• Tenant - Verwendet fürTenant-Bereitstellungen.

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.

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@2022-09-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

Weitere Informationen finden Sie unter Benutzerdefinierte Datentypen.

Funktionen (Vorschau)

Hinweis

Informationen zum Aktivieren des Vorschaufeatures finden Sie unter Aktivieren experimenteller Features.

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.

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
}

Weitere Informationen finden Sie unter Parameter in Bicep.

Parameter-Decorator

Sie können für jeden Parameter ein oder mehrere Decorator-Zeichen hinzufügen. Diese Decorator-Elemente beschreiben den Parameter und definieren Einschränkungen für die übergebenen Werte. Das folgende Beispiel zeigt einen Decorator, aber es gibt noch viele andere.

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageSKU string = 'Standard_LRS'

Weitere Informationen, einschließlich Beschreibungen aller verfügbaren Decorator-Elemente, finden Sie unter Decorators.

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@2019-04-01' = {
  name: uniqueStorageName

Weitere Informationen finden Sie unter Variablen in Bicep.

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@2019-06-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

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@2022-09-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@2022-09-01' = {
  name: 'examplestorage'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

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

resource share 'Microsoft.Storage/storageAccounts/fileServices/shares@2022-09-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.

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

Ressourcen-und Modul-Decorator

Sie können einer Ressourcen-oder Modul Definition ein Decorator-Modul hinzufügen. Die unterstützten Decorator-Elemente sind batchSize(int) und description. Sie können ihn nur auf eine Ressourcen- oder Moduldefinition anwenden, fordie einen Ausdruck verwendet.

Standardmäßig werden Ressourcen parallel bereitgestellt. Wenn Sie den batchSize(int)Decorator hinzufügen, stellen Sie Instanzen seriell bereit.

@batchSize(3)
resource storageAccountResources 'Microsoft.Storage/storageAccounts@2019-06-01' = [for storageName in storageAccounts: {
  ...
}]

Weitere Informationen finden Sie unter Bereitstellung in Batches.

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

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@2018-05-01' = 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@2019-06-01' = if (newOrExisting == 'new') {
  ...
}

Kann nicht wie folgt geschrieben werden:

resource sa 'Microsoft.Storage/storageAccounts@2019-06-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@2020-06-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 derzeit 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.