Förstå strukturen och syntaxen för Bicep-filer

Artikel
11/19/2021
6 minuter för att läsa

I den här artikeln beskrivs strukturen och syntaxen för en Bicep-fil. Den visar de olika avsnitten i filen och de egenskaper som är tillgängliga i dessa avsnitt.

En stegvis självstudiekurs som vägleder dig genom processen för att skapa en Bicep-fil finns i Snabbstart: Skapa Bicep-filer med Visual Studio Kod.

Bicep-format

Bicep är ett deklarativt språk, vilket innebär att elementen kan visas i valfri ordning. Till skillnad från imperativt språk påverkar elementens ordningsföljd inte hur distributionen bearbetas.

En Bicep-fil har följande element.

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>

I följande exempel visas en implementering av dessa element.

@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

Målomfång

Som standard är målomfånget inställt på resourceGroup . Om du distribuerar på resursgruppsnivå behöver du inte ange målomfånget i bicep-filen.

Tillåtna värden är:

resourceGroup – standardvärde som används för resursgruppsdistributioner.
subscription – används för prenumerationsdistributioner.
managementGroup – används för distribution av hanteringsgrupper.
tenant – används för klientdistributioner.

I en modul kan du ange ett annat omfång än omfånget för resten av Bicep-filen. Mer information finns i Konfigurera modulomfång

Parametrar

Använd parametrar för värden som måste variera för olika distributioner. Du kan definiera ett standardvärde för parametern som används om inget värde anges under distributionen.

Du kan till exempel lägga till en SKU-parameter för att ange olika storlekar för en resurs. Du kan skicka olika värden beroende på om du distribuerar till test eller produktion.

param storageSKU string = 'Standard_LRS'

Parametern är tillgänglig för användning i din Bicep-fil.

sku: {
  name: storageSKU
}

Mer information finns i Parametrar i Bicep.

Parameterdekoratorer

Du kan lägga till en eller flera decorators för varje parameter. Dessa decorators beskriver parametern och definierar begränsningar för de värden som skickas in. I följande exempel visas en decorator, men det finns många andra som är tillgängliga.

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

Mer information, inklusive beskrivningar av alla tillgängliga decorators, finns i Decorators.

Variabler

Du kan göra din Bicep-fil mer lättläst genom att kapsla in komplexa uttryck i en variabel. Du kan till exempel lägga till en variabel för ett resursnamn som skapas genom att sammanfoga flera värden.

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

Använd den här variabeln överallt där du behöver det komplexa uttrycket.

resource stg 'Microsoft.Storage/storageAccounts@2019-04-01' = {
  name: uniqueStorageName

Mer information finns i Variabler i Bicep.

Resurser

Använd resource nyckelordet för att definiera en resurs som ska distribueras. Resursdeklarationen innehåller ett symboliskt namn för resursen. Du använder det här symboliska namnet i andra delar av Bicep-filen för att hämta ett värde från resursen.

Resursdeklarationen innehåller resurstypen och API-versionen. Inkludera egenskaper som är specifika för resurstypen i resursdeklarationens brödtext.

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

Mer information finns i Resursdeklaration i Bicep.

Vissa resurser har en överordnad/underordnad relation. Du kan definiera en underordnad resurs antingen i den överordnade resursen eller utanför den.

I följande exempel visas hur du definierar en underordnad resurs i en överordnad resurs. Den innehåller ett lagringskonto med en underordnad resurs (filtjänst) som definieras i lagringskontot. Filtjänsten har också en underordnad resurs (resurs) som definieras i den.

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

I nästa exempel visas hur du definierar en underordnad resurs utanför den överordnade resursen. Du använder den överordnade egenskapen för att identifiera en överordnad/underordnad relation. Samma tre resurser definieras.

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
}

Mer information finns i Ange namn och typ för underordnade resurser i Bicep.

Moduler

Med moduler kan du återanvända kod från en Bicep-fil i andra Bicep-filer. I moduldeklarationen länkar du till filen för återanvändning. När du distribuerar Bicep-filen distribueras även resurserna i modulen.

module webModule './webApp.bicep' = {
  name: 'webDeploy'
  params: {
    skuName: 'S1'
    location: location
  }
}

Med det symboliska namnet kan du referera till modulen från någon annan plats i filen. Du kan till exempel hämta ett utdatavärde från en modul med hjälp av det symboliska namnet och namnet på utdatavärdet.

Mer information finns i Använda Bicep-moduler.

Resurs- och moduldekoratorer

Du kan lägga till en decorator till en resurs- eller moduldefinition. Den enda decorator som stöds är batchSize(int) . Du kan bara tillämpa den på en resurs- eller moduldefinition som använder ett for uttryck.

Som standard distribueras resurser parallellt. När du lägger batchSize till encorator distribuerar du instanserna seriellt.

@batchSize(3)
resource storageAccountResources 'Microsoft.Storage/storageAccounts@2019-06-01' = [for storageName in storageAccounts: {
  ...
}]

Mer information finns i Distribuera i batchar.

Utdata

Använd utdata för att returnera värden från distributionen. Normalt returnerar du ett värde från en distribuerad resurs när du behöver återanvända det värdet för en annan åtgärd.

output storageEndpoint object = stg.properties.primaryEndpoints

Mer information finns i Utdata i Bicep.

Loopar

Du kan lägga till iterativa loopar i bicep-filen för att definiera flera kopior av en:

resource
Modul
Variabel
egenskap
utdata

Använd uttrycket for för att definiera en loop.

param moduleCount int = 2

module stgModule './example.bicep' = [for i in range(0, moduleCount): {
  name: '${i}deployModule'
  params: {
  }
}]

Du kan iterera över en matris, ett objekt eller ett heltalsindex.

Mer information finns i Iterativa loopar i Bicep.

Villkorlig distribution

Du kan lägga till en resurs eller modul i din Bicep-fil som är villkorligt distribuerad. Under distributionen utvärderas villkoret och resultatet avgör om resursen eller modulen distribueras. Använd uttrycket if för att definiera en villkorsstyrd distribution.

param deployZone bool

resource dnsZone 'Microsoft.Network/dnszones@2018-05-01' = if (deployZone) {
  name: 'myZone'
  location: 'global'
}

Mer information finns i Villkorlig distribution i Bicep.

Blanksteg

Blanksteg och tabbar ignoreras när bicep-filer redigeras.

Bicep är nyradskänsligt. Exempel:

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

Det går inte att skriva som:

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

Definiera objekt och matriser på flera rader.

Kommentarer

Använd // för enkelradskommentarer /* ... */ eller för flerradskommentarer

I följande exempel visas en kommentar med en rad.

// This is your primary NIC.
resource nic1 'Microsoft.Network/networkInterfaces@2020-06-01' = {
   ...
}

I följande exempel visas en flerradskommentar.

/*
  This Bicep file assumes the key vault already exists and
  is in same subscription and resource group as the deployment.
*/
param existingKeyVaultName string

Flerradssträngar

Du kan dela upp en sträng i flera rader. Använd tre enkla citattecken ''' för att starta och avsluta flerradssträngen.

Tecken i flerradssträngen hanteras som de är. Escape-tecken är onödiga. Du kan inte inkludera ''' i flerradssträngen. Stränginterpolering stöds inte för närvarande.

Du kan antingen starta strängen direkt efter öppningen ''' eller inkludera en ny rad. I båda fallen innehåller inte den resulterande strängen någon ny rad. Beroende på radsluten i bicep-filen tolkas nya rader som \r\n eller \n .

I följande exempel visas en flerradssträng.

var stringVar = '''
this is multi-line
  string with formatting
  preserved.
'''

Föregående exempel motsvarar följande JSON.

"variables": {
  "stringVar": "this is multi-line\r\n  string with formatting\r\n  preserved.\r\n"
}

Kända begränsningar

Inget stöd för begreppet apiProfile, som används för att mappa en enskild apiProfile till en uppsättning apiVersion för varje resurstyp.
Inget stöd för användardefinierade funktioner.
Vissa Bicep-funktioner kräver en motsvarande ändring av det mellanliggande språket (Azure Resource Manager JSON-mallar). Vi meddelar att dessa funktioner är tillgängliga när alla nödvändiga uppdateringar har distribuerats till globala Azure. Om du använder en annan miljö, till exempel Azure Stack, kan det uppstå en fördröjning i tillgängligheten för funktionen. Bicep-funktionen är endast tillgänglig när det mellanliggande språket också har uppdaterats i den miljön.

Nästa steg

En introduktion till Bicep finns i Vad är Bicep?. Information om Bicep-datatyper finns i Datatyper.