Bagikan melalui

Perulangan berulang di Bicep

Artikel ini menunjukkan kepada Anda cara menggunakan sintaks for untuk mengiterasi item dalam koleksi. Fungsionalitas ini didukung mulai dari v0.3.1 dan seterusnya. Anda dapat menggunakan perulangan untuk menentukan beberapa salinan sumber daya, modul, variabel, properti, atau output. Gunakan perulangan untuk menghindari sintaks berulang dalam file Bicep Anda dan untuk secara dinamis mengatur jumlah salinan yang akan dibuat selama penyebaran. Lihat Mulai Cepat: Membuat beberapa instans sumber daya di Bicep untuk panduan cepat tentang cara menggunakan berbagai sintaks untuk membuat beberapa instans sumber daya di Bicep.

Untuk menggunakan perulangan untuk membuat beberapa sumber daya atau modul, setiap instans harus memiliki nilai unik untuk properti name. Anda dapat menggunakan nilai indeks atau nilai unik dalam array atau koleksi untuk membuat nama.

Sintaks perulangan

Perulangan dapat dideklarasikan dengan:

  • Menggunakan indeks bilangan bulat. Opsi ini berfungsi ketika skenario Anda adalah: "Saya ingin membuat instans sebanyak ini." Fungsi rentang membuat array bilangan bulat yang dimulai pada indeks awal dan berisi jumlah elemen yang ditentukan. Dalam perulangan, Anda dapat menggunakan indeks bilangan bulat untuk mengubah nilai. Untuk informasi selengkapnya, lihat Indeks bilangan bulat.

    [for <index> in range(<startIndex>, <numberOfElements>): {
  ...
}]

  • Menggunakan item dalam array: Opsi ini berfungsi saat skenario Anda adalah, "Saya ingin membuat objek untuk setiap elemen dalam array." Dalam perulangan, Anda dapat menggunakan nilai elemen array saat ini untuk memodifikasi nilai lainnya. Untuk informasi selengkapnya, lihat Elemen array.

    [for <item> in <collection>: {
  ...
}]

  • Menggunakan item dalam objek kamus: Opsi ini berfungsi saat skenario Anda adalah, "Saya ingin membuat instans untuk setiap item dalam objek." Fungsi item mengonversi objek menjadi array. Dalam perulangan, Anda dapat menggunakan properti pada objek untuk menghasilkan nilai. Untuk informasi selengkapnya, lihat Objek kamus.

    [for <item> in items(<object>): {
  ...
}]

  • Menggunakan indeks bilangan bulat dan item dalam array: Opsi ini berfungsi saat skenario Anda adalah, "Saya ingin membuat instans untuk setiap elemen dalam array, tetapi saya juga memerlukan indeks saat ini untuk membuat nilai lain." Untuk informasi selengkapnya, lihat Pengulangan array dan indeks.

    [for (<item>, <index>) in <collection>: {
  ...
}]

  • Menambahkan penyebaran kondisional: Opsi ini dapat digunakan ketika skenario Anda adalah, "Saya ingin membuat beberapa instans, tetapi saya hanya ingin menyebarkan setiap instans ketika kondisinya benar." Untuk informasi selengkapnya, lihat Perulangan dengan kondisi.

    [for <item> in <collection>: if(<condition>) {
  ...
}]

Batas perulangan

Menggunakan perulangan di Bicep memiliki batasan berikut:

  • Perulangan Bicep hanya berfungsi dengan nilai yang dapat ditentukan pada saat memulai penyebaran.
  • Perulangan perulangan tidak boleh berupa angka negatif atau melebihi 800 iterasi.
  • Karena sumber daya tidak dapat berulang dengan sumber daya anak yang bertingkat, ubah sumber daya anak menjadi sumber daya tingkat atas. Untuk informasi selengkapnya, lihat Perulangan untuk sumber daya anak.
  • Untuk mengulang beberapa tingkat properti, gunakan fungsi lambdamap.

Indeks bilangan bulat

Untuk contoh sederhana menggunakan indeks, buat variabel yang berisi array string:

param itemCount int = 5

var stringArray = [for i in range(0, itemCount): 'item${(i + 1)}']

output arrayResult array = stringArray

Output menghasilkan array dengan nilai-nilai berikut:

[
  "item1",
  "item2",
  "item3",
  "item4",
  "item5"
]

Contoh berikutnya membuat jumlah akun penyimpanan yang ditentukan dalam storageCount parameter . Ini mengembalikan tiga properti untuk setiap akun penyimpanan:

param location string = resourceGroup().location
param storageCount int = 2

resource storageAcct 'Microsoft.Storage/storageAccounts@2025-06-01' = [for i in range(0, storageCount): {
  name: '${i}storage${uniqueString(resourceGroup().id)}'
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'Storage'
}]

output storageInfo array = [for i in range(0, storageCount): {
  id: storageAcct[i].id
  blobEndpoint: storageAcct[i].properties.primaryEndpoints.blob
  status: storageAcct[i].properties.statusOfPrimary
}]

Perhatikan bahwa indeks i digunakan dalam membuat nama sumber daya akun penyimpanan.

Contoh berikutnya menyebarkan modul tersebut berulang kali:

param location string = resourceGroup().location
param storageCount int = 2

var baseName = 'store${uniqueString(resourceGroup().id)}'

module stgModule './storageAccount.bicep' = [for i in range(0, storageCount): {
  name: '${i}deploy${baseName}'
  params: {
    storageName: '${i}${baseName}'
    location: location
  }
}]

output storageAccountEndpoints array = [for i in range(0, storageCount): {
  endpoint: stgModule[i].outputs.storageEndpoint
}]

Elemen-elemen dalam array

Contoh berikut membuat satu akun penyimpanan untuk setiap nama yang disediakan dalam storageNames parameter . Perhatikan properti nama untuk setiap instans sumber daya harus unik:

param location string = resourceGroup().location
param storageNames array = [
  'contoso'
  'fabrikam'
  'coho'
]

resource storageAcct 'Microsoft.Storage/storageAccounts@2025-06-01' = [for name in storageNames: {
  name: '${name}${uniqueString(resourceGroup().id)}'
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'Storage'
}]

Contoh berikutnya berulang melalui array untuk menentukan properti. Ini membuat dua subnet dalam jaringan virtual. Perhatikan bahwa nama subnet harus unik:

param rgLocation string = resourceGroup().location

var subnets = [
  {
    name: 'api'
    subnetPrefix: '10.144.0.0/24'
  }
  {
    name: 'worker'
    subnetPrefix: '10.144.1.0/24'
  }
]

resource vnet 'Microsoft.Network/virtualNetworks@2025-01-01' = {
  name: 'vnet'
  location: rgLocation
  properties: {
    addressSpace: {
      addressPrefixes: [
        '10.144.0.0/20'
      ]
    }
    subnets: [for subnet in subnets: {
      name: subnet.name
      properties: {
        addressPrefix: subnet.subnetPrefix
      }
    }]
  }
}

Array dan indeks

Contoh berikut menggunakan elemen array dan nilai indeks saat menentukan akun penyimpanan:

param storageAccountNamePrefix string

var storageConfigurations = [
  {
    suffix: 'local'
    sku: 'Standard_LRS'
  }
  {
    suffix: 'geo'
    sku: 'Standard_GRS'
  }
]

resource storageAccountResources 'Microsoft.Storage/storageAccounts@2025-06-01' = [for (config, i) in storageConfigurations: {
  name: '${storageAccountNamePrefix}${config.suffix}${i}'
  location: resourceGroup().location
  sku: {
    name: config.sku
  }
  kind: 'StorageV2'
}]

Contoh berikutnya menggunakan elemen array dan indeks untuk menghasilkan informasi tentang sumber daya baru:

param location string = resourceGroup().location
param orgNames array = [
  'Contoso'
  'Fabrikam'
  'Coho'
]

resource nsg 'Microsoft.Network/networkSecurityGroups@2025-01-01' = [for name in orgNames: {
  name: 'nsg-${name}'
  location: location
}]

output deployedNSGs array = [for (name, i) in orgNames: {
  orgName: name
  nsgName: nsg[i].name
  resourceId: nsg[i].id
}]

Objek kamus

Untuk mengulangi elemen dalam objek kamus, gunakan items fungsi , yang mengonversi objek menjadi array. Gunakan properti value untuk mendapatkan properti pada objek. Perhatikan bahwa nama sumber daya nsg harus unik.

param nsgValues object = {
  nsg1: {
    name: 'nsg-westus1'
    location: 'westus'
  }
  nsg2: {
    name: 'nsg-east1'
    location: 'eastus'
  }
}

resource nsg 'Microsoft.Network/networkSecurityGroups@2025-01-01' = [for nsg in items(nsgValues): {
  name: nsg.value.name
  location: nsg.value.location
}]

Perulangan dengan kondisi

Untuk sumber daya dan modul, Anda dapat menambahkan if ekspresi dengan sintaks perulangan untuk menyebarkan koleksi secara kondisional.

Contoh berikut menunjukkan perulangan yang dikombinasikan dengan pernyataan kondisi. Dalam contoh ini, satu kondisi diterapkan ke semua instans modul:

param location string = resourceGroup().location
param storageCount int = 2
param createNewStorage bool = true

var baseName = 'store${uniqueString(resourceGroup().id)}'

module stgModule './storageAccount.bicep' = [for i in range(0, storageCount): if(createNewStorage) {
  name: '${i}deploy${baseName}'
  params: {
    storageName: '${i}${baseName}'
    location: location
  }
}]

Contoh berikutnya menunjukkan cara menerapkan kondisi yang khusus untuk elemen saat ini dalam array:

resource parentResources 'Microsoft.Example/examples@2024-06-06' = [for parent in parents: if(parent.enabled) {
  name: parent.name
  properties: {
    children: [for child in parent.children: {
      name: child.name
      setting: child.settingValue
    }]
  }
}]

Melakukan penyebaran dalam kelompok

Sumber daya Azure disebarkan secara paralel secara default. Saat Anda menggunakan perulangan untuk membuat beberapa instans jenis sumber daya, semua instans tersebut disebarkan secara bersamaan. Urutan pembuatannya tidak dijamin. Tidak ada batasan jumlah sumber daya yang disebarkan secara paralel selain batas total 800 sumber daya dalam file Bicep.

Anda mungkin tidak ingin memperbarui semua instans jenis sumber daya secara bersamaan. Misalnya, saat memperbarui lingkungan produksi, Anda mungkin ingin menjadwalkan pembaruan bertahap agar hanya sejumlah tertentu yang diperbarui pada satu waktu. Anda dapat menentukan subset instans yang akan di-batch bersama dan disebarkan secara bersamaan. Instans lain menunggu batch tersebut sampai selesai.

Untuk menyebarkan instans sumber daya secara serial, tambahkan batchSize dekorator. Atur nilainya ke jumlah instans untuk disebarkan secara bersamaan. Dependensi dibuat selama instans sebelumnya dalam perulangan, sehingga tidak memulai satu batch hingga batch sebelumnya selesai.

param location string = resourceGroup().location

@batchSize(2)
resource storageAcct 'Microsoft.Storage/storageAccounts@2025-06-01' = [for i in range(0, 4): {
  name: '${i}storage${uniqueString(resourceGroup().id)}'
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'Storage'
}]

Untuk penyebaran berurutan, atur ukuran batch ke 1.

Dekorator batchSize berada di namespace sys. Jika Anda perlu membedakan dekorator ini dari item lain dengan nama yang sama, awali dekorator dengan sys: @sys.batchSize(2)

Iterasi untuk sumber daya anak

Untuk membuat lebih dari satu instans sumber daya anak, kedua file Bicep berikut mendukung tugas ini:

Sumber daya anak tertanam

param location string = resourceGroup().location

resource stg 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: 'examplestorage'
  location: location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
  resource service 'fileServices' = {
    name: 'default'
    resource share 'shares' = [for i in range(0, 3): {
      name: 'exampleshare${i}'
    }]
  }
}

Sumber daya anak tingkat atas

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

resource service 'Microsoft.Storage/storageAccounts/fileServices@2025-06-01' = {
  name: 'default'
  parent: stg
}

resource share 'Microsoft.Storage/storageAccounts/fileServices/shares@2025-06-01' = [for i in range(0, 3): {
  name: 'exampleshare${i}'
  parent: service
}]

Mereferensikan kumpulan sumber daya/modul

Fungsi templat Azure Resource Manager (templat ARM) references mengembalikan array objek yang mewakili status runtime kumpulan sumber daya. Karena tidak ada fungsi eksplisit references dalam Bicep dan penggunaan pengumpulan simbolis digunakan secara langsung, Bicep menerjemahkannya ke templat ARM yang menggunakan fungsi templat references ARM saat kode dihasilkan. Untuk fitur terjemahan yang menggunakan references fungsi untuk mengubah koleksi simbolis menjadi templat ARM, perlu memiliki Bicep CLI versi 0.20.X atau yang lebih tinggi. Selain itu, dalam file bicepconfig.json , symbolicNameCodegen pengaturan harus disajikan dan diatur ke true.

Hasil dari dua sampel dalam indeks Bilangan Bulat dapat ditulis sebagai:

param location string = resourceGroup().location
param storageCount int = 2

resource storageAcct 'Microsoft.Storage/storageAccounts@2025-06-01' = [for i in range(0, storageCount): {
  name: '${i}storage${uniqueString(resourceGroup().id)}'
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'Storage'
}]

output storageInfo array = map(storageAcct, store => {
  blobEndpoint: store.properties.primaryEndpoints
  status: store.properties.statusOfPrimary
})

output storageAccountEndpoints array = map(storageAcct, store => store.properties.primaryEndpoints)

File Bicep ini ditranspilasi ke dalam templat ARM JSON berikut yang menggunakan references fungsi :

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "1.10-experimental",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "storageCount": {
      "type": "int",
      "defaultValue": 2
    }
  },
  "resources": {
    "storageAcct": {
      "copy": {
        "name": "storageAcct",
        "count": "[length(range(0, parameters('storageCount')))]"
      },
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2023-04-01",
      "name": "[format('{0}storage{1}', range(0, parameters('storageCount'))[copyIndex()], uniqueString(resourceGroup().id))]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage"
    }
  },
  "outputs": {
    "storageInfo": {
      "type": "array",
      "value": "[map(references('storageAcct', 'full'), lambda('store', createObject('blobEndpoint', lambdaVariables('store').properties.primaryEndpoints, 'status', lambdaVariables('store').properties.statusOfPrimary)))]"
    },
    "storageAccountEndpoints": {
      "type": "array",
      "value": "[map(references('storageAcct', 'full'), lambda('store', lambdaVariables('store').properties.primaryEndpoints))]"
    }
  }
}

Catatan dalam templat ARM JSON sebelumnya, languageVersion harus diatur ke 1.10-experimental, dan elemen sumber daya adalah objek alih-alih array.

Langkah selanjutnya

Untuk mempelajari cara membuat file Bicep, lihat Struktur dan sintaks file Bicep.

  • Last updated on