A Bicep-fájlok szerkezetének és szintaxisának megismerése

Cikk
11/03/2023

Ez a cikk egy Bicep-fájl szerkezetét és szintaxisát ismerteti. Bemutatja a fájl különböző szakaszait és az ezekben a szakaszokban elérhető tulajdonságokat.

A Bicep-fájlok létrehozásának folyamatán végigvezető részletes oktatóanyagért tekintse meg a Rövid útmutatót: Bicep-fájlok létrehozása a Visual Studio Code-tal.

Bicep formátum

A Bicep egy deklaratív nyelv, ami azt jelenti, hogy az elemek bármilyen sorrendben megjelenhetnek. Az imperatív nyelvektől eltérően az elemek sorrendje nem befolyásolja az üzembe helyezés feldolgozását.

A Bicep-fájlok a következő elemeket tartalmaznak.

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>

Az alábbi példa ezeknek az elemeknek a megvalósítását mutatja be.

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

Metaadatok

A Bicep metaadatai olyan nem beírt értékek, amelyek a Bicep-fájlokban is szerepelhetnek. Lehetővé teszi, hogy kiegészítő információkat adjon meg a Bicep-fájlokról, beleértve a nevét, leírását, szerzőjét, létrehozási dátumát stb.

Cél hatóköre

Alapértelmezés szerint a cél hatóköre a következőre resourceGroupvan állítva: . Ha az erőforráscsoport szintjén telepít, nem kell beállítania a célhatókört a Bicep-fájlban.

Az engedélyezett értékek a következők:

resourceGroup – az erőforráscsoport üzembe helyezéséhez használt alapértelmezett érték.
előfizetés – előfizetések üzembe helyezéséhez használatos.
managementGroup – felügyeleti csoportok üzembe helyezéséhez használatos.
bérlő – bérlőtelepítésekhez használatos.

Egy modulban megadhat egy olyan hatókört, amely eltér a Bicep-fájl többi részének hatókörétől. További információ: Modulhatókör konfigurálása

Típusok

Az type utasítás használatával definiálhat felhasználó által definiált adattípusokat.

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

További információ: Felhasználó által definiált adattípusok.

Függvények (előzetes verzió)

Megjegyzés:

Az előzetes verziójú funkció engedélyezéséhez lásd : Kísérleti funkciók engedélyezése.

A Bicep-fájlban a szokásos Bicep-függvények mellett saját függvényeket is létrehozhat, amelyek automatikusan elérhetők a Bicep-fájlokban. Saját függvényeket hozhat létre, ha bonyolult kifejezésekkel rendelkezik, amelyeket a Bicep-fájlokban ismétlődően használnak.

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

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

További információ: Felhasználó által definiált függvények.

Parameters

Olyan értékekhez használjon paramétereket, amelyeknek eltérőnek kell a különböző üzemelő példányok esetében. Megadhat egy alapértelmezett értéket a használt paraméterhez, ha az üzembe helyezés során nem ad meg értéket.

Hozzáadhat például egy termékváltozat-paramétert az erőforrás különböző méreteinek megadásához. Különböző értékeket adhat meg attól függően, hogy tesztelésre vagy éles üzembe helyezésre készül-e.

param storageSKU string = 'Standard_LRS'

A paraméter a Bicep-fájlban használható.

sku: {
  name: storageSKU
}

További információ: Paraméterek a Bicepben.

Paraméter-dekorátorok

Minden paraméterhez hozzáadhat egy vagy több dekoratőrt. Ezek a dekorátorok leírják a paramétert, és megszorításokat határoznak meg az átadott értékekhez. Az alábbi példa egy dekoratőrt mutat be, de sok más elérhető.

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

További információkért, beleértve az összes elérhető dekoratőr leírását, tekintse meg a Dekorátorok című témakört.

Változók

A Bicep-fájlt olvashatóbbá teheti, ha összetett kifejezéseket foglal bele egy változóba. Hozzáadhat például egy változót egy erőforrásnévhez, amely több érték összefűzésével jön létre.

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

Alkalmazza ezt a változót bárhol, ahol szüksége van az összetett kifejezésre.

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

További információ: Változók a Bicepben.

Források

resource A kulcsszóval definiálhat egy üzembe helyezhető erőforrást. Az erőforrás-deklaráció az erőforrás szimbolikus nevét tartalmazza. Ezt a szimbolikus nevet a Bicep-fájl más részeiben használja az erőforrás értékének lekéréséhez.

Az erőforrás-deklaráció tartalmazza az erőforrástípust és az API-verziót. Az erőforrás-deklaráció törzsében szerepeljenek az erőforrástípusra jellemző tulajdonságok.

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

További információ: Erőforrás-deklaráció a Bicepben.

Egyes erőforrások szülő-gyermek kapcsolatban vannak. Gyermekerőforrást a szülőerőforráson belül vagy azon kívül is meghatározhat.

Az alábbi példa bemutatja, hogyan definiálhat gyermekerőforrást egy szülőerőforráson belül. Tartalmaz egy tárfiókot a tárfiókban definiált gyermekerőforrással (fájlszolgáltatással). A fájlszolgáltatás egy gyermekerőforrással (megosztással) is rendelkezik, amely benne van definiálva.

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

A következő példa bemutatja, hogyan definiálhat gyermekerőforrást a szülőerőforráson kívül. A szülőtulajdonság használatával azonosíthatja a szülő-gyermek kapcsolatot. Ugyanaz a három erőforrás van definiálva.

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
}

További információ: Gyermekerőforrások nevének és típusának beállítása a Bicepben.

Modulok

A modulok lehetővé teszik, hogy más Bicep-fájlokban lévő Bicep-fájlokból származó kódot újra felhasználjon. A modul deklarációjában hivatkozik a fájlra, hogy újra felhasználhassa. A Bicep-fájl üzembe helyezésekor a modul erőforrásai is üzembe lesznek helyezve.

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

A szimbolikus név lehetővé teszi a modul hivatkozását a fájl más részeiről. Egy modul kimeneti értékét például a szimbolikus névvel és a kimeneti érték nevével is lekérheti.

További információ: Bicep-modulok használata.

Erőforrás- és modul-dekorátorok

Dekorátort hozzáadhat egy erőforrás- vagy moduldefinícióhoz. A támogatott dekorátorok és batchSize(int)description. Csak kifejezéseket használó for erőforrás- vagy moduldefiníciókra alkalmazhatja.

Alapértelmezés szerint az erőforrások párhuzamosan vannak üzembe helyezve. A dekoratőr hozzáadásakor batchSize(int) a példányokat sorosan helyezi üzembe.

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

További információ: Üzembe helyezés kötegekben.

Outputs

Kimenetek használatával adja vissza az üzembe helyezés értékeit. Általában akkor ad vissza egy értéket egy üzembe helyezett erőforrásból, ha ezt az értéket újra kell használnia egy másik művelethez.

output storageEndpoint object = stg.properties.primaryEndpoints

További információ: Kimenetek a Bicepben.

Hurkok

A Bicep-fájlhoz iteratív hurkokat adhat hozzá a következő fájlok több példányának definiálásához:

erőforrás
modult
változó
tulajdonság
output

A kifejezés használatával for definiálhat egy hurkot.

param moduleCount int = 2

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

Egy tömb, objektum vagy egész szám indexe iterálható.

További információ: Iteratív hurkok a Bicepben.

Feltételes üzembe helyezés

A feltételesen üzembe helyezett Bicep-fájlhoz hozzáadhat egy erőforrást vagy modult. Az üzembe helyezés során a rendszer kiértékeli a feltételt, és az eredmény meghatározza, hogy az erőforrás vagy a modul üzembe lett-e helyezve. A kifejezéssel if feltételes üzembe helyezést határozhat meg.

param deployZone bool

resource dnsZone 'Microsoft.Network/dnszones@2018-05-01' = if (deployZone) {
  name: 'myZone'
  location: 'global'
}

További információ: Feltételes üzembe helyezés a Bicepben.

Térköz

A bicep-fájlok létrehozásakor a rendszer figyelmen kívül hagyja a szóközöket és a lapokat.

Bicep newline sensitive. Például:

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

Nem írható így:

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

Objektumok és tömbök definiálása több sorban.

Megjegyzések

Egysoros megjegyzésekhez vagy /* ... */ többsoros megjegyzésekhez használható //

Az alábbi példában egy egysoros megjegyzés látható.

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

Az alábbi példában egy többsoros megjegyzés látható.

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

Többsoros sztringek

A sztringeket több sorra bonthatja. A többsoros sztring elindításához és befejezéséhez használjon három egyetlen idézőjelet ''' .

A többsoros sztringben lévő karakterek kezelése a következőképpen történik. A feloldó karakterek szükségtelenek. A többsoros sztringben nem szerepelhet ''' . A sztring interpolációja jelenleg nem támogatott.

Elindíthatja a sztringet közvetlenül a megnyitás ''' után, vagy felvehet egy új sort. Mindkét esetben az eredményül kapott sztring nem tartalmaz új sort. A Bicep-fájlban lévő sorvégződéstől függően a rendszer az új sorokat a következőképpen értelmezi \r\n : vagy \n.

Az alábbi példa egy többsoros sztringet mutat be.

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

Az előző példa a következő JSON-nak felel meg.

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

Többsoros deklarációk

Mostantól több sort is használhat függvény-, tömb- és objektumdeklarációkban. Ehhez a funkcióhoz a Bicep CLI 0.7.X-es vagy újabb verziója szükséges.

Az alábbi példában a resourceGroup() definíció több sorra van bontva.

var foo = resourceGroup(
  mySubscription,
  myRgName)

Többsoros deklarációmintákat a Tömbök és objektumok című témakörben talál.

Known limitations

Az apiProfile fogalma nem támogatott, amely egyetlen apiProfile egy adott apiVersion-ra való leképezésére szolgál az egyes erőforrástípusokhoz.
A felhasználó által definiált függvények jelenleg nem támogatottak. Egy kísérleti funkció azonban jelenleg elérhető. További információ: Felhasználó által definiált függvények a Bicepben.
Egyes Bicep-funkciókhoz a köztes nyelv (Azure Resource Manager JSON-sablonok) megfelelő módosítása szükséges. Ezeket a funkciókat akkor tesszük elérhetővé, ha az összes szükséges frissítés üzembe lett helyezve a globális Azure-ban. Ha más környezetet használ, például az Azure Stacket, előfordulhat, hogy a funkció rendelkezésre állása késik. A Bicep szolgáltatás csak akkor érhető el, ha a köztes nyelv is frissült ebben a környezetben.

További lépések

A Bicep bemutatása: Mi az a Bicep?. Bicep-adattípusok esetén lásd : Adattípusok.