Memahami struktur dan sintaksis file Bicep

Artikel
10/17/2024

Artikel ini menguraikan struktur dan sintaks file Bicep. Di sini akan disajikan berbagai bagian file dan properti yang tersedia di bagian tersebut.

Untuk mengetahui tutorial langkah demi langkah yang memandu Anda melalui proses pembuatan file Bicep, lihat Mulai cepat: Membuat file Bicep dengan Visual Studio Code.

Format Bicep

Bicep adalah bahasa komputer deklaratif, yang berarti elemen dapat muncul dalam urutan mana pun. Tidak seperti bahasa komputer imperatif, urutan elemennya tidak memengaruhi cara penyebaran diproses.

File Bicep memiliki elemen berikut.

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

Contoh berikut menunjukkan implementasi elemen-elemen ini.

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

Metadata

Metadata di Bicep adalah nilai yang tidak dititip yang dapat disertakan dalam file Bicep. Ini memungkinkan Anda untuk memberikan informasi tambahan tentang file Bicep Anda, termasuk detail seperti nama, deskripsi, penulis, tanggal pembuatan, dan banyak lagi.

Cakupan target

Secara default, cakupan target diatur ke resourceGroup. Jika Anda melakukan penyebaran di tingkat grup sumber daya, Anda tidak perlu mengatur cakupan target dalam file Bicep Anda.

Nilai yang diperbolehkan adalah:

resourceGroup - nilai default, digunakan untuk penyebaran grup sumber daya.
subscription - digunakan untuk penyebaran langganan.
managementGroup - digunakan untuk penyebaran grup manajemen.
tenant - digunakan untuk penyebaran penyewa.

Dalam sebuah modul, Anda dapat menentukan cakupan yang berbeda dari cakupan untuk file Bicep lainnya. Untuk informasi selengkapnya, lihat Mengonfigurasi cakupan modul

Dekorator

Anda dapat menambahkan satu atau beberapa dekorator untuk setiap elemen berikut:

param
var
resource
module
output
func
jenis

Dekorator meliputi:

Dekorator	Terapkan ke elemen	Terapkan ke tipe data	Argumen	Deskripsi
diizinkan	param	all	array	Gunakan dekorator ini untuk memastikan pengguna memberikan nilai yang benar. Dekorator ini hanya diizinkan pada `param` pernyataan. Untuk menyatakan bahwa properti harus merupakan salah satu dari sekumpulan nilai yang telah ditentukan sebelumnya dalam pernyataan `type` atau `output` , gunakan sintaks jenis union. Sintaks jenis union juga dapat digunakan dalam `param` pernyataan.
batchSize	modul, sumber daya	T/A	Integer	Siapkan instans untuk disebarkan secara berurutan.
description	func, param, modul, output, sumber daya, jenis, var	all	string	Berikan deskripsi untuk elemen. Teks berformat markdown dapat digunakan untuk teks deskripsi.
diskriminator	param, jenis, output	object	string	Gunakan dekorator ini untuk memastikan subkelas yang benar diidentifikasi dan dikelola. Untuk informasi selengkapnya, lihat Jenis data serikat yang ditandai kustom.
ekspor	func, type, var	all	tidak ada	Menunjukkan bahwa elemen dapat diimpor oleh file Bicep lain.
maxLength	param, output, ketik	array, untai (karakter)	int	Panjang maksimum untuk elemen string dan array. Nilainya inklusif.
maxValue	param, output, ketik	int	int	Nilai maksimum untuk elemen bilangan bulat. Nilai ini inklusif.
metadata	func, output, param, type	all	object	Properti kustom untuk diterapkan ke elemen. Dapat mencakup properti deskripsi yang setara dengan dekorator deskripsi.
minLength	param, output, ketik	array, untai (karakter)	int	Panjang minimum untuk elemen string dan array. Nilainya inklusif.
minValue	param, output, ketik	int	int	Nilai minimum untuk elemen bilangan bulat. Nilai ini inklusif.
disegel	param, jenis, output	object	tidak ada	Tingkatkan BCP089 dari peringatan ke kesalahan ketika nama properti dari jenis data yang ditentukan penggunaan kemungkinan salah ketik. Untuk informasi selengkapnya, lihat Meningkatkan tingkat kesalahan.
aman	param, ketik	untai (karakter), objek	tidak ada	Menandai parameter sebagai aman. Nilai parameter aman tidak disimpan ke riwayat penyebaran dan tidak dicatat ke dalam log. Untuk informasi lebih lanjut, lihat Untai (karakter) dan objek yang aman.

Parameter

Gunakan parameter untuk nilai yang perlu bervariasi untuk penyebaran yang berbeda. Anda dapat menentukan nilai default untuk parameter yang digunakan jika tidak ada nilai yang disediakan selama proses penyebaran.

Misalnya, Anda dapat menambahkan parameter SKU untuk menentukan ukuran yang berbeda untuk sumber daya. Anda mungkin lulus dengan nilai yang berbeda tergantung pada apakah Anda menggunakannya untuk menguji atau produksi.

param storageSKU string = 'Standard_LRS'

Parameter tersedia untuk digunakan dalam file Bicep Anda.

sku: {
  name: storageSKU
}

Anda dapat menambahkan satu atau beberapa dekorator untuk setiap parameter. Untuk informasi selengkapnya, lihat Menggunakan dekorator.

Untuk informasi selengkapnya, lihat Parameter di Bicep.

Variabel

Anda dapat membuat file Bicep Anda lebih mudah dibaca dengan merangkum ekspresi kompleks dalam variabel. Misalnya, Anda dapat menambahkan variabel untuk nama sumber daya yang dibangun dengan menggabungkan beberapa nilai bersamaan.

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

Terapkan variabel ini di mana pun Anda membutuhkan ekspresi yang kompleks.

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

Anda dapat menambahkan satu atau beberapa dekorator untuk setiap variabel. Untuk informasi selengkapnya, lihat Menggunakan dekorator.

Untuk mengetahui informasi selengkapnya, lihat Variabel dalam Bicep.

Jenis

Anda dapat menggunakan type pernyataan untuk menentukan jenis data yang ditentukan pengguna.

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

Anda dapat menambahkan satu atau beberapa dekorator untuk setiap jenis data yang ditentukan pengguna. Untuk informasi selengkapnya, lihat Menggunakan dekorator.

Untuk informasi selengkapnya, lihat Jenis data yang ditentukan pengguna.

Fungsi

Dalam file Bicep, Anda dapat membuat fungsi Anda sendiri selain menggunakan fungsi Bicep standar yang secara otomatis tersedia dalam file Bicep Anda. Buat fungsi Anda sendiri saat Anda memiliki ekspresi rumit yang digunakan berulang kali dalam file Bicep Anda.

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

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

Untuk informasi selengkapnya, lihat Fungsi yang ditentukan pengguna.

Sumber

Gunakan kata kunci resource untuk menentukan sumber daya untuk disebarkan. Deklarasi sumber daya Anda menyertakan nama simbolis untuk sumber daya. Anda menggunakan nama simbolis ini di bagian lain file Bicep untuk mendapatkan nilai dari sumber daya.

Deklarasi sumber daya juga mencakup jenis sumber daya dan versi API. Dalam isi deklarasi sumber daya, sertakan properti yang khusus untuk jenis sumber dayanya.

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

Anda dapat menambahkan satu atau beberapa dekorator untuk setiap sumber daya. Untuk informasi selengkapnya, lihat Menggunakan dekorator.

Untuk informasi selengkapnya, lihat Deklarasi sumber daya dalam Bicep.

Beberapa sumber daya memiliki hubungan induk/anak. Anda bisa menetapkan sumber daya anak baik di dalam sumber daya induk maupun di luar sumber daya induk.

Contoh berikut memperlihatkan cara menetapkan sumber daya anak di dalam sumber daya induk. Ini berisi akun penyimpanan dengan sumber daya anak (layanan file) yang ditetapkan di dalam akun penyimpanan. Layanan file juga memiliki sumber daya anak (berbagi) yang ditetapkan di dalamnya.

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

Contoh berikutnya memperlihatkan cara menetapkan sumber daya anak di luar sumber daya induk. Anda menggunakan properti induk untuk mengidentifikasi hubungan induk/anak. Tiga sumber daya yang sama ditetapkan.

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
}

Untuk informasi selengkapnya, lihat Mengatur nama dan jenis untuk sumber daya anak dalam Bicep.

Modul

Modul memungkinkan Anda untuk menggunakan kembali kode dari file Bicep dalam file Bicep lainnya. Dalam deklarasi modul, Anda menautkan ke file untuk digunakan kembali. Saat Anda menerapkan file Bicep, sumber daya dalam modul juga digunakan.

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

Dengan nama simbolis, Anda dapat mereferensikan modul dari tempat lain dalam file. Misalnya, Anda bisa mendapatkan nilai output dari modul dengan menggunakan nama simbolis dan nama nilai output.

Anda dapat menambahkan satu atau beberapa dekorator untuk setiap modul. Untuk informasi selengkapnya, lihat Menggunakan dekorator.

Untuk mengetahui informasi lebih lanjut, lihat Menggunakan modul Bicep.

Output

Gunakan output untuk mengembalikan nilai dari penyebaran. Biasanya, Anda mengembalikan nilai dari sumber daya yang disebarkan saat Anda perlu menggunakan kembali nilai tersebut untuk operasi lain.

output storageEndpoint object = stg.properties.primaryEndpoints

Anda dapat menambahkan satu atau beberapa dekorator untuk setiap output. Untuk informasi selengkapnya, lihat Menggunakan dekorator.

Untuk mengetahui informasi selengkapnya, lihat Output dalam Bicep.

Perulangan

Anda dapat menambahkan perulangan secara berulang ke file Bicep Anda untuk menetapkan beberapa salinan:

resource
modul
variabel
properti
output

Gunakan ekspresi for untuk menentukan perulangan.

param moduleCount int = 2

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

Anda dapat mengulangi array, objek, atau indeks integer.

Untuk informasi selengkapnya, lihat loop Iterasi di Bisep.

Penyebaran kondisional

Anda dapat menambahkan sumber daya atau modul ke file Bicep Anda yang disebarkan secara kondisional. Selama penyebaran, kondisi dievaluasi dan hasilnya menentukan apakah sumber daya atau modul disebarkan. Gunakan ekspresi if untuk menentukan penyebaran kondisional.

param deployZone bool

resource dnsZone 'Microsoft.Network/dnsZones@2023-07-01-preview' = if (deployZone) {
  name: 'myZone'
  location: 'global'
}

Untuk mengetahui informasi selengkapnya, lihat Pnyebaran bersyarat dalam Bisep.

Whitespace

Spasi dan tab diabaikan saat menulis file Bicep.

Bicep sensitif terhadap garis baru. Contohnya:

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

Tidak dapat ditulis sebagai:

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

Tentukan objek dan array dalam beberapa baris.

Komentar

Gunakan // untuk komentar satu baris atau /* ... */ untuk komentar beberapa baris

Contoh berikut memperlihatkan komentar satu baris.

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

Contoh berikut memperlihatkan komentar multibaris.

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

String multibaris

Anda dapat memecah string menjadi beberapa baris. Gunakan tiga karakter kutipan tunggal ''' untuk memulai dan mengakhiri string multibaris.

Karakter dalam string multibaris ditangani apa adanya. Karakter escape tidak diperlukan. Anda tidak dapat menyertakan ''' di string multibaris. Interpolasi string saat ini tidak didukung.

Anda dapat memulai string tepat setelah membuka ''' atau menyertakan baris baru. Dalam kedua kasus, string yang dihasilkan tidak menyertakan baris baru. Bergantung pada akhir baris dalam file Bicep Anda, baris baru diinterpretasikan sebagai \r\n atau \n.

Contoh berikut memperlihatkan string multibaris.

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

Contoh sebelumnya setara dengan JSON berikut.

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

Deklarasi beberapa baris

Anda sekarang dapat menggunakan beberapa baris dalam deklarasi fungsi, array, dan objek. Fitur ini memerlukan Bicep CLI versi 0.7.X atau yang lebih tinggi.

Dalam contoh berikut, definisi resourceGroup() dipecah menjadi beberapa baris.

var foo = resourceGroup(
  mySubscription,
  myRgName)

Lihat Array dan Objects untuk sampel deklarasi beberapa baris.

Pembatasan yang diketahui

Tidak ada dukungan untuk konsep apiProfile yang digunakan untuk memetakan apiProfile tunggal ke set apiVersion untuk setiap jenis sumber daya.
Fungsi yang ditentukan pengguna saat ini tidak didukung. Namun, fitur eksperimental saat ini dapat diakses. Untuk informasi selengkapnya, lihat Fungsi yang ditentukan pengguna di Bicep.
Beberapa fitur Bicep memerlukan perubahan terkait pada bahasa perantara (templat JSON Azure Resource Manager). Kami menetapkan fitur ini menjadi tersedia ketika semua pembaruan yang diperlukan telah disebarkan ke Azure global. Jika Anda menggunakan lingkungan lain, seperti Azure Stack, dapat terjadi penundaan dalam ketersediaan fitur. Fitur Bicep hanya tersedia ketika bahasa perantara juga telah diperbarui di lingkungan tersebut.

Langkah berikutnya

Sebagai pengantar ke Bicep, lihat Apa itu Bicep?. Untuk mengetahui jenis data Bicep, lihat Jenis data.

Bagikan melalui