Memahami struktur dan sintaksis file Bicep

Artikel
11/03/2023

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.

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>

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

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

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

Untuk informasi selengkapnya, lihat Jenis data yang ditentukan pengguna.

Functions (Pratinjau)

Catatan

Untuk mengaktifkan fitur pratinjau, lihat Mengaktifkan fitur eksperimental.

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.

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
}

Untuk informasi selengkapnya, lihat Parameter di Bicep.

Dekorator parameter

Anda dapat menambahkan satu atau beberapa dekorator untuk setiap parameter. Dekorator ini menggambarkan parameter dan menentukan batasan untuk nilai-nilai yang diteruskan. Contoh berikut menunjukkan satu dekorator tetapi banyak lainnya tersedia.

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

Untuk informasi lebih lanjut, termasuk deskripsi semua dekorator yang tersedia, lihat Dekorator.

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@2019-04-01' = {
  name: uniqueStorageName

Untuk mengetahui informasi selengkapnya, lihat Variabel dalam Bicep.

Sumber daya

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@2019-06-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

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@2022-09-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@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
}

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.

Untuk mengetahui informasi lebih lanjut, lihat Menggunakan modul Bicep.

Dekorator sumber daya dan modul

Anda dapat menambahkan dekorator ke definisi sumber daya atau modul. Dekorator yang didukung adalah batchSize(int) dan description. Anda hanya dapat menerapkannya ke definisi sumber daya atau modul yang menggunakan ekspresi for.

Secara default, sumber daya disebarkan secara paralel. Saat Anda menambahkan dekorator batchSize(int), Anda menerapkan instans secara serial.

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

Untuk informasi selengkapnya, lihat Menyebarkan dalam batch.

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

Untuk mengetahui informasi selengkapnya, lihat Output dalam Bicep.

Perulangan

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

sumber daya
module
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@2018-05-01' = 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. Misalnya:

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

Tidak dapat ditulis sebagai:

resource sa 'Microsoft.Storage/storageAccounts@2019-06-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@2020-06-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.

Batasan umum

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.