Inzicht in de structuur en syntaxis van Bicep-bestanden

Artikel
10/17/2024

In dit artikel worden de structuur en syntaxis van een Bicep-bestand beschreven. Het bevat de verschillende secties van het bestand en de eigenschappen die beschikbaar zijn in deze 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 de wijze waarop de implementatie wordt verwerkt.

Een Bicep-bestand heeft de volgende elementen.

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>
  }
}

output <output-name> <output-data-type> = <output-value>

In het volgende voorbeeld ziet u een implementatie van deze elementen.

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
  }
}

Metagegevens

Metagegevens in Bicep zijn een niet-getypte waarde die kan worden opgenomen in Bicep-bestanden. Hiermee kunt u aanvullende informatie verstrekken over uw Bicep-bestanden, inclusief details zoals de naam, beschrijving, auteur, aanmaakdatum en meer.

Doelbereik

Standaard is het doelbereik ingesteld op resourceGroup. Als u implementeert op het niveau van de resourcegroep, hoeft u het doelbereik niet in te stellen in uw Bicep-bestand.

De toegestane waarden zijn:

resourceGroup : standaardwaarde die wordt gebruikt voor implementaties van resourcegroepen.
abonnement - gebruikt voor abonnementsimplementaties.
managementGroup : gebruikt voor implementaties van beheergroepen.
tenant - gebruikt voor tenantimplementaties.

In een module kunt u een bereik opgeven dat verschilt van het bereik voor de rest van het Bicep-bestand. Zie Modulebereik configureren voor meer informatie

Decorators

U kunt een of meer decorators toevoegen voor elk van de volgende elementen:

Param
Var
resource
module
uitvoer
func
type

Decorateur	Toepassen op element	Toepassen op gegevenstype	Argument	Beschrijving
toegestaan	Param	Alles	matrix	Gebruik deze decorator om ervoor te zorgen dat de gebruiker de juiste waarden levert. Deze decorator is alleen toegestaan voor `param` instructies. Als u wilt declareren dat een eigenschap een van een set vooraf gedefinieerde waarden in een `type` of `output` instructie moet zijn, gebruikt u de syntaxis van het samenvoegtype. Syntaxis van samenvoegingstype kan ook worden gebruikt in `param` instructies.
batchSize	resource, module	N.v.t.	geheel getal	Stel exemplaren in om sequentieel te implementeren.
beschrijving	param, var, resource, module, uitvoer, type, func	Alles	tekenreeks	Geef beschrijvingen op voor de elementen. Markdown-opgemaakte tekst kan worden gebruikt voor de beschrijvingstekst.
Discriminator	param, type, uitvoer	object	tekenreeks	Gebruik deze decorator om ervoor te zorgen dat de juiste subklasse wordt geïdentificeerd en beheerd. Zie het gegevenstype Aangepaste samenvoeging voor meer informatie.
exporteren	var, type, func	Alles	Geen	Geeft aan dat het element kan worden geïmporteerd door een ander Bicep-bestand.
maxLength	param, uitvoer	matrix, tekenreeks	int	De maximale lengte voor tekenreeks- en matrixelementen. De waarde is inclusief.
maxValue	param, uitvoer	int	int	De maximumwaarde voor de gehele getallen. Deze waarde is inclusief.
metagegevens	param, uitvoer	Alles	object	Aangepaste eigenschappen die moeten worden toegepast op de elementen. Kan een beschrijvingseigenschap bevatten die gelijk is aan de beschrijvingsdecorator.
minLength	param, uitvoer	matrix, tekenreeks	int	De minimale lengte voor tekenreeks- en matrixelementen. De waarde is inclusief.
minValue	param, uitvoer	int	int	De minimumwaarde voor de gehele getallen. Deze waarde is inclusief.
Verzegeld	param, type, uitvoer	object	Geen	Verhoog BCP089 van een waarschuwing naar een fout wanneer een eigenschapsnaam van een gegevenstype use-define waarschijnlijk een type typfout is. Zie Foutniveau verhogen voor meer informatie.
veilig	Param	tekenreeks, object	Geen	Markeert de parameter als veilig. De waarde voor een beveiligde parameter wordt niet opgeslagen in de implementatiegeschiedenis en wordt niet geregistreerd. Zie Beveiligde tekenreeksen en objecten 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 geen waarde wordt opgegeven tijdens de implementatie.

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 testen of productie.

param storageSKU string = 'Standard_LRS'

De parameter is beschikbaar voor gebruik in uw Bicep-bestand.

sku: {
  name: storageSKU
}

U kunt voor elke parameter een of meer decorators toevoegen. Zie Decorators gebruiken voor meer informatie.

Zie Parameters in Bicep voor meer informatie.

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

U kunt voor elke variabele een of meer decorators toevoegen. Zie Decorators gebruiken voor meer informatie.

Zie Variabelen in Bicep voor meer informatie.

Typen

U kunt de instructie gebruiken om door de type gebruiker gedefinieerde gegevenstypen te definiëren.

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'
}

U kunt een of meer decorators toevoegen voor elk door de gebruiker gedefinieerd gegevenstype. Zie Decorators gebruiken voor meer informatie.

Zie Door de gebruiker gedefinieerde gegevenstypen voor meer informatie.

Functies

In uw Bicep-bestand kunt u uw eigen functies maken naast het gebruik van de standaard Bicep-functies die automatisch beschikbaar zijn in uw Bicep-bestanden. Maak uw eigen functies wanneer u gecompliceerde expressies hebt die herhaaldelijk worden gebruikt in uw Bicep-bestanden.

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

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

Zie Door de gebruiker gedefinieerde functies 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@2023-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

U kunt voor elke resource een of meer decorators toevoegen. Zie Decorators gebruiken voor meer informatie.

Zie Resourcedeclaratie in Bicep voor meer informatie.

Sommige resources hebben een bovenliggende/onderliggende relatie. U kunt een onderliggende resource definiëren binnen de bovenliggende resource of buiten de 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@2023-04-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@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
}

Zie Naam en type instellen voor onderliggende resources in Bicep voor meer informatie.

Modules

Met modules kunt u code uit een Bicep-bestand opnieuw gebruiken in andere Bicep-bestanden. In de moduledeclaratie koppelt u een koppeling naar het bestand dat u opnieuw wilt 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 naar de module verwijzen vanaf een andere locatie in het bestand. U kunt bijvoorbeeld een uitvoerwaarde uit een module ophalen met behulp van de symbolische naam en de naam van de uitvoerwaarde.

U kunt voor elke module een of meer decorators toevoegen. Zie Decorators gebruiken voor meer informatie.

Zie Bicep-modules gebruiken voor meer informatie.

Uitvoerwaarden

Gebruik uitvoer om waarden van de implementatie te retourneren. Normaal gesproken retourneert u een waarde van een geïmplementeerde resource wanneer u die waarde opnieuw moet gebruiken voor een andere bewerking.

output storageEndpoint object = stg.properties.primaryEndpoints

U kunt voor elke uitvoer een of meer decorators toevoegen. Zie Decorators gebruiken voor meer informatie.

Zie Outputs in Bicep voor meer informatie.

Lussen

U kunt iteratieve lussen toevoegen aan uw Bicep-bestand om meerdere exemplaren van een:

resource
module
variabele
eigenschap
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 getalindex 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 het resultaat bepaalt of de resource of module is geïmplementeerd. Gebruik de if expressie om een voorwaardelijke implementatie te definiëren.

param deployZone bool

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

Zie Voorwaardelijke implementatie in Bicep voor meer informatie.

Whitespace

Spaties en tabbladen worden genegeerd bij het ontwerpen van Bicep-bestanden.

Bicep is nieuwlijngevoelig. Voorbeeld:

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

Kan niet worden geschreven als:

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

Objecten en matrices 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@2023-11-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 starten en te beëindigen.

Tekens in de tekenreeks met meerdere regels worden als zodanig verwerkt. Escape-tekens zijn overbodig. U kunt deze 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 opnemen. In beide gevallen bevat de resulterende tekenreeks geen nieuwe regel. Afhankelijk van de einden van de lijn 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"
}

Declaraties met meerdere regels

U kunt nu meerdere regels gebruiken in functie-, matrix- en objectdeclaraties. Voor deze functie is Bicep CLI versie 0.7.X of hoger vereist.

In het volgende voorbeeld wordt de resourceGroup() definitie onderverdeeld in meerdere regels.

var foo = resourceGroup(
  mySubscription,
  myRgName)

Zie matrices en objecten voor voorbeelden van declaraties met meerdere regels.

Bekende beperkingen

Geen ondersteuning voor het concept apiProfile, dat wordt gebruikt om één apiProfile toe te wijzen aan een set apiVersion voor elk resourcetype.
Door de gebruiker gedefinieerde functies worden momenteel niet ondersteund. Een experimentele functie is momenteel echter toegankelijk. Zie Door de gebruiker gedefinieerde functies in Bicep voor meer informatie.
Sommige Bicep-functies vereisen een overeenkomstige wijziging in de tussenliggende taal (Azure Resource Manager JSON-sjablonen). We kondigen deze functies aan als beschikbaar wanneer alle vereiste updates zijn geïmplementeerd in global Azure. Als u een andere omgeving gebruikt, zoals Azure Stack, kan er een vertraging optreden in de beschikbaarheid van de functie. De Bicep-functie 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.

Share via