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

Artikel
2024-11-06

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 att skapa en Bicep-fil finns i Snabbstart: Skapa Bicep-filer med Visual Studio Code.

Bicep-format

Bicep är ett deklarativt språk, vilket innebär att elementen kan visas i valfri ordning. Till skillnad från imperativa språk påverkar inte ordningen på element hur distributionen bearbetas.

En Bicep-fil har följande element.

Bicep

@<decorator>(<argument>)
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>
  }
}

@<decorator>(<argument>)
output <output-name> <output-data-type> = <output-value>

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

Bicep

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

Metadata

Metadata i Bicep är ett icke-typat värde som kan ingå i Bicep-filer. Det gör att du kan ange ytterligare information om dina Bicep-filer, inklusive information som dess namn, beskrivning, författare, skapandedatum med mera.

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.

De tillåtna värdena är:

resourceGroup – standardvärde som används för resursgruppsdistributioner.
prenumeration – används för prenumerationsdistributioner.
managementGroup – används för distributioner av hanteringsgrupper.
klientorganisation – används för klientdistributioner.

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

Dekoratörer

Du kan lägga till en eller flera dekoratörer för vart och ett av följande element:

Param
var
resource
modul
utdata
func
typ

Dekoratörerna inkluderar:

Dekoratör	Tillämpa på element	Tillämpa på datatyp	Argument	beskrivning
tillåten	Param	alla	matris	Använd den här dekoratören för att se till att användaren tillhandahåller rätt värden. Den här dekoratören är endast tillåten för `param` instruktioner. Om du vill deklarera att en egenskap måste vara en av en uppsättning fördefinierade värden i en eller `output` -`type`instruktionen använder du syntax för unionstyp. Union-typsyntax kan också användas i `param` -instruktioner.
batchSize	modul, resurs	Ej tillämpligt	integer	Konfigurera instanser för att distribuera sekventiellt.
description	func, param, module, output, resource, type, var	alla	sträng	Ange beskrivningar för elementen. Markdown-formaterad text kan användas för beskrivningstexten.
diskriminerande	param, type, output	objekt	sträng	Använd den här dekoratören för att säkerställa att rätt underklass identifieras och hanteras. Mer information finns i Anpassad taggad union-datatyp.
exportera	func, type, var	alla	inget	Anger att elementet kan importeras av en annan Bicep-fil.
maxLength	param, output, type	matris, sträng	heltal	Maximal längd för sträng- och matriselement. Värdet är inkluderande.
maxValue	param, output, type	heltal	heltal	Det maximala värdet för heltalselementen. Det här värdet är inkluderande.
metadata	func, output, param, type	alla	objekt	Anpassade egenskaper som ska tillämpas på elementen. Kan innehålla en beskrivningsegenskap som motsvarar beskrivningsdekoratören.
minLength	param, output, type	matris, sträng	heltal	Minsta längd för sträng- och matriselement. Värdet är inkluderande.
minValue	param, output, type	heltal	heltal	Minsta värde för heltalselementen. Det här värdet är inkluderande.
stängd	param, type, output	objekt	inget	Höj BCP089 från en varning till ett fel när ett egenskapsnamn för en användningsdefinierad datatyp sannolikt är ett skrivfel. Mer information finns i Höja felnivån.
säker	param, typ	sträng, objekt	inget	Markerar parametern som säker. Värdet för en säker parameter sparas inte i distributionshistoriken och loggas inte. Mer information finns i Skydda strängar och objekt.

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 in olika värden beroende på om du distribuerar för att testa eller producera.

Bicep

param storageSKU string = 'Standard_LRS'

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

Bicep

sku: {
  name: storageSKU
}

Du kan lägga till en eller flera dekoratörer för varje parameter. Mer information finns i Använda dekoratörer.

Mer information finns i Parametrar i Bicep.

Variabler

Du kan göra Bicep-filen mer läsbar 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.

Bicep

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

Använd den här variabeln var du än behöver det komplexa uttrycket.

Bicep

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

Du kan lägga till en eller flera dekoratörer för varje variabel. Mer information finns i Använda dekoratörer.

Mer information finns i Variabler i Bicep.

Typer

Du kan använda -instruktionen type för att definiera användardefinierade datatyper.

Bicep

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

Du kan lägga till en eller flera dekoratörer för varje användardefinierad datatyp. Mer information finns i Använda dekoratörer.

Mer information finns i Användardefinierade datatyper.

Funktioner

I Bicep-filen kan du skapa dina egna funktioner utöver att använda standardfunktionerna för Bicep som är automatiskt tillgängliga i Bicep-filerna. Skapa dina egna funktioner när du har komplicerade uttryck som används upprepade gånger i Bicep-filerna.

Bicep

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

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

Mer information finns i Användardefinierade funktioner.

Resurser

Använd nyckelordet resource 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. I resursdeklarationens brödtext inkluderar du egenskaper som är specifika för resurstypen.

Bicep

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

Du kan lägga till en eller flera dekoratörer för varje resurs. Mer information finns i Använda dekoratörer.

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.

Bicep

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

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.

Bicep

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
}

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.

Bicep

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

Med det symboliska namnet kan du referera till modulen från någon annanstans 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.

Du kan lägga till en eller flera dekoratörer för varje modul. Mer information finns i Använda dekoratörer.

Mer information finns i Använda Bicep-moduler.

Utdata

Använd utdata för att returnera värden från distributionen. Vanligtvis 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.

Bicep

output storageEndpoint object = stg.properties.primaryEndpoints

Du kan lägga till en eller flera dekoratörer för varje utdata. Mer information finns i Använda dekoratörer.

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.

Bicep

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.

Bicep

param deployZone bool

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

Mer information finns i Villkorsstyrd distribution i Bicep.

Tomt utrymme

Blanksteg och flikar ignoreras vid redigering av Bicep-filer.

Bicep är nyradskänslig. Till exempel:

Bicep

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

Det går inte att skriva som:

Bicep

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

Definiera objekt och matriser på flera rader.

Kommentarer

Används // för enradskommentarer eller /* ... */ för flerradskommentarer

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

Bicep

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

I följande exempel visas en kommentar med flera rader.

Bicep

/*
  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 strängen med flera rader.

Tecken i flerradssträngen hanteras som de är. Escape-tecken är onödiga. Du kan inte ta med ''' 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 den resulterande strängen inte en ny rad. Beroende på radsluten i Bicep-filen tolkas nya rader som \r\n eller \n.

I följande exempel visas en sträng med flera rader.

Bicep

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

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

JSON

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

Deklarationer med flera rader

Nu kan du använda flera rader i funktions-, matris- och objektdeklarationer. Den här funktionen kräver Bicep CLI version 0.7.X eller senare.

I följande exempel resourceGroup() är definitionen uppdelad i flera rader.

Bicep

var foo = resourceGroup(
  mySubscription,
  myRgName)

Se Matriser och objekt för deklarationsexempel med flera rader.

Kända begränsningar

Inget stöd för begreppet apiProfile, som används för att mappa en enda apiProfile till en uppsättning apiVersion för varje resurstyp.
Användardefinierade funktioner stöds inte just nu. En experimentell funktion är dock tillgänglig för närvarande. Mer information finns i Användardefinierade funktioner i Bicep.
Vissa Bicep-funktioner kräver en motsvarande ändring av mellanliggande språk (Azure Resource Manager JSON-mallar). Vi meddelar dessa funktioner som 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.

Dela via

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

Bicep-format

Metadata

Målomfång

Dekoratörer

Parametrar

Variabler

Typer

Funktioner

Resurser

Moduler

Utdata

Loopar

Villkorlig distribution

Tomt utrymme

Kommentarer

Flerradssträngar

Deklarationer med flera rader

Kända begränsningar

Nästa steg

Feedback

Ytterligare resurser