Vysvětlení struktury a syntaxe souborů Bicep

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 mohou být zobrazeny 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.

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>

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

@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

Cílový obor

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

Povolené hodnoty jsou následující:

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

Parametry

Pro hodnoty, které se musí lišit pro různá nasazení, použijte parametry. 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 najdete v tématu Parametry v nástroji 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 existuje mnoho dalších, které jsou 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 naleznete 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 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ředku v Bicep.

Některé prostředky mají vztah nadřazeného nebo podřízeného objektu. 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@2021-02-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. Nadřazenou vlastnost použijete k identifikaci vztahu nadřazeného/podřízeného objektu. Jsou definovány stejné tři prostředky.

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
}

Další informace najdete v tématu Nastavení názvu a typu podřízených prostředků v Nástroji Bicep.

Moduly

Moduly umožňují opakovaně používat kód ze souboru Bicep v jiných souborech Bicep. V deklaraci modulu vytvoříte odkaz na 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 například získat 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. Jediným podporovaným dekorátorem je batchSize(int). Můžete ho for použít jenom na definici prostředku nebo modulu, která používá výraz.

Ve výchozím nastavení se prostředky nasazují paralelně. Když přidáte batchSize 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

K vrácení hodnot z nasazení použijte výstupy. Obvykle vrátíte hodnotu z nasazeného prostředku, když ji potřebujete znovu použít pro jinou operaci.

output storageEndpoint object = stg.properties.primaryEndpoints

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

Smyčky

Do souboru Bicep můžete přidat iterativní smyčky, které definují více kopií:

  • prostředek
  • module
  • proměnná
  • property
  • 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 nad polem, objektem nebo celočíselnou indexem.

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 můžete definovat 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 nástroji Bicep.

Prázdné znaky

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') {
  ...
}

Nelze napsat jako:

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

Definujte objekty a pole ve více řá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@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 více řá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 spustit hned za otevřením ''' nebo přidat nový řádek. V obou případech výsledný řetězec neobsahuje nový řádek. V závislosti na konci řádku 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 s více řádky

V deklaracích funkcí, polí a objektů teď můžete použít více řádků. Tato funkce vyžaduje Bicep verze 0.7.4 nebo novější.

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

var foo = resourceGroup(
  mySubscription,
  myRgName)

Viz Pole a objekty pro ukázky deklarace více řádků.

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.
  • Nepodporuje uživatelem definované funkce.
  • Některé funkce Bicep vyžadují odpovídající změnu zprostředkujícího jazyka (šablony AZURE Resource Manager JSON). 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 k dispozici pouze v případech, kdy byl v daném prostředí aktualizován 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.