Aracılığıyla paylaş


Bicep dosya yapısı ve söz dizimi

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:

@<decorator>(<argument>)
metadata <metadata-name> = ANY

targetScope = '<scope>'

@<decorator>(<argument>)
type <user-defined-data-type-name> = <type-expression>

@<decorator>(<argument>)
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>

@<decorator>(<argument>)
var <variable-name> = <variable-value>

@<decorator>(<argument>)
resource <resource-symbolic-name> '<resource-type>@<api-version>' = {
  <resource-properties>
}

@<decorator>(<argument>)
module <module-symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

@<decorator>(<argument>)
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@2023-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
  }
}

Meta veri

Bicep'teki meta veriler, Bicep dosyalarınıza ekleyebileceğiniz yazılmamış bir değerdir. Meta veriler, Bicep dosyalarınız hakkında ad, açıklama, yazar ve oluşturma tarihi gibi ek bilgiler sağlar.

Hedef kapsam

Varsayılan olarak, hedef kapsam olarak resourceGroupayarlanır. Kaynak grubu düzeyinde dağıtım yaparsanı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çinkullanı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 .

Dekoratörler

Aşağıdaki öğelerin her biri için bir veya daha fazla dekoratör ekleyebilirsiniz:

Aşağıdaki tabloda dekoratörler listelenir:

Dekoratör Öğeye uygula Veri türüne uygula Bağımsız değişken Açıklama
İzinli param tümü dizi Kullanıcının doğru değerler sağladığından emin olmak için bu dekoratörü kullanın. Bu dekoratöre yalnızca param deyimlerinde izin verilir. Bir özelliğin veya type deyiminde output önceden tanımlanmış bir değer kümesinden biri olması gerektiğini bildirmek için birleşim türü söz dizimini kullanın. param deyimlerinde birleşim türü söz dizimlerini de kullanabilirsiniz.
yığınBoyutu modül, kaynak Yok tamsayı Örnekleri sıralı olarak dağıtılacak şekilde ayarlayın.
açıklama func, param, modül, çıkış, kaynak, tür, var tümü Dize Öğeler için açıklamalar sağlayın. Açıklama metni için Markdown biçimli metin kullanın.
Ayrımcı param, type, output nesne Dize Doğru alt sınıfın tanımlandığından ve yönetildiğinden emin olmak için bu dekoratörü kullanın. Daha fazla bilgi için Özel etiketli birleşim veri türü'ne bakın.
dışarı aktarma func, type, var tümü yok Başka bir Bicep dosyasının öğeyi içeri aktarabileceğini gösterir.
maksimumUzunluk param, çıkış, tür dizi, dize int Dize ve dizi öğeleri için uzunluk üst sınırı. Değer kapsayıcıdır.
maksimum değer param, çıkış, tür int int Tamsayı öğelerinin en büyük değeri. Bu değer kapsam dahiline alınmıştır.
meta veriler func, output, param, type tümü nesne Öğelere uygulanacak özel özellikler. Açıklama dekoratörüne eşdeğer bir açıklama özelliği içerebilir.
minimum uzunluk param, çıkış, tür dizi, dize int Dize ve dizi öğeleri için en düşük uzunluk. Değer kapsayıcıdır.
minDeğer param, çıkış, tür int int Tamsayı öğelerinin en küçük değeri. Bu değer kapsam dahiline alınmıştır.
mühürlü param, type, output nesne yok Kullanıcı tanımlı veri türünün özellik adının yazım hatası olasılığı yüksek olduğunda, BCP089'yi uyarıdan hataya yükseltin. Daha fazla bilgi için bkz Hata düzeyini yükseltme.
güvenli param, tür dize, nesne yok parametresini güvenli olarak işaretler. Güvenli bir parametrenin değeri dağıtım geçmişine ve günlüklere kaydedilmez. Daha fazla bilgi için bkz . Güvenli dizeler ve nesneler.

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 bir 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ğıttığınıza bağlı olarak farklı değerler geçirebilirsiniz.

param storageSKU string = 'Standard_LRS'

Bu parametre, Bicep dosyanızda kullanılabilir.

sku: {
  name: storageSKU
}

Her parametre için bir veya daha fazla dekoratör ekleyebilirsiniz. Daha fazla bilgi için Dekoratörleri kullanma başlığına bkz.

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

Değişkenler

Bicep dosyanızı daha okunabilir hale getirmek için bir değişkendeki karmaşık ifadeleri kapsülleyin. Örneğin, bir kaynak adı için birkaç değeri birleştirerek 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@2023-04-01' = {
  name: uniqueStorageName

Her değişken için bir veya daha fazla dekoratör ekleyebilirsiniz. Daha fazla bilgi için Dekoratörleri kullanma başlığına bkz.

Daha fazla bilgi için Bicep'te Değişkenler dokümanına bakın.

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@2023-04-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

Kullanıcı tanımlı her veri türü için bir veya daha fazla dekoratör ekleyebilirsiniz. Daha fazla bilgi için Dekoratörleri kullanma başlığına bkz.

Daha fazla bilgi için bkz. Bicep'te kullanıcı tanımlı veri türleri.

İşlevler

Bicep dosyanızda kendi işlevlerinizi oluşturabilir ve ayrıca Bicep dosyalarınızda otomatik olarak kullanılabilen standart Bicep işlevlerini kullanabilirsiniz. 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 . Bicep'te kullanıcı tanımlı işlevler.

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. Bicep dosyasının diğer bölümlerinde, kaynaktan bir değer almak için bu sembolik adı 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@2023-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

Her kaynak için bir veya daha fazla dekoratör ekleyebilirsiniz. Daha fazla bilgi için Dekoratörleri kullanma başlığına bkz.

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

Bazı kaynakların ebeveyn/çocuk ilişkisi vardır. Alt kaynağı, ana kaynağın içinde veya dışında tanımlayabilirsiniz.

Aşağıdaki örnekte, ana kaynak içindeki 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@2023-04-01' = {
  name: 'examplestorage'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }

  resource service 'fileServices' = {
    name: 'default'

    resource share 'shares' = {
      name: 'exampleshare'
    }
  }
}

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

resource storage 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: 'examplestorage'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

resource service 'Microsoft.Storage/storageAccounts/fileServices@2023-04-01' = {
  name: 'default'
  parent: storage
}

resource share 'Microsoft.Storage/storageAccounts/fileServices/shares@2023-04-01' = {
  name: 'exampleshare'
  parent: service
}

Daha fazla bilgi için Bicep'te alt kaynaklar için ad ve tür ayarlama bölümüne bakın.

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.

Her modül için bir veya daha fazla dekoratör ekleyebilirsiniz. Daha fazla bilgi için Dekoratörleri kullanma başlığına bkz.

Daha fazla bilgi için Bicep modüllerini kullanma'ya bakın.

Çıkışlar

Dağıtım işlemlerinden değerleri geri döndürmek için çıktı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

Her çıkış için bir veya daha fazla dekoratör ekleyebilirsiniz. Daha fazla bilgi için Dekoratörleri kullanma başlığına bkz.

Daha fazla bilgi için Bicep'te Çıkışlar kısmına bakın.

Döngüler

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

  • Kaynak
  • Modül
  • Değişken
  • Bir özellik
  • Bir çıktı

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 Bicep'teki yinelemeli döngüler bölümüne bakın.

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@2023-07-01-preview' = if (deployZone) {
  name: 'myZone'
  location: 'global'
}

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

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@2023-04-01' = if (newOrExisting == 'new') {
  ...
}

Şu şekilde yazılamaz:

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

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

Açıklamalar

Tek satırlı açıklamalar için // 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@2023-11-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 işareti kullanın.

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

dizenizi '''açıldıktan 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 \r\n veya \n şeklinde 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)

Çok satırlı bildirim örnekleri için bkz. diziler ve nesneleri.

Bilinen sınırlamalar

  • Tek bir apiProfile'i her kaynak türü için bir apiProfile kümesine eşlemek amacıyla kullanılan apiVersionkavramı için destek mevcut değildir.
  • Kullanıcı tanımlı işlevler şu anda desteklenmiyor. Deneysel bir özelliğe şu anda erişilebilir. 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ıktan sonra 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ştirildikten sonra kullanılabilir.