Principy struktury a syntaxe souborů Bicep

  • Článek
  • 6 min ke čtení

Tento článek popisuje strukturu a syntaxi souboru Bicep. Představuje různé části souboru a vlastnosti, které jsou v těchto částech k dispozici.

Podrobný kurz, který vás provede procesem vytvoření souboru Bicep, najdete v tématu Rychlý start: Vytváření souborů Biceppomocí 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ů nemá pořadí prvků vliv na způsob zpracování nasazení.

Soubor Bicep má 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 nastavovat 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

Parametry použijte pro hodnoty, které se musí pro různá nasazení lišit. Pro parametr můžete definovat výchozí hodnotu, která se použije, pokud během nasazování není zadána žádná hodnota.

Můžete například přidat parametr SKU a zadat pro prostředek různé velikosti. Můžete předat různé hodnoty v závislosti na tom, jestli nasazujete do testovacího nebo produkčního prostředí.

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 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ů, najdete v tématu Dekorátory.

Proměnné

Soubor Bicep můžete zefektovat 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řena zřetězováním několika hodnot.

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.

Prostředky

Pomocí resource klíčového 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 zahrnte vlastnosti, které jsou 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řazenosti a podřízené položky. 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ředekem (souborovou službou), který je definovaný v rámci účtu úložiště. Souborová služba má také podřízený prostředek (sdílená složku), který je v ní 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'
    }
  }
}

Další příklad ukazuje, jak definovat podřízený prostředek mimo nadřazený prostředek. K identifikaci vztahu nadřazený/podřízený použijete nadřazenou vlastnost . 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 Bicep.

Moduly

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

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

Symbolický název umožňuje odkazovat na modul od jiného místa v souboru . Můžete například získat výstupní hodnotu 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 použít pouze na definici prostředku nebo modulu, která používá for výraz.

Ve výchozím nastavení se prostředky nasadí paralelně. Když přidáte batchSize dekoratér, nasadíte instance sériově.

@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ých prostředků, 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 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í for výrazu definujte smyčku.

param moduleCount int = 2

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

Můžete iterovat přes pole, objekt nebo celočíselný index.

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

Podmíněné nasazení

Do souboru Bicep, který je podmíněně nasazený, můžete přidat prostředek nebo modul. Během nasazování se podmínka vyhodnotí a výsledek určí, jestli je prostředek nebo modul nasazen. Pomocí if výrazu 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.

Prázdné znaky

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

Bicep je citlivý na nový řádku. Napří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 na 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 řádky komentáře.

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

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

/*
  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ů. Ke spuštění a ukončení víceřádkového řetězce použijte tři jednoduché ''' znaky uvozovek.

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

Řetězec můžete buď spustit hned za otevřením, ''' nebo zahrnout 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ězce.

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

Známá omezení

  • Nepodporuje koncept apiProfile, který se používá k namapování jednoho apiProfile na set 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 (Azure Resource Manager json). Tyto funkce oznamujeme jako dostupné po nasazení všech požadovaných aktualizací 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á jenom v případě, že se v tomto prostředí aktualizoval i zprostředkující jazyk.

Další kroky

Úvod do Bicep najdete v tématu Co je Bicep?. Informace o datových typech Bicep najdete v tématu Datové typy.