Vysvětlení struktury a syntaxe souborů Bicep

Článek
11/06/2024

Tento článek popisuje strukturu a syntaxi souboru Bicep. Zobrazí různé části souboru a vlastnosti, které jsou v těchto oddílech k dispozici.

Podrobný kurz, který vás provede procesem vytvoření souboru Bicep, najdete v tématu Rychlý start: Vytvoření souborů Bicep pomocí editoru Visual Studio Code.

Formát Bicep

Bicep je deklarativní jazyk, což znamená, že prvky se mohou objevit v libovolném pořadí. Na rozdíl od imperativních jazyků pořadí prvků nemá vliv na zpracování nasazení.

Soubor Bicep obsahuje následující prvky.

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

Následující příklad ukazuje implementaci těchto prvků.

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 v Bicep jsou netypová hodnota, kterou lze zahrnout do souborů Bicep. Umožňuje vám poskytnout dodatečné informace o souborech Bicep, včetně podrobností, jako je jeho název, popis, autor, datum vytvoření a další.

Cílový obor

Ve výchozím nastavení je cílový obor nastaven na resourceGrouphodnotu . Pokud nasazujete na úrovni skupiny prostředků, nemusíte v souboru Bicep nastavit cílový obor.

Povolené hodnoty jsou následující:

resourceGroup – výchozí hodnota použitá pro nasazení skupin prostředků.
předplatné – používá se pro nasazení předplatného.
managementGroup – používá se pro nasazení skupin pro správu.
tenant – používá se pro nasazení tenanta.

V modulu můžete zadat obor, který se liší od oboru pro zbytek souboru Bicep. Další informace najdete v tématu Konfigurace oboru modulu

Dekoratéry

Pro každý z následujících prvků můžete přidat jeden nebo více dekorátorů:

Param
var
resource
module
výstup
func
type

Dekorátory zahrnují:

Dekoratér	Použít u elementu	Použít u datového typu	Argument	Popis
povolený	Param	vše	pole	Pomocí tohoto dekorátoru se ujistěte, že uživatel poskytuje správné hodnoty. Tento dekorátor je povolen pouze u `param` příkazů. Chcete-li deklarovat, že vlastnost musí být jednou ze sady předdefinovaných hodnot v `type` příkazu nebo `output` příkazu, použijte syntaxi sjednocovacího typu. Syntaxi sjednocovacího typu lze použít také v `param` příkazech.
batchSize	modul, prostředek	–	integer	Nastavte instance pro postupné nasazení.
description	func, param, module, output, resource, type, var	vše	string	Zadejte popisy prvků. Text ve formátu Markdown lze použít pro text popisu.
diskriminátor	parametr, typ, výstup	objekt	string	Pomocí tohoto dekorátoru se ujistěte, že je identifikována a spravována správná podtřída. Další informace naleznete v tématu Vlastní značky sjednocovacího datového typu.
export	func, type, var	vše	Žádná	Označuje, že prvek lze importovat jiným souborem Bicep.
maxLength	parametr, výstup, typ	array, string	int	Maximální délka řetězcových a maticových prvků. Hodnota je inkluzivní.
maxValue	parametr, výstup, typ	int	int	Maximální hodnota celočíselného elementu. Tato hodnota je inkluzivní.
metadata	func, output, param, type	vše	objekt	Vlastní vlastnosti, které se mají použít u prvků. Může obsahovat vlastnost popisu, která je ekvivalentní popis dekorátoru.
minLength	parametr, výstup, typ	array, string	int	Minimální délka pro řetězcové a maticové prvky. Hodnota je inkluzivní.
minValue	parametr, výstup, typ	int	int	Minimální hodnota celočíselného elementu. Tato hodnota je inkluzivní.
sealed	parametr, typ, výstup	objekt	Žádná	Zvýšení úrovně BCP089 z upozornění na chybu, pokud název vlastnosti parametru use-define datový typ je pravděpodobně překlep. Další informace naleznete v tématu Zvýšení úrovně chyby.
Zabezpečený	parametr, typ	string, object	Žádná	Označí parametr jako zabezpečený. Hodnota zabezpečeného parametru se neuloží do historie nasazení a nezaprotokoluje se. Další informace naleznete v tématu Zabezpečení řetězců a objektů.

Parametry

Použijte parametry pro hodnoty, které se musí pro různá nasazení lišit. Můžete definovat výchozí hodnotu parametru, který se použije, pokud během nasazování není k dispozici žádná hodnota.

Můžete například přidat parametr skladové položky pro určení různých velikostí prostředku. V závislosti na tom, jestli nasazujete do testování nebo produkčního prostředí, můžete předat různé hodnoty.

param storageSKU string = 'Standard_LRS'

Parametr je k dispozici pro použití v souboru Bicep.

sku: {
  name: storageSKU
}

Pro každý parametr můžete přidat jeden nebo více dekorátorů. Další informace naleznete v tématu Použití dekorátorů.

Další informace naleznete v tématu Parametry v bicep.

Proměnné

Soubor Bicep můžete zviditelnit zapouzdřením složitých výrazů do proměnné. Můžete například přidat proměnnou pro název prostředku, který je vytvořen zřetězením několika hodnot dohromady.

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

Tuto proměnnou použijte všude, kde potřebujete komplexní výraz.

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

Pro každou proměnnou můžete přidat jeden nebo více dekorátorů. Další informace naleznete v tématu Použití dekorátorů.

Další informace najdete v tématu Proměnné v bicep.

Typy

Příkaz můžete použít type k definování uživatelem definovaných datových typů.

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

Pro každý uživatelem definovaný datový typ můžete přidat jeden nebo více dekorátorů. Další informace naleznete v tématu Použití dekorátorů.

Další informace naleznete v tématu Uživatelem definované datové typy.

Funkce

V souboru Bicep můžete kromě standardních funkcí Bicep, které jsou automaticky dostupné v souborech Bicep, vytvořit vlastní funkce. Vytvořte si vlastní funkce, pokud máte složité výrazy, které se opakovaně používají v souborech 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')

Další informace naleznete v tématu Uživatelem definované funkce.

Zdroje informací

Pomocí klíčového resource slova definujte prostředek, který se má nasadit. Deklarace prostředku obsahuje symbolický název prostředku. Tento symbolický název použijete v jiných částech souboru Bicep k získání hodnoty z prostředku.

Deklarace prostředku zahrnuje typ prostředku a verzi rozhraní API. V těle deklarace prostředku uveďte vlastnosti specifické pro daný typ prostředku.

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

Pro každý prostředek můžete přidat jeden nebo více dekorátorů. Další informace naleznete v tématu Použití dekorátorů.

Další informace najdete v tématu Deklarace prostředků v Bicep.

Některé prostředky mají vztah nadřazenosti nebo podřízenosti. Podřízený prostředek můžete definovat buď uvnitř nadřazeného prostředku, nebo mimo něj.

Následující příklad ukazuje, jak definovat podřízený prostředek v rámci nadřazeného prostředku. Obsahuje účet úložiště s podřízeným prostředkem (souborovou službou), který je definovaný v rámci účtu úložiště. Souborová služba má také podřízený prostředek (sdílenou složku), který je v něm definovaný.

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

Následující příklad ukazuje, jak definovat podřízený prostředek mimo nadřazený prostředek. K identifikaci vztahu nadřazeného/podřízeného objektu použijete nadřazenou vlastnost. Jsou definovány stejné tři prostředky.

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
}

Další informace naleznete v tématu Nastavení názvu a typu pro podřízené prostředky v Bicep.

Moduly

Moduly umožňují opakovaně používat kód ze souboru Bicep v jiných souborech Bicep. V deklaraci modulu propočítáte soubor, který chcete znovu použít. Když nasadíte soubor Bicep, nasadí se také prostředky v modulu.

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

Symbolický název umožňuje odkazovat na modul odjinud v souboru. Výstupní hodnotu můžete získat například z modulu pomocí symbolického názvu a názvu výstupní hodnoty.

Pro každý modul můžete přidat jeden nebo více dekorátorů. Další informace naleznete v tématu Použití dekorátorů.

Další informace najdete v tématu Použití modulů Bicep.

Výstupy

Pomocí výstupů můžete vracet hodnoty z nasazení. Obvykle vrátíte hodnotu z nasazeného prostředku, když potřebujete tuto hodnotu znovu použít pro jinou operaci.

output storageEndpoint object = stg.properties.primaryEndpoints

Pro každý výstup můžete přidat jeden nebo více dekorátorů. Další informace naleznete v tématu Použití dekorátorů.

Další informace najdete v tématu Výstupy v Bicep.

Smyčky

Do souboru Bicep můžete přidat iterativní smyčky pro definování více kopií:

resource
modul
proměnná
vlastnost
output

Pomocí výrazu for definujte smyčku.

param moduleCount int = 2

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

Můžete iterovat pole, objekt nebo celočíselné indexy.

Další informace naleznete v tématu Iterativní smyčky v Bicep.

Podmíněné nasazení

Prostředek nebo modul můžete přidat do souboru Bicep, který je podmíněně nasazený. Během nasazení se podmínka vyhodnotí a výsledek určuje, jestli je prostředek nebo modul nasazený. Pomocí výrazu if definujte podmíněné nasazení.

param deployZone bool

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

Další informace najdete v tématu Podmíněné nasazení v Bicep.

Whitespace

Při vytváření souborů Bicep se mezery a karty ignorují.

Bicep je citlivá na nový řádek. Příklad:

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

Nejde napsat takto:

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

Definujte objekty a pole v několika řádcích.

Komentáře

Používá se // pro jednořádkové komentáře nebo /* ... */ pro víceřádkové komentáře.

Následující příklad ukazuje jednořádkový komentář.

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

Následující příklad ukazuje víceřádkový komentář.

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

Víceřádkové řetězce

Řetězec můžete rozdělit na několik řádků. K zahájení a ukončení víceřádkového řetězce použijte tři jednoduché znaky ''' uvozovek.

Znaky v řetězci s více řádky se zpracovávají tak, jak jsou. Řídicí znaky nejsou nutné. Do víceřádkového řetězce nemůžete zahrnout ''' . Interpolace řetězců se v současné době nepodporuje.

Řetězec můžete začínat přímo za otevřením ''' nebo přidat nový řádek. V obou případech výsledný řetězec neobsahuje nový řádek. V závislosti na konců řádků v souboru Bicep se nové řádky interpretují jako \r\n nebo \n.

Následující příklad ukazuje víceřádkový řetězec.

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

Předchozí příklad je ekvivalentní následujícímu kódu JSON.

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

Deklarace víceřádkového řádku

V deklaracích funkcí, polí a objektů teď můžete použít více řádků. Tato funkce vyžaduje rozhraní příkazového řádku Bicep verze 0.7.X nebo vyšší.

V následujícím příkladu resourceGroup() je definice rozdělena na více řádků.

var foo = resourceGroup(
  mySubscription,
  myRgName)

Ukázky deklarace více řádků najdete v polích a objektech .

Známá omezení

Nepodporuje se koncept apiProfile, který se používá k mapování jednoho souboru apiProfile na sadu apiVersion pro každý typ prostředku.
Uživatelem definované funkce se v tuto chvíli nepodporují. Experimentální funkce je ale momentálně přístupná. Další informace naleznete v tématu Uživatelem definované funkce v Bicep.
Některé funkce Bicep vyžadují odpovídající změnu zprostředkujícího jazyka (šablony JSON Azure Resource Manageru). Tyto funkce oznamujeme jako dostupné, když jsou všechny požadované aktualizace nasazené do globálního Azure. Pokud používáte jiné prostředí, například Azure Stack, může dojít ke zpoždění dostupnosti funkce. Funkce Bicep je dostupná pouze v případech, kdy se v daném prostředí aktualizoval také zprostředkující jazyk.

Další kroky

Úvod do Bicep najdete v tématu Co je Bicep?. Datové typy Bicep najdete v tématu Datové typy.

Sdílet prostřednictvím