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

  • Makale
  • Okumak için 6 dakika

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.

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>

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

@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

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:

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

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 değer sağlanmazsa kullanılan parametre için varsayılan bir değer tanımlayabilirsiniz.

Örneğin, bir kaynağın farklı boyutlarını belirtmek için bir SKU parametresi ekleyebilirsiniz. Teste mi yoksa üretime mi dağıtım yaptığı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 başka birçok dekoratör vardır.

@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şkende karmaşık ifadeleri kapsülleyerek Bicep dosyanızı daha okunabilir hale getirebilirsiniz. Örneğin, birkaç değeri bir araya getirerek bir kaynak adı için bir değişken ekleyebilirsiniz.

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

Bu değişkeni karmaşık ifadeye ihtiyacınız olan her yere 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. Kaynaktan bir değer almak için bu sembolik adı Bicep dosyasının diğer bölümlerinde kullanacaksı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. Üst kaynağın içinde veya dışında bir alt kaynak 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@2021-02-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ği kullanırsınız. Aynı üç kaynak tanımlanır.

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
}

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 tek dekoratördür batchSize(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 ö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.

Çıkış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 bir öğesinin 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ılmayacağı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.

Boşluk

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

Bicep yeni satıra duyarlıdır. Örnek:

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 sürüm 0.7.4 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

  • Her kaynak türü için tek bir apiProfile'ı ayarlanmış bir apiVersion ile eşlemek için kullanılan apiProfile kavramı için destek yoktur.
  • Kullanıcı tanımlı işlevler için destek yoktur.
  • 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ıma sunulduğunu duyuruyoruz. Azure Stack gibi farklı bir ortam kullanıyorsanız özelliğin kullanılabilirliği gecikmeli olabilir. Bicep özelliği yalnızca bu ortamda ara dil de 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.