Bicep dosyalarının yapısını ve söz dizimini anlama

  • Makale

Bu makalede Bicep dosyasının yapısı ve söz dizimi açıklanmaktadır. Dosyanın farklı bölümlerini ve bu bölümlerde kullanılabilen özellikleri sunar.

Bicep dosyası oluşturma işleminde size yol gösteren adım adım öğretici için bkz . Hızlı Başlangıç: Visual Studio Code ile Bicep dosyaları oluşturma.

Bicep biçimi

Bicep bildirim temelli bir dildir ve bu da öğelerin herhangi bir sırada görünebileceği anlamına gelir. Kesinlik temelli dillerden farklı olarak, öğelerin sırası dağıtımın nasıl işlendiğini etkilemez.

Bicep dosyasında aşağıdaki öğeler bulunur.

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>

Aşağıdaki örnekte bu öğelerin bir uygulaması gösterilmektedir.

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

Meta veri

Bicep'teki meta veriler, Bicep dosyalarına eklenebilen yazılmamış bir değerdir. Bicep dosyalarınız hakkında ad, açıklama, yazar, oluşturma tarihi ve daha fazlası gibi ek bilgiler sağlamanıza olanak tanır.

Hedef kapsam

Varsayılan olarak, hedef kapsam olarak resourceGroupayarlanır. Kaynak grubu düzeyinde dağıtıyorsanız, Bicep dosyanızda hedef kapsamı ayarlamanız gerekmez.

İzin verilen değerler şunlardır:

  • resourceGroup - kaynak grubu dağıtımları için kullanılan varsayılan değer.
  • subscription - Abonelik dağıtımları için kullanılır.
  • managementGroup - yönetim grubu dağıtımları için kullanılır.
  • tenant - kiracı dağıtımları için kullanılır.

Modülde, Bicep dosyasının geri kalanının kapsamından farklı bir kapsam belirtebilirsiniz. Daha fazla bilgi için bkz . Modül kapsamını yapılandırma

Türler

Kullanıcı tanımlı veri türlerini tanımlamak için deyimini type kullanabilirsiniz.

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

Daha fazla bilgi için bkz . Kullanıcı tanımlı veri türleri.

İşlevler (Önizleme)

Dekont

Önizleme özelliğini etkinleştirmek için bkz . Deneysel özellikleri etkinleştirme.

Bicep dosyanızda, Bicep dosyalarınızda otomatik olarak kullanılabilen standart Bicep işlevlerini kullanmanın yanı sıra kendi işlevlerinizi de oluşturabilirsiniz. Bicep dosyalarınızda tekrar tekrar kullanılan karmaşık ifadeleriniz olduğunda kendi işlevlerinizi oluşturun.

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

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

Daha fazla bilgi için bkz . Kullanıcı tanımlı işlevler.

Parametreler

Farklı dağıtımlar için değişiklik göstermesi gereken değerler için parametreleri kullanın. Dağıtım sırasında hiçbir değer sağlanmazsa kullanılan parametre için varsayılan bir değer tanımlayabilirsiniz.

Örneğin, bir kaynak için farklı boyutlar belirtmek üzere bir SKU parametresi ekleyebilirsiniz. Teste mi yoksa üretime mi dağıttığınıza bağlı olarak farklı değerler geçirebilirsiniz.

param storageSKU string = 'Standard_LRS'

parametresi, Bicep dosyanızda kullanılabilir.

sku: {
  name: storageSKU
}

Daha fazla bilgi için bkz . Bicep'te Parametreler.

Parametre dekoratörleri

Her parametre için bir veya daha fazla dekoratör ekleyebilirsiniz. Bu dekoratörler parametresini açıklar ve geçirilen değerler için kısıtlamalar tanımlar. Aşağıdaki örnekte bir dekoratör gösterilmektedir ancak diğer birçok dekoratör kullanılabilir.

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

Kullanılabilir tüm dekoratörlerin açıklamaları da dahil olmak üzere daha fazla bilgi için bkz . Dekoratörler.

Değişkenler

Bir değişkendeki karmaşık ifadeleri kapsülleyerek Bicep dosyanızı daha okunabilir hale getirebilirsiniz. Örneğin, bir kaynak adı için çeşitli değerleri birleştirerek birleştirilmiş bir değişken ekleyebilirsiniz.

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

Karmaşık ifadeye ihtiyacınız olan her yere bu değişkeni uygulayın.

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

Daha fazla bilgi için bkz . Bicep'te değişkenler.

Kaynaklar

resource Dağıtılacak kaynağı tanımlamak için anahtar sözcüğünü kullanın. Kaynak bildiriminiz kaynak için sembolik bir ad içerir. Bu sembolik adı, kaynaktan bir değer almak için Bicep dosyasının diğer bölümlerinde kullanırsınız.

Kaynak bildirimi, kaynak türünü ve API sürümünü içerir. Kaynak bildiriminin gövdesinde, kaynak türüne özgü özellikleri ekleyin.

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

Daha fazla bilgi için bkz . Bicep'te kaynak bildirimi.

Bazı kaynakların üst/alt ilişkisi vardır. Alt kaynağı üst kaynağın içinde veya dışında tanımlayabilirsiniz.

Aşağıdaki örnekte, üst kaynak içinde bir alt kaynağın nasıl tanımlanacağı gösterilmektedir. Depolama hesabı içinde tanımlanan bir alt kaynağa (dosya hizmeti) sahip bir depolama hesabı içerir. Dosya hizmetinin içinde tanımlanmış bir alt kaynak (paylaşım) da vardır.

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

Sonraki örnekte, üst kaynağın dışında bir alt kaynağın nasıl tanımlanacağı gösterilmektedir. Üst/alt ilişkiyi tanımlamak için üst özelliğini kullanırsınız. Aynı üç kaynak tanımlanır.

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
}

Daha fazla bilgi için bkz . Bicep'te alt kaynaklar için ad ve tür ayarlama.

Modül

Modüller, bir Bicep dosyasındaki kodu diğer Bicep dosyalarında yeniden kullanmanıza olanak tanır. Modül bildiriminde yeniden kullanmak üzere dosyaya bağlanırsınız. Bicep dosyasını dağıttığınızda modüldeki kaynaklar da dağıtılır.

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

Sembolik ad, modüle dosyanın başka bir yerinden başvurmanızı sağlar. Örneğin, sembolik adı ve çıkış değerinin adını kullanarak bir modülden çıkış değeri alabilirsiniz.

Daha fazla bilgi için bkz . Bicep modüllerini kullanma.

Kaynak ve modül dekoratörleri

Kaynak veya modül tanımına dekoratör ekleyebilirsiniz. Desteklenen dekoratörler ve description'tirbatchSize(int). Bunu yalnızca ifade kullanan for bir kaynak veya modül tanımına uygulayabilirsiniz.

Varsayılan olarak, kaynaklar paralel olarak dağıtılır. Dekoratör eklediğinizde batchSize(int) örnekleri seri olarak dağıtırsınız.

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

Daha fazla bilgi için bkz . Toplu olarak dağıtma.

Çıktılar

Dağıtımdan değer döndürmek için çıkışları kullanın. Genellikle, başka bir işlem için bu değeri yeniden kullanmanız gerektiğinde dağıtılan bir kaynaktan bir değer döndürürsiniz.

output storageEndpoint object = stg.properties.primaryEndpoints

Daha fazla bilgi için bkz . Bicep'te çıkışlar.

Döngüler

Bicep dosyanıza yinelemeli döngüler ekleyerek şunun birden çok kopyasını tanımlayabilirsiniz:

  • kaynak
  • modül
  • değişken
  • özellik
  • çıkış

Döngü tanımlamak için ifadeyi for kullanın.

param moduleCount int = 2

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

Dizi, nesne veya tamsayı dizini üzerinde yineleme yapabilirsiniz.

Daha fazla bilgi için bkz . Bicep'te yinelemeli döngüler.

Koşullu dağıtım

Bicep dosyanıza koşullu olarak dağıtılan bir kaynak veya modül ekleyebilirsiniz. Dağıtım sırasında koşul değerlendirilir ve sonuç kaynağın veya modülün dağıtılıp dağıtılmadığını belirler. if Koşullu dağıtım tanımlamak için ifadesini kullanın.

param deployZone bool

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

Daha fazla bilgi için bkz . Bicep'te koşullu dağıtım.

Whitespace

Bicep dosyaları yazarken boşluklar ve sekmeler yoksayılır.

Bicep yeni satıra duyarlıdır. Örneğin:

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

Şu şekilde yazılamaz:

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

Nesneleri ve dizileri birden çok satırda tanımlayın.

Yorumlar

Tek satırlı açıklamalar veya /* ... */ çok satırlı açıklamalar için kullanın //

Aşağıdaki örnekte tek satırlık bir açıklama gösterilmektedir.

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

Aşağıdaki örnekte çok satırlı bir açıklama gösterilmektedir.

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

Çok satırlı dizeler

Bir dizeyi birden çok satıra bölebilirsiniz. Çok satırlı dizeyi başlatmak ve sonlandırmak için üç tek tırnak karakteri ''' kullanın.

Çok satırlı dizedeki karakterler olduğu gibi işlenir. Kaçış karakterleri gereksizdir. Çok satırlı dizeye ekleyemezsiniz ''' . Dize ilişkilendirmesi şu anda desteklenmiyor.

Dizenizi açmadan ''' hemen sonra başlatabilir veya yeni bir satır ekleyebilirsiniz. Her iki durumda da, sonuçta elde edilen dize yeni bir satır içermez. Bicep dosyanızdaki satır sonlarına bağlı olarak, yeni satırlar veya \nolarak \r\n yorumlanır.

Aşağıdaki örnekte çok satırlı bir dize gösterilmektedir.

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

Yukarıdaki örnek aşağıdaki JSON ile eşdeğerdir.

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

Çok satırlı bildirimler

Artık işlev, dizi ve nesne bildirimlerinde birden çok satır kullanabilirsiniz. Bu özellik için Bicep CLI sürüm 0.7.X veya üzeri gerekir.

Aşağıdaki örnekte tanım resourceGroup() birden çok satıra ayrılmıştır.

var foo = resourceGroup(
  mySubscription,
  myRgName)

Birden çok satırlı bildirim örnekleri için bkz . Diziler ve Nesneler .

Bilinen sınırlamalar

  • Tek bir apiProfile'ı her kaynak türü için ayarlanmış bir apiVersion ile eşlemek için kullanılan apiProfile kavramı için destek yoktur.
  • Kullanıcı tanımlı işlevler şu anda desteklenmiyor. Ancak deneysel bir özelliğe şu anda erişilebilir durumdadır. Daha fazla bilgi için bkz . Bicep'te kullanıcı tanımlı işlevler.
  • Bazı Bicep özellikleri için ara dilde (Azure Resource Manager JSON şablonları) karşılık gelen bir değişiklik gerekir. Tüm gerekli güncelleştirmeler genel Azure'a dağıtıldığında bu özellikleri kullanılabilir olarak duyuruyoruz. Azure Stack gibi farklı bir ortam kullanıyorsanız özelliğin kullanılabilirliği gecikmeli olabilir. Bicep özelliği yalnızca ara dil de bu ortamda güncelleştirildiğinde kullanılabilir.

Sonraki adımlar

Bicep'e giriş için bkz . Bicep nedir?. Bicep veri türleri için bkz . Veri türleri.