Perulangan sumber daya dalam templat ARM

  • Artikel

Artikel ini menunjukkan kepada Anda cara membuat lebih dari satu instans sumber daya di templat Azure Resource Manager (templat ARM) Anda. Dengan menambahkan perulangan salinan ke bagian sumber daya templat Anda, Anda dapat secara dinamis mengatur jumlah sumber daya untuk disebarkan. Anda juga menghindari keharusan mengulangi sintaksis templat.

Anda juga dapat menggunakan perulangan salinan dengan properti, variabel, dan output.

Jika Anda perlu menentukan apakah sumber daya disebarkan sama sekali, lihat elemen kondisi.

Tip

Kami merekomendasikan Bicep karena menawarkan kemampuan yang sama dengan templat ARM dan sintaksnya lebih mudah digunakan. Untuk mempelajari selengkapnya, lihat perulangan.

Sintaks

Tambahkan elemen copy ke bagian sumber daya templat Anda untuk menyebarkan beberapa instans sumber daya. Elemen copy memiliki format umum berikut:

"copy": {
  "name": "<name-of-loop>",
  "count": <number-of-iterations>,
  "mode": "serial" <or> "parallel",
  "batchSize": <number-to-deploy-serially>
}

Properti name adalah nilai apa pun yang mengidentifikasi perulangan. Properti count menentukan jumlah perulangan yang Anda inginkan untuk jenis sumber daya.

Gunakan properti mode dan batchSize untuk menentukan apakah sumber daya disebarkan secara paralel atau berurutan. Properti ini dijelaskan dalam Serial atau Paralel.

Batas penyalinan

Jumlahnya tidak bisa melebihi 800.

Hitungannya tidak bisa menjadi angka negatif. Ini bisa nol jika Anda menyebarkan template dengan versi terbaru Azure CLI, PowerShell, atau REST API. Secara khusus, Anda harus menggunakan:

  • Azure PowerShell 2.6 atau yang lebih baru
  • Azure CLI 2.0.74 atau yang lebih baru
  • Rest API versi 2019-05-10 atau lebih tinggi
  • Penerapan tertaut harus menggunakan API versi 2019-05-10 atau yang lebih baru untuk jenis sumber daya penyebaran

Versi PowerShell, CLI, dan REST API yang lebih lama tidak mendukung nol untuk dihitung.

Hati-hati menggunakan penyebaran mode lengkap dengan perulangan salinan. Jika Anda melakukan penyebaran ulang dengan mode lengkap ke grup sumber daya, sumber daya apa pun yang tidak ditentukan dalam templat setelah menyelesaikan perulangan salinan akan dihapus.

Perulangan sumber daya

Contoh berikut membuat jumlah akun penyimpanan yang ditentukan dalam parameter storageCount.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "storageCount": {
      "type": "int",
      "defaultValue": 3
    }
  },
  "resources": [
    {
      "copy": {
        "name": "storagecopy",
        "count": "[length(range(0, parameters('storageCount')))]"
      },
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2022-09-01",
      "name": "[format('{0}storage{1}', range(0, parameters('storageCount'))[copyIndex()], uniqueString(resourceGroup().id))]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "properties": {}
    }
  ]
}

Perhatikan bahwa nama setiap sumber daya menyertakan fungsi copyIndex(), yang mengembalikan perulangan saat ini dalam perulangan. copyIndex() adalah berbasis nol. Lihat contoh berikut:

"name": "[format('storage{0}', copyIndex())]",

Membuat nama-nama ini:

  • storage0
  • storage1
  • storage2

Untuk mengimbangi nilai indeks, Anda dapat meneruskan nilai dalam fungsi copyIndex(). Jumlah perulangan masih ditentukan dalam elemen salin, tetapi nilai copyIndex diimbangi dengan nilai yang ditentukan. Lihat contoh berikut:

"name": "[format('storage{0}', copyIndex(1))]",

Membuat nama-nama ini:

  • storage1
  • storage2
  • storage3

Operasi salin sangat membantu saat bekerja dengan array karena Anda dapat melakukan perulangan melalui setiap elemen dalam array. Gunakan fungsi length pada array untuk menentukan hitungan untuk perulangan, dan copyIndex untuk mengambil indeks saat ini dalam array.

Contoh berikut membuat satu akun penyimpanan untuk setiap nama yang disediakan dalam parameter.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageNames": {
      "type": "array",
      "defaultValue": [
        "contoso",
        "fabrikam",
        "coho"
      ]
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    }
  },
  "resources": [
    {
      "copy": {
        "name": "storagecopy",
        "count": "[length(parameters('storageNames'))]"
      },
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2022-09-01",
      "name": "[format('{0}{1}', parameters('storageNames')[copyIndex()], uniqueString(resourceGroup().id))]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "properties": {}
    }
  ]
}

Jika Anda ingin mengembalikan nilai dari sumber daya yang disebarkan, Anda bisa menggunakan salin di bagian output.

Gunakan nama simbolis

Nama simbolis akan ditetapkan ke perulangan salinan sumber daya. Indeks perulangan berbasis nol. Dalam contoh berikut, myStorages[1] mereferensikan sumber daya kedua dalam perulangan sumber daya.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "storageCount": {
      "type": "int",
      "defaultValue": 2
    }
  },
  "resources": {
    "myStorages": {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2022-09-01",
      "name": "[format('{0}storage{1}', copyIndex(), uniqueString(resourceGroup().id))]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "properties": {},
      "copy": {
        "name": "storagecopy",
        "count": "[parameters('storageCount')]"
      }
    }
  },
  "outputs": {
    "storageEndpoint":{
      "type": "object",
      "value": "[reference('myStorages[1]').primaryEndpoints]"
    }
  }
}

Jika indeks adalah nilai runtime, format referensi sendiri. Misalnya

"outputs": {
  "storageEndpoint":{
    "type": "object",
    "value": "[reference(format('myStorages[{0}]', variables('runtimeIndex'))).primaryEndpoints]"
  }
}

Nama simbolis dapat digunakan dalam array dependsOn. Jika nama simbolis adalah untuk perulangan salinan, semua sumber daya dalam perulangan ditambahkan sebagai dependensi. Untuk informasi selengkapnya, lihat Bergantung pada sumber daya dalam perulangan.

Serial atau Paralel

Secara default, Resource Manager membuat sumber daya secara paralel. Tidak ada batasan untuk jumlah sumber daya yang disebarkan secara paralel, selain batas total 800 sumber daya dalam templat. Urutan pembuatannya tidak dijamin.

Namun, Anda mungkin ingin menentukan sumber daya disebarkan secara berurutan. Misalnya, saat memperbarui lingkungan produksi, Anda mungkin ingin mengejutkan pembaruan sehingga hanya angka tertentu yang diperbarui pada satu waktu.

Untuk menyebarkan lebih dari satu instans sumber daya secara serial, atur mode ke serial dan batchSize ke jumlah instans untuk disebarkan pada satu waktu. Dengan mode serial, Resource Manager membuat dependensi pada instans sebelumnya dalam perulangan, sehingga tidak memulai satu batch hingga batch sebelumnya selesai.

Nilai untuk batchSize tidak boleh melebihi nilai untuk count di elemen salin.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    }
  },
  "resources": [
    {
      "copy": {
        "name": "storagecopy",
        "count": 4,
        "mode": "serial",
        "batchSize": 2
      },
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2022-09-01",
      "name": "[format('{0}storage{1}', range(0, 4)[copyIndex()], uniqueString(resourceGroup().id))]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "properties": {}
    }
  ]
}

Properti mode juga menerima paralel, yang merupakan nilai default.

Perulangan untuk sumber daya anak

Anda tidak dapat menggunakan perulangan salinan untuk sumber daya anak. Untuk membuat lebih dari satu instans sumber daya yang biasanya Anda tetapkan sebagai berlapis di dalam sumber daya lain, Anda harus membuat sumber daya tersebut sebagai sumber daya tingkat teratas. Anda menetapkan hubungan dengan sumber daya induk melalui properti jenis dan nama.

Misalnya, Anda biasanya menetapkan set data sebagai sumber daya anak dalam pabrik data.

{
  "resources": [
    {
      "type": "Microsoft.DataFactory/factories",
      "name": "exampleDataFactory",
      ...
      "resources": [
        {
          "type": "datasets",
          "name": "exampleDataSet",
          "dependsOn": [
            "exampleDataFactory"
          ],
          ...
        }
      ]
      ...
    }
  ]
}

Untuk membuat lebih dari satu set data, pindahkan ke luar pabrik data. Set data harus berada pada tingkat yang sama dengan pabrik data, tetapi masih merupakan sumber daya anak dari pabrik data. Anda mempertahankan hubungan antara set data dan pabrik data melalui properti jenis dan nama. Karena jenis tidak lagi dapat disimpulkan dari posisinya dalam templat, Anda harus menyediakan jenis yang sepenuhnya memenuhi syarat dalam format: {resource-provider-namespace}/{parent-resource-type}/{child-resource-type}.

Untuk menjalin hubungan induk/anak dengan instans pabrik data, berikan nama untuk set data yang menyertakan nama sumber daya induk. Gunakan format: {parent-resource-name}/{child-resource-name}.

Contoh berikut menunjukkan implementasinya.

"resources": [
{
  "type": "Microsoft.DataFactory/factories",
  "name": "exampleDataFactory",
  ...
},
{
  "type": "Microsoft.DataFactory/factories/datasets",
  "name": "[format('exampleDataFactory/exampleDataSet{0}', copyIndex())]",
  "dependsOn": [
    "exampleDataFactory"
  ],
  "copy": {
    "name": "datasetcopy",
    "count": "3"
  },
  ...
}]

Contoh templat

Contoh berikut menunjukkan skenario umum untuk membuat lebih dari satu instans sumber daya atau properti.

Templat Deskripsi
Salin penyimpanan Menyebarkan lebih dari satu akun penyimpanan dengan nomor indeks dalam nama.
Salin penyimpanan serial Menyebarkan beberapa akun penyimpanan satu per satu. Nama ini menyertakan nomor indeks.
Salin penyimpanan dengan array Menyebarkan beberapa akun penyimpanan. Nama ini menyertakan nilai dari array.
Salin grup sumber daya Menyebarkan beberapa grup sumber daya.

Langkah berikutnya