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@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:
- 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@2023-04-01' = {
name: storageAccountConfig.name
location: location
sku: {
name: storageAccountConfig.sku
}
kind: 'StorageV2'
}
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.
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@2023-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@2023-04-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@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.
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, for
die 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@2023-04-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@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 \n
interpretiert.
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.
Feedback
https://aka.ms/ContentUserFeedback.
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unterFeedback senden und anzeigen für