Inzicht in de structuur en syntaxis van Bicep-bestanden

In dit artikel wordt de structuur van een Bicep-bestand beschreven. Het bevat de verschillende secties van het bestand en de eigenschappen die beschikbaar zijn in deze secties.

Dit artikel is bedoeld voor gebruikers die enige kennis hebben van Bicep-bestanden. Het bevat gedetailleerde informatie over de structuur van het Bicep-bestand. 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

Een Bicep-bestand heeft de volgende elementen. 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.

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

// conditional deployment
resource <resource-symbolic-name> '<resource-type>@<api-version>' = if (<condition-to-deploy>) {
  <resource-properties>
}

// iterative deployment
@<decorator>(<argument>)
resource <resource-symbolic-name> '<resource-type>@<api-version>' = [for <item> in <collection>: {
  <resource-properties>
}]

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

// conditional deployment
module <module-symbolic-name> '<path-to-file>' = if (<condition-to-deploy>) {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

// iterative deployment
module <module-symbolic-name> '<path-to-file>' = [for <item> in <collection>: {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}]

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

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

// iterative output
output <output-name> array = [for <item> in <collection>: {
  <output-properties>
}]

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 Bicep-functies gebruiken om de standaardwaarde te maken, zoals het verkrijgen van de locatie van de resourcegroep.

param storageSKU string = 'Standard_LRS'
param location string = resourceGroup().location

Zie Gegevenstypen in Bicep voor de beschikbare gegevenstypen.

Een parameter mag niet dezelfde naam hebben als een variabele, module of resource.

Zie Parameters in Bicep voor meer informatie.

Parameterparameters

U kunt voor elke parameter een of meer verantwoordelijken toevoegen. Deze verantwoordelijken definiëren de waarden die zijn toegestaan voor de parameter. In het volgende voorbeeld worden de SKU's opgegeven die kunnen worden geïmplementeerd via het Bicep-bestand.

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

In de volgende tabel worden de beschikbare houders beschreven en wordt beschreven hoe u deze kunt gebruiken.

Decorator Van toepassing op Argument Beschrijving
Toegestaan all matrix Toegestane waarden voor de parameter . Gebruik deze gebruiksdesator om ervoor te zorgen dat de gebruiker de juiste waarden levert.
beschrijving all tekenreeks Tekst waarin wordt uitgelegd hoe u de parameter gebruikt. De beschrijving wordt weergegeven voor gebruikers via de portal.
Maxlength matrix, tekenreeks int De maximale lengte voor tekenreeks- en matrixparameters. De waarde is inclusief.
maxValue int int De maximumwaarde voor de parameter integer. Deze waarde is inclusief.
metagegevens all object Aangepaste eigenschappen die moeten worden toegepast op de parameter . Kan een beschrijvings-eigenschap bevatten die gelijk is aan de beschrijvingsmaker.
minLength matrix, tekenreeks int De minimale lengte voor tekenreeks- en matrixparameters. De waarde is inclusief.
minValue int int De minimumwaarde voor de parameter integer. Deze waarde is inclusief.
Veilige 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.

Variabelen

Gebruik variabelen voor complexe expressies die worden herhaald in een Bicep-bestand. U kunt bijvoorbeeld een variabele toevoegen voor een resourcenaam die wordt samengesteld door verschillende waarden samen te voegen.

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

U geeft geen gegevenstype op voor een variabele. In plaats daarvan wordt het gegevenstype afgeleid van de waarde.

Een variabele kan niet dezelfde naam hebben als een parameter, module of resource.

Zie Variabelen in Bicep voor meer informatie.

Resource

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 als u een waarde uit de resource wilt krijgen. De symbolische naam kan a-z, A-Z, 0-9 en '_' bevatten. De naam kan niet beginnen met een getal.

De resourcedeclaratie bevat ook het resourcetype en de API-versie.

resource stg 'Microsoft.Storage/storageAccounts@2019-06-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

In de resourcedeclaratie gebruikt u eigenschappen voor het resourcetype. Deze eigenschappen zijn uniek voor elk resourcetype.

Zie Resourcedeclaratie in Bicep voor meer informatie.

Als u een resource voorwaardelijk wilt implementeren,voegt u een expressie if toe.

resource sa 'Microsoft.Storage/storageAccounts@2019-06-01' = if (newOrExisting == 'new') {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

Als u meer dan één exemplaar van een resourcetype wilt implementeren, voegt u een expressie for toe. De expressie kan worden overgenomen door leden van een matrix.

resource sa 'Microsoft.Storage/storageAccounts@2019-06-01' = [for storageName in storageAccounts: {
  name: storageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}]

Een resource kan niet dezelfde naam hebben als een parameter, variabele of module.

Modules

Gebruik modules om een koppeling te maken naar andere Bicep-bestanden die code bevatten die u opnieuw wilt gebruiken. De module bevat een of meer resources die moeten worden geïmplementeerd. Deze resources worden samen met andere resources in uw Bicep-bestand 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 van een module krijgen met behulp van de symbolische naam en de naam van de uitvoerwaarde. De symbolische naam kan a-z, A-Z, 0-9 en '_' bevatten. De naam mag niet beginnen met een getal.

Een module kan niet dezelfde naam hebben als een parameter, variabele of resource.

Net als bij resources kunt u een module voorwaardelijk of iteratief implementeren. De syntaxis is hetzelfde voor modules als resources.

Zie Bicep-modules gebruiken voor meer informatie.

Resource- en moduleverdelers

U kunt eenator toevoegen aan een resource- of moduledefinitie. De enige ondersteunde magator 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. U weet niet in welke volgorde ze zijn gefinisht. Wanneer u batchSize deator toevoegt, implementeert u exemplaren serieel. Gebruik het argument integer om het aantal exemplaren op te geven dat parallel moet worden geïmplementeerd.

@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 de waarde 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

Geef een gegevenstype op voor de uitvoerwaarde.

Een uitvoer kan dezelfde naam hebben als een parameter, variabele, module of resource.

Zie Outputs in Bicep (Uitvoer in Bicep) voor meer informatie.

Witruimte

Spaties en tabbladen worden genegeerd bij het ontwerpen van Bicep-bestanden. Nieuwe regels hebben echter een semantische betekenis, bijvoorbeeld in object- en matrixdeclaraties.

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 regel die eindigt op 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"
}

Volgende stappen

Zie Wat is Bicep? voor een inleiding tot Bicep. Zie Gegevenstypen voor Bicep-gegevenstypen.