Vysvětlení struktury a syntaxe souborů Bicep

  • Článek

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.

metadata <metadata-name> = ANY

targetScope = '<scope>'

type <user-defined-data-type-name> = <type-expression>

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>

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>

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

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@2022-09-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

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

Funkce (Preview)

Poznámka:

Pokud chcete funkci Preview povolit, přečtěte si téma Povolení experimentálních funkcí.

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.

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
}

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

Dekorátory parametrů

Pro každý parametr můžete přidat jeden nebo více dekorátorů. Tyto dekorátory popisují parametr a definují omezení pro hodnoty, které jsou předány. Následující příklad ukazuje jeden dekorátor, ale mnoho dalších je k dispozici.

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

Další informace, včetně popisů všech dostupných dekorátorů, naleznete v tématu Dekorátory.

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@2019-04-01' = {
  name: uniqueStorageName

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

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@2019-06-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

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@2022-09-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@2022-09-01' = {
  name: 'examplestorage'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

resource service 'Microsoft.Storage/storageAccounts/fileServices@2022-09-01' = {
  name: 'default'
  parent: storage
}

resource share 'Microsoft.Storage/storageAccounts/fileServices/shares@2022-09-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.

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

Dekorátory prostředků a modulů

Do definice prostředku nebo modulu můžete přidat dekorátor. Podporované dekorátory jsou batchSize(int) a description. Můžete ho použít pouze na definici prostředku nebo modulu, která používá for výraz.

Ve výchozím nastavení se prostředky nasazují paralelně. Když přidáte batchSize(int) dekorátor, nasadíte instance serialně.

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

Další informace najdete v tématu Nasazení v dávkách.

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

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
  • module
  • 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@2018-05-01' = 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@2019-06-01' = if (newOrExisting == 'new') {
  ...
}

Nejde napsat takto:

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

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

Poznámky

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@2020-06-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.