Inzicht in de structuur en syntaxis van Bicep-bestanden

  • Artikel
  • 7 minuten om te lezen

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-bestandenmaken met Visual Studio Code voor een stapsgewijze zelfstudie die u door het proces van het maken van een Bicep-bestand leidt.

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 manier waarop de implementatie wordt verwerkt.

Een Bicep-bestand heeft de volgende elementen.

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.

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

output storageEndpoint object = stg.properties.primaryEndpoints

Doelbereik

Het doelbereik is standaard 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:

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

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

Parameterparameters

U kunt een of meer aaneenvoegers toevoegen voor elke parameter. Deze verantwoordelijken beschrijven de parameter en definiëren beperkingen voor de waarden die worden doorgegeven. In het volgende voorbeeld ziet u éénator, maar er zijn er nog veel meer beschikbaar.

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

Zie Voor meer informatie, inclusief beschrijvingen van alle beschikbare inseroren, SeeOrs.

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 wordt 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 body 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 de bovenliggende resource of daarbuiten.

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 in de service 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 Set name and type for child resources in Bicep (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 aan 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 vanuit een andere map in het bestand naar de module verwijzen. U kunt bijvoorbeeld een uitvoerwaarde van een module krijgen met behulp van de symbolische naam en de naam van de uitvoerwaarde.

Zie Bicep-modules gebruiken voor meer informatie.

Resource- en moduledelers

U kunt eenator toevoegen aan een resource- of moduledefinitie. De enige ondersteundeator is batchSize(int) . U kunt deze alleen toepassen op een resource- of moduledefinitie die gebruikmaakt van een for expressie.

Standaard worden resources parallel geïmplementeerd. Wanneer u batchSize deator 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 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

Zie Outputs in Bicep (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 index met gehele getallen itereren.

Zie Iteratieve lussen in Bicep voor meer informatie.

Voorwaardelijke implementatie

U kunt een resource of module toevoegen aan uw Bicep-bestand dat voorwaardelijk wordt geïmplementeerd. Tijdens de implementatie wordt de voorwaarde geëvalueerd en het resultaat bepaalt 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 en matrices in meerdere regels definiëren.

Opmerkingen

Gebruiken // voor opmerkingen van één regel of voor opmerkingen van meerdere /* ... */ lijnen

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 lijnen.

/*
  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 lijnen

U kunt een tekenreeks in meerdere regels ops breken. Gebruik drie enkele aangavetekens om de tekenreeks met meerdere lijnen te ''' starten en te beëindigen.

Tekens binnen de tekenreeks met meerdere lijnen worden in de staat verwerkt. Escapetekens zijn niet nodig. U kunt niet opnemen ''' in de tekenreeks met meerdere lijnen. 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 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 lijnen.

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

Bekende beperkingen

  • Er is geen ondersteuning voor het concept apiProfile, dat wordt gebruikt om één apiProfile toe te kennen aan een set apiVersion voor elk resourcetype.
  • Er is geen ondersteuning voor door de gebruiker gedefinieerde functies.
  • 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 azure wereldwijd. Als u een andere omgeving gebruikt, zoals Azure Stack, kan er vertraging zijn 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.