Inzicht in de structuur en syntaxis van Bicep-bestanden
In dit artikel worden de structuur en syntaxis van een Bicep-bestand beschreven. Het toont de verschillende secties van het bestand en de eigenschappen die beschikbaar zijn in die secties.
Zie Quickstart: Bicep-bestanden maken met Visual Studio Code voor een stapsgewijze zelfstudie die u begeleidt bij het maken van een Bicep-bestand.
Bicep-indeling
Bicep is een declaratieve taal, wat betekent dat de elementen in elke volgorde kunnen worden weergegeven. In tegenstelling tot imperatieve talen heeft de volgorde van elementen geen invloed op hoe de implementatie wordt verwerkt.
Een Bicep-bestand heeft de volgende elementen.
metadata <metadata-name> = ANY
targetScope = '<scope>'
@<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>
In het volgende voorbeeld ziet u een implementatie van deze elementen.
metadata description = {
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
}
}
Metagegevens
Metagegevens in Bicep is een niet-getypte waarde die kan worden opgenomen in Bicep-bestanden. Hiermee kunt u aanvullende informatie over uw Bicep-bestanden verstrekken, inclusief details zoals de naam, beschrijving, auteur, aanmaakdatum en meer.
Doelbereik
Het doelbereik is standaard ingesteld op resourceGroup
. Als u implementeert op het niveau van de resourcegroep, hoeft u het doelbereik niet in uw Bicep-bestand in te stellen.
De toegestane waarden zijn:
- resourceGroup : standaardwaarde, gebruikt voor resourcegroepimplementaties.
- subscription : wordt gebruikt voor abonnementsimplementaties.
- managementGroup : wordt gebruikt voor implementaties van beheergroepen.
- tenant : gebruikt voor tenantimplementaties.
In een module kunt u een ander bereik opgeven dan het bereik voor de rest van het Bicep-bestand. Zie Modulebereik configureren voor meer informatie
Parameters
Gebruik parameters voor waarden die moeten variëren voor verschillende implementaties. U kunt een standaardwaarde definiëren voor de parameter die wordt gebruikt als er tijdens de implementatie geen waarde wordt opgegeven.
U kunt bijvoorbeeld een SKU-parameter toevoegen om verschillende grootten voor een resource op te geven. U kunt verschillende waarden doorgeven, afhankelijk van of u implementeert voor test of productie.
param storageSKU string = 'Standard_LRS'
De parameter is beschikbaar voor gebruik in uw Bicep-bestand.
sku: {
name: storageSKU
}
Zie Parameters in Bicep voor meer informatie.
Parameterdecorators
U kunt een of meer decorators toevoegen voor elke parameter. Deze decorators beschrijven de parameter en definiëren beperkingen voor de waarden die worden doorgegeven. In het volgende voorbeeld ziet u één decorator, maar er zijn nog vele andere beschikbaar.
@allowed([
'Standard_LRS'
'Standard_GRS'
'Standard_ZRS'
'Premium_LRS'
])
param storageSKU string = 'Standard_LRS'
Zie Decorators voor meer informatie, inclusief beschrijvingen van alle beschikbare decorators.
Variabelen
U kunt uw Bicep-bestand beter leesbaar maken door complexe expressies in een variabele in te kapselen. U kunt bijvoorbeeld een variabele toevoegen voor een resourcenaam die is samengesteld door verschillende waarden samen te voegen.
var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'
Pas deze variabele toe waar u de complexe expressie nodig hebt.
resource stg 'Microsoft.Storage/storageAccounts@2019-04-01' = {
name: uniqueStorageName
Zie Variabelen in Bicep voor meer informatie.
Resources
Gebruik het resource
trefwoord om een resource te definiëren die moet worden geïmplementeerd. Uw resourcedeclaratie bevat een symbolische naam voor de resource. U gebruikt deze symbolische naam in andere delen van het Bicep-bestand om een waarde op te halen uit de resource.
De resourcedeclaratie bevat het resourcetype en de API-versie. Neem in de hoofdtekst van de resourcedeclaratie eigenschappen op die specifiek zijn voor het resourcetype.
resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' = {
name: uniqueStorageName
location: location
sku: {
name: storageSKU
}
kind: 'StorageV2'
properties: {
supportsHttpsTrafficOnly: true
}
}
Zie Resourcedeclaratie in Bicep voor meer informatie.
Sommige resources hebben een bovenliggende/onderliggende relatie. U kunt een onderliggende resource definiëren binnen of buiten de bovenliggende resource.
In het volgende voorbeeld ziet u hoe u een onderliggende resource binnen een bovenliggende resource definieert. Het bevat een opslagaccount met een onderliggende resource (bestandsservice) die is gedefinieerd in het opslagaccount. De bestandsservice heeft ook een onderliggende resource (share) die erin is gedefinieerd.
resource storage 'Microsoft.Storage/storageAccounts@2021-02-01' = {
name: 'examplestorage'
location: resourceGroup().location
kind: 'StorageV2'
sku: {
name: 'Standard_LRS'
}
resource service 'fileServices' = {
name: 'default'
resource share 'shares' = {
name: 'exampleshare'
}
}
}
In het volgende voorbeeld ziet u hoe u een onderliggende resource buiten de bovenliggende resource definieert. U gebruikt de bovenliggende eigenschap om een bovenliggende/onderliggende relatie te identificeren. Dezelfde drie resources worden gedefinieerd.
resource storage 'Microsoft.Storage/storageAccounts@2021-02-01' = {
name: 'examplestorage'
location: resourceGroup().location
kind: 'StorageV2'
sku: {
name: 'Standard_LRS'
}
}
resource service 'Microsoft.Storage/storageAccounts/fileServices@2021-02-01' = {
name: 'default'
parent: storage
}
resource share 'Microsoft.Storage/storageAccounts/fileServices/shares@2021-02-01' = {
name: 'exampleshare'
parent: service
}
Zie Naam en type instellen voor onderliggende resources in Bicep voor meer informatie.
Modules
Met modules kunt u code uit een Bicep-bestand hergebruiken in andere Bicep-bestanden. In de moduledeclaratie koppelt u het bestand om opnieuw te gebruiken. Wanneer u het Bicep-bestand implementeert, worden de resources in de module ook geïmplementeerd.
module webModule './webApp.bicep' = {
name: 'webDeploy'
params: {
skuName: 'S1'
location: location
}
}
Met de symbolische naam kunt u ergens anders in het bestand naar de module verwijzen. U kunt bijvoorbeeld een uitvoerwaarde ophalen uit een module met behulp van de symbolische naam en de naam van de uitvoerwaarde.
Zie Bicep-modules gebruiken voor meer informatie.
Resource- en moduledecorators
U kunt een decorator toevoegen aan een resource- of moduledefinitie. De enige ondersteunde decorator is batchSize(int)
. U kunt deze alleen toepassen op een resource- of moduledefinitie die gebruikmaakt van een for
expressie.
Resources worden standaard parallel geïmplementeerd. Wanneer u de batchSize
decorator toevoegt, implementeert u exemplaren serieel.
@batchSize(3)
resource storageAccountResources 'Microsoft.Storage/storageAccounts@2019-06-01' = [for storageName in storageAccounts: {
...
}]
Zie Implementeren in batches voor meer informatie.
Uitvoerwaarden
Gebruik uitvoer om waarden uit de implementatie te retourneren. Normaal gesproken retourneert u een waarde van een geïmplementeerde resource wanneer u die waarde opnieuw wilt gebruiken voor een andere bewerking.
output storageEndpoint object = stg.properties.primaryEndpoints
Zie Uitvoer in Bicep voor meer informatie.
Lussen
U kunt iteratieve lussen toevoegen aan uw Bicep-bestand om meerdere kopieën van een te definiëren:
- resource
- module
- Variabele
- property
- output
Gebruik de for
expressie om een lus te definiëren.
param moduleCount int = 2
module stgModule './example.bicep' = [for i in range(0, moduleCount): {
name: '${i}deployModule'
params: {
}
}]
U kunt een matrix-, object- of gehele index herhalen.
Zie Iteratieve lussen in Bicep voor meer informatie.
Voorwaardelijke implementatie
U kunt een resource of module toevoegen aan uw Bicep-bestand dat voorwaardelijk is geïmplementeerd. Tijdens de implementatie wordt de voorwaarde geëvalueerd en bepaalt het resultaat of de resource of module wordt geïmplementeerd. Gebruik de if
expressie om een voorwaardelijke implementatie te definiëren.
param deployZone bool
resource dnsZone 'Microsoft.Network/dnszones@2018-05-01' = if (deployZone) {
name: 'myZone'
location: 'global'
}
Zie Voorwaardelijke implementatie in Bicep voor meer informatie.
Witruimte
Spaties en tabbladen worden genegeerd bij het ontwerpen van Bicep-bestanden.
Bicep is nieuwlijngevoelig. Bijvoorbeeld:
resource sa 'Microsoft.Storage/storageAccounts@2019-06-01' = if (newOrExisting == 'new') {
...
}
Kan niet worden geschreven als:
resource sa 'Microsoft.Storage/storageAccounts@2019-06-01' =
if (newOrExisting == 'new') {
...
}
Objecten enmatrices in meerdere regels definiëren.
Opmerkingen
Gebruiken //
voor opmerkingen met één regel of /* ... */
voor opmerkingen met meerdere regels
In het volgende voorbeeld ziet u een opmerking met één regel.
// This is your primary NIC.
resource nic1 'Microsoft.Network/networkInterfaces@2020-06-01' = {
...
}
In het volgende voorbeeld ziet u een opmerking met meerdere regels.
/*
This Bicep file assumes the key vault already exists and
is in same subscription and resource group as the deployment.
*/
param existingKeyVaultName string
Tekenreeksen met meerdere regels
U kunt een tekenreeks opsplitsen in meerdere regels. Gebruik drie enkele aanhalingstekens '''
om de tekenreeks met meerdere regels te beginnen en te beëindigen.
Tekens in de tekenreeks met meerdere regels worden ongewijzigd verwerkt. Escape-tekens zijn niet nodig. U kunt niet opnemen '''
in de tekenreeks met meerdere regels. Tekenreeksinterpolatie wordt momenteel niet ondersteund.
U kunt de tekenreeks direct na het openen '''
starten of een nieuwe regel toevoegen. In beide gevallen bevat de resulterende tekenreeks geen nieuwe regel. Afhankelijk van de regeleinden in uw Bicep-bestand, worden nieuwe regels geïnterpreteerd als \r\n
of \n
.
In het volgende voorbeeld ziet u een tekenreeks met meerdere regels.
var stringVar = '''
this is multi-line
string with formatting
preserved.
'''
Het voorgaande voorbeeld is gelijk aan de volgende JSON.
"variables": {
"stringVar": "this is multi-line\r\n string with formatting\r\n preserved.\r\n"
}
Meerregelige declaraties
U kunt nu meerdere regels gebruiken in functie-, matrix- en objectdeclaraties. Voor deze functie is Bicep versie 0.7.4 of hoger vereist.
In het volgende voorbeeld is de resourceGroup()
definitie onderverdeeld in meerdere regels.
var foo = resourceGroup(
mySubscription,
myRgName)
Zie Matrices en objecten voor voorbeelden van declaratie met meerdere regels.
Bekende beperkingen
- Er is geen ondersteuning voor het concept apiProfile, dat wordt gebruikt om één apiProfile toe te wijzen aan een set apiVersion voor elk resourcetype.
- Geen ondersteuning voor door de gebruiker gedefinieerde functies.
- Voor sommige Bicep-functies is een overeenkomstige wijziging in de tussenliggende taal vereist (Azure Resource Manager JSON-sjablonen). We kondigen deze functies aan als beschikbaar wanneer alle vereiste updates zijn geïmplementeerd in globale Azure. Als u een andere omgeving gebruikt, zoals Azure Stack, kan er een vertraging optreden in de beschikbaarheid van de functie. De functie Bicep is alleen beschikbaar wanneer de tussenliggende taal ook in die omgeving is bijgewerkt.
Volgende stappen
Zie Wat is Bicep? voor een inleiding tot Bicep. Zie Gegevenstypen voor Bicep-gegevenstypen.