Memahami struktur dan sintaks templat ARM

Artikel ini menjelaskan struktur templat Azure Resource Manager (templat ARM). Isi artikel menyajikan berbagai bagian templat dan properti yang tersedia di bagian tersebut.

Artikel ini ditujukan untuk pengguna yang telah memiliki pemahaman terkait templat ARM. Di dalamnya tersedia informasi terperinci tentang struktur templat. Untuk tutorial langkah demi langkah yang memandu Anda melalui proses pembuatan templat, lihat Tutorial: Membuat dan menerapkan templat ARM pertama Anda. Untuk mempelajari template ARM melalui set modul Learn terpandu, lihat Menyebarkan dan mengelola sumber daya di Azure dengan menggunakan template ARM.

Tip

Bicep adalah bahasa baru yang menawarkan kemampuan yang sama seperti templat ARM tetapi dengan sintaks yang lebih mudah digunakan. Jika Anda sedang mempertimbangkan infrastruktur sebagai opsi kode, kami menyarankan Anda untuk melihat Bicep.

Untuk mempelajari tentang elemen file Bicep, lihat Memahami struktur dan sintaks file Bicep.

Format templat

Dalam strukturnya yang paling sederhana, templat memiliki elemen berupa:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "",
  "apiProfile": "",
  "parameters": {  },
  "variables": {  },
  "functions": [  ],
  "resources": [  ],
  "outputs": {  }
}
Nama elemen Diperlukan Deskripsi
$skema Ya Lokasi file skema JavaScript Object Notation (JSON) yang menjelaskan versi bahasa templat. Nomor versi yang Anda gunakan tergantung pada cakupan penyebaran dan editor JSON Anda.

Jika Anda menggunakan Visual Studio Code dengan ekstensi alat Azure Resource Manager, gunakan versi terbaru untuk penyebaran grup sumber daya:
https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#

Editor lain (termasuk Visual Studio) mungkin tidak dapat memproses skema ini. Untuk editor tersebut, gunakan:
https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#

Untuk penyebaran langganan, gunakan:
https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#

Untuk penyebaran grup manajemen, gunakan:
https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#

Untuk penyebaran penyewa, gunakan:
https://schema.management.azure.com/schemas/2019-08-01/tenantDeploymentTemplate.json#
contentVersion Ya Versi templat (seperti 1.0.0.0). Anda dapat memberikan nilai apa pun untuk elemen ini. Gunakan nilai tersebut untuk mendokumentasikan perubahan signifikan dalam templat Anda. Saat menyebarkan sumber daya menggunakan templat, nilai tersebut dapat digunakan untuk memastikan bahwa templat yang tepat sedang digunakan.
apiProfile Tidak Versi API yang berfungsi sebagai kumpulan versi API untuk jenis sumber daya. Gunakan nilai tersebut untuk menghindari keharusan menentukan versi API untuk setiap sumber daya di dalam templat. Saat Anda menentukan versi profil API dan tidak menentukan versi API untuk jenis sumber daya, Resource Manager menggunakan versi API untuk jenis sumber daya yang ditentukan dalam profil.

Properti profil API sangat membantu saat menyebarkan templat ke lingkungan yang berbeda, seperti Azure Stack dan Azure global. Gunakan versi profil API untuk memastikan templat Anda secara otomatis menggunakan versi yang didukung di kedua lingkungan. Untuk daftar versi profil API saat ini dan versi API sumber daya yang ditentukan pada profil, lihat Profil API.

Untuk informasi selengkapnya, lihat Lacak versi menggunakan profil API.
parameter Tidak Nilai yang diberikan saat penyebaran dijalankan untuk menyesuaikan penyebaran sumber daya.
variabel Tidak Nilai yang digunakan sebagai fragmen JSON dalam templat untuk menyederhanakan ekspresi templat.
fungsi Tidak Fungsi yang ditentukan pengguna tersedia di dalam templat.
sumber daya Ya Tipe sumber daya yang disebarkan atau diperbarui dalam grup sumber daya atau langganan.
output Tidak Nilai yang dikembalikan setelah penyebaran.

Setiap elemen memiliki properti yang dapat Anda tetapkan. Artikel ini menjelaskan bagian templat secara terperinci.

Parameter

Di bagian parameters templat, Anda menentukan nilai mana yang dapat Anda masukkan saat menyebarkan sumber daya. Anda dibatasi hingga 256 parameter dalam templat. Anda dapat mengurangi jumlah parameter dengan menggunakan objek yang berisi beberapa properti.

Properti yang tersedia untuk parameter adalah:

"parameters": {
  "<parameter-name>" : {
    "type" : "<type-of-parameter-value>",
    "defaultValue": "<default-value-of-parameter>",
    "allowedValues": [ "<array-of-allowed-values>" ],
    "minValue": <minimum-value-for-int>,
    "maxValue": <maximum-value-for-int>,
    "minLength": <minimum-length-for-string-or-array>,
    "maxLength": <maximum-length-for-string-or-array-parameters>,
    "metadata": {
      "description": "<description-of-the parameter>"
    }
  }
}
Nama elemen Diperlukan Deskripsi
Nama parameter Ya Nama parameter. Harus menjadi pengidentifikasi JavaScript yang valid.
jenis Ya Jenis nilai parameter. Jenis dan nilai yang diizinkan adalah string, securestring,int, bool,object,secureObject, dan array. Lihat Jenis data dalam templat ARM.
defaultValue Tidak Nilai default untuk parameter, jika tidak ada nilai yang diberikan untuk parameter.
allowedValues Tidak Larik nilai yang diizinkan untuk parameter guna memastikan bahwa nilai yang benar diberikan.
minValue Tidak Nilai minimum untuk parameter jenis int termasuk nilai inklusif.
maxValue Tidak Nilai maksimum untuk parameter jenis int termasuk nilai inklusif.
minLength Tidak Panjang minimum untuk string, string aman, dan parameter tipe larik termasuk nilai inklusif.
maxLength Tidak Panjang maksimum untuk string, string aman, dan parameter tipe larik termasuk nilai inklusif.
deskripsi Tidak Deskripsi parameter yang ditampilkan kepada pengguna melalui portal. Untuk informasi selengkapnya, lihat Komentar di dalam templat.

Untuk contoh penggunakan parameter, lihat Parameter di templat ARM.

Pada Bicep, lihat parameter.

Variabel

Di bagian variables ini, Anda membuat nilai yang dapat digunakan di seluruh templat Anda. Anda tidak perlu menentukan variabel, tetapi templat Anda sering disederhanakan dengan cara mengurangi ekspresi kompleks. Format setiap variabel sesuai dengan salah satu jenis data. Anda dibatasi hingga 256 variabel dalam templat.

Contoh berikut menunjukkan pilihan yang tersedia untuk menentukan variabel:

"variables": {
  "<variable-name>": "<variable-value>",
  "<variable-name>": {
    <variable-complex-type-value>
  },
  "<variable-object-name>": {
    "copy": [
      {
        "name": "<name-of-array-property>",
        "count": <number-of-iterations>,
        "input": <object-or-value-to-repeat>
      }
    ]
  },
  "copy": [
    {
      "name": "<variable-array-name>",
      "count": <number-of-iterations>,
      "input": <object-or-value-to-repeat>
    }
  ]
}

Untuk informasi tentang copy membuat beberapa nilai untuk variabel, lihat Perulangan variabel.

Untuk contoh cara menggunakan variabel, lihat Variabel dalam templat ARM.

Pada Bicep, lihat variabel.

Fungsi

Dalam templat Anda, Anda dapat membuat fungsi Anda sendiri. Fungsi tersebut tersedia untuk digunakan pada templat Anda. Biasanya, Anda menentukan ekspresi rumit yang tidak ingin Anda ulangi di seluruh templat Anda. Anda membuat fungsi yang ditentukan pengguna dari ekspresi dan fungsi yang didukung dalam templat.

Saat mendefinisikan fungsi pengguna, ada beberapa batasan:

  • Fungsi tidak dapat mengakses variabel.
  • Fungsi tersebut hanya dapat menggunakan parameter yang ditentukan dalam fungsi. Saat Anda menggunakan fungsi parameter dalam fungsi yang ditentukan pengguna, Anda dibatasi pada parameter untuk fungsi tersebut.
  • Fungsi tersebut tidak dapat memanggil fungsi lain yang ditentukan pengguna.
  • Fungsi tidak dapat menggunakan fungsi referensi.
  • Parameter untuk fungsi tidak diperbolehkan memiliki nilai default.
"functions": [
  {
    "namespace": "<namespace-for-functions>",
    "members": {
      "<function-name>": {
        "parameters": [
          {
            "name": "<parameter-name>",
            "type": "<type-of-parameter-value>"
          }
        ],
        "output": {
          "type": "<type-of-output-value>",
          "value": "<function-return-value>"
        }
      }
    }
  }
],
Nama elemen Diperlukan Deskripsi
namespace Ya Namespace untuk fungsi kustom. Gunakan untuk menghindari konflik penamaan dengan fungsi templat.
nama fungsi Ya Nama fungsi kustom. Saat memanggil fungsi, gabungkan nama fungsi dengan namespace. Misalnya, untuk memanggil fungsi bernama uniqueName di dalam contoso namespace, gunakan "[contoso.uniqueName()]".
Nama parameter Tidak Nama parameter yang akan digunakan dalam fungsi kustom.
nilai parameter Tidak Jenis nilai parameter. Jenis dan nilai yang diizinkan adalah string, securestring,int, bool,object,secureObject, dan array.
jenis output Ya Jenis nilai output. Nilai output mendukung jenis yang sama dengan parameter input fungsi.
nilai output Ya Ekspresi bahasa templat yang dievaluasi dan dikembalikan dari fungsi.

Untuk contoh cara menggunakan fungsi kustom, lihat Fungsi yang ditentukan pengguna pada templat ARM.

Pada Bicep, fungsi yang ditentukan pengguna tidak didukung. Bicep memang mendukung berbagai fungsi dan operator.

Sumber

Di bagian resources tersebut, Anda menentukan sumber daya yang disebarkan atau diperbarui. Anda dibatasi hingga 800 sumber daya dalam templat.

Anda mendefinisikan sumber daya dengan struktur berikut:

"resources": [
  {
      "condition": "<true-to-deploy-this-resource>",
      "type": "<resource-provider-namespace/resource-type-name>",
      "apiVersion": "<api-version-of-resource>",
      "name": "<name-of-the-resource>",
      "comments": "<your-reference-notes>",
      "location": "<location-of-resource>",
      "dependsOn": [
          "<array-of-related-resource-names>"
      ],
      "tags": {
          "<tag-name1>": "<tag-value1>",
          "<tag-name2>": "<tag-value2>"
      },
      "identity": {
        "type": "<system-assigned-or-user-assigned-identity>",
        "userAssignedIdentities": {
          "<resource-id-of-identity>": {}
        }
      },
      "sku": {
          "name": "<sku-name>",
          "tier": "<sku-tier>",
          "size": "<sku-size>",
          "family": "<sku-family>",
          "capacity": <sku-capacity>
      },
      "kind": "<type-of-resource>",
      "scope": "<target-scope-for-extension-resources>",
      "copy": {
          "name": "<name-of-copy-loop>",
          "count": <number-of-iterations>,
          "mode": "<serial-or-parallel>",
          "batchSize": <number-to-deploy-serially>
      },
      "plan": {
          "name": "<plan-name>",
          "promotionCode": "<plan-promotion-code>",
          "publisher": "<plan-publisher>",
          "product": "<plan-product>",
          "version": "<plan-version>"
      },
      "properties": {
          "<settings-for-the-resource>",
          "copy": [
              {
                  "name": ,
                  "count": ,
                  "input": {}
              }
          ]
      },
      "resources": [
          "<array-of-child-resources>"
      ]
  }
]
Nama elemen Diperlukan Deskripsi
kondisi Tidak Nilai Boolean yang menunjukkan apakah sumber daya akan tersedia selama penyebaran ini. Ketika true, sumber daya dibuat selama penyebaran. Ketika false, sumber daya dilewati untuk penyebaran ini. Lihat kondisi.
jenis Ya Jenis sumber daya. Nilai ini adalah kombinasi dari namespace penyedia sumber daya dan jenis sumber daya (seperti Microsoft.Storage/storageAccounts). Untuk menentukan nilai yang tersedia, lihat referensi templat. Untuk sumber daya anak, format jenisnya bedalam sumber daya induk atau ditentukan di luar sumber daya induk. Lihat Pengaturan nama dan jenis untuk sumber daya anak.
apiVersion Ya Versi REST API yang digunakan untuk membuat sumber daya. Saat membuat templat baru, atur nilai ke versi terbaru dari sumber daya yang Anda terapkan. Selama templat berfungsi sesuai kebutuhan, tetap gunakan versi API yang sama. Saat Anda tetap menggunakan versi API yang sama, Anda dapat meminimalkan risiko versi API baru yang mengubah cara kerja templat Anda. Pertimbangkan untuk memperbarui versi API hanya saat Anda ingin menggunakan fitur baru yang diperkenalkan dalam versi terbaru tersebut. Untuk menentukan nilai yang tersedia, lihat referensi templat.
nama Ya Nama sumber daya. Nama harus mengikuti batasan komponen URI yang ditentukan di RFC3986. Layanan Azure yang mengekspos nama sumber daya ke pihak luar memvalidasi nama tersebut untuk memastikan itu bukan upaya untuk memalsukan identitas lain. Untuk sumber daya anak, format nama bergantung pada apakah itu berlapis di dalam sumber daya induk atau ditentukan di luar sumber daya induk. Lihat Pengaturan nama dan jenis untuk sumber daya anak.
komentar Tidak Catatan Anda untuk mendokumentasikan sumber daya di templat Anda. Untuk informasi selengkapnya, lihat Komentar di dalam templat.
lokasi Bervariasi Lokasi geografis yang didukung dari sumber daya yang tersedia. Anda dapat memilih salah satu lokasi yang tersedia, umumnya lebih diutamakan memilih lokasi yang dekat dengan pengguna Anda. Anda juga dapat menempatkan sumber daya yang berinteraksi satu sama lain di wilayah yang sama. Sebagian besar jenis sumber daya memerlukan lokasi, tetapi beberapa jenis (seperti penetapan peran) tidak memerlukan lokasi. Lihat Mengatur lokasi sumber daya.
dependsOn Tidak Sumber daya yang harus digunakan sebelum sumber daya ini disebarkan. Resource Manager mengevaluasi dependensi antar sumber daya dan menyebarkannya dalam urutan yang benar. Ketika sumber daya tidak bergantung satu sama lain, sumber daya diterapkan secara paralel. Nilainya dapat berupa daftar nama sumber daya atau pengenal unik sumber daya yang dipisahkan dengan koma. Hanya daftar sumber daya yang disebarkan dalam templat ini. Sumber daya yang tidak ditentukan dalam templat ini harus sudah ada. Hindari menambahkan dependensi yang tidak perlu karena dapat memperlambat penyebaran Anda dan membuat dependensi melingkar. Untuk panduan pengaturan dependensi, lihat Menentukan urutan untuk penyebaran sumber daya di templat ARM.
tag Tidak Tag yang terkait dengan sumber daya. Terapkan tag untuk mengatur sumber daya secara logis di seluruh langganan Anda.
identity Tidak Beberapa sumber daya mendukung identitas terkelola untuk sumber daya Azure. Sumber daya tersebut memiliki objek identitas pada tingkat akar deklarasi sumber daya. Anda dapat mengatur jika identitas tersebut ditetapkan oleh pengguna atau ditetapkan sistem. Untuk identitas yang ditetapkan pengguna, berikan daftar ID sumber daya untuk identitas. Atur kunci ke ID sumber daya dan nilai ke objek kosong. Untuk informasi selengkapnya, lihat Mengonfigurasi identitas terkelola untuk sumber daya Azure di Azure VM menggunakan templat.
sku Tidak Beberapa sumber daya mengizinkan penyebaran nilai yang menentukan SKU. Misalnya, Anda dapat menentukan jenis redundansi untuk akun penyimpanan.
jenis Tidak Beberapa sumber daya mengizinkan nilai yang menentukan jenis sumber daya yang Anda terapkan. Misalnya, Anda dapat menentukan jenis Azure Cosmos DB yang akan dibuat.
cakupan Tidak Properti cakupan hanya tersedia untuk jenis sumber daya ekstensi. Gunakan saat menentukan cakupan penyebaran yang berbeda. Lihat Mengatur cakupan untuk sumber daya ekstensi di templat ARM.
menyalin Tidak Jika memerlukan lebih dari satu instans, jumlah sumber daya yang akan dibuat. Mode default bersifat paralel. Tentukan mode serial saat Anda tidak ingin semua atau sumber daya disebarkan secara bersamaan. Untuk informasi selengkapnya, lihat Membuat beberapa instan sumber daya di Azure Resource Manager.
rencana Tidak Beberapa sumber daya mengizinkan nilai yang menentukan rencana untuk disebarkan. Misalnya, Anda dapat menentukan gambar marketplace untuk komputer virtual.
properti Tidak Pengaturan konfigurasi khusus sumber daya. Nilai untuk properti sama dengan nilai yang Anda berikan di dalam isi permintaan untuk operasi REST API (metode PUT) untuk membuat sumber daya. Anda juga dapat menentukan array salinan untuk membuat beberapa instans properti. Untuk menentukan nilai yang tersedia, lihat referensi templat.
sumber daya Tidak Sumber daya anak yang bergantung pada sumber daya yang ditentukan. Cukup sediakan jenis sumber daya yang diizinkan oleh skema sumber daya induk. Dependensi pada sumber daya induk tidak tersirat. Anda harus menentukan ketergantungan tersebut secara jelas. Lihat Pengaturan nama dan jenis untuk sumber daya anak.

Pada Bicep, lihat sumber daya.

Output

Di outputs bagian tersebut, Anda menentukan nilai yang dikembalikan dari penyebaran. Biasanya, Anda mengembalikan nilai dari sumber daya yang disebarkan. Anda dibatasi hingga 64 output dalam templat.

Contoh berikut menunjukkan struktur definisi output:

"outputs": {
  "<output-name>": {
    "condition": "<boolean-value-whether-to-output-value>",
    "type": "<type-of-output-value>",
    "value": "<output-value-expression>",
    "copy": {
      "count": <number-of-iterations>,
      "input": <values-for-the-variable>
    }
  }
}
Nama elemen Diperlukan Deskripsi
nama output Ya Nama nilai output. Harus menjadi pengidentifikasi JavaScript yang valid.
kondisi Tidak Nilai Boolean menunjukkan apakah nilai output tersebut dikembalikan. Ketika true, nilai disertakan dalam output untuk penyebaran. Ketika false, nilai output dilewati untuk penyebaran ini. Ketika tidak ditentukan, nilai defaultnya adalah true.
jenis Ya Jenis nilai output. Nilai output mendukung jenis yang sama dengan parameter input templat. Jika Anda menentukan securestring untuk jenis output, nilai tidak ditampilkan dalam riwayat penyebaran dan tidak dapat diambil dari templat lain. Untuk menggunakan nilai rahasia di lebih dari satu templat, simpan rahasia di Key Vault dan referensikan di dalam file parameter. Untuk informasi selengkapnya, lihat Gunakan Azure Key Vault untuk meneruskan nilai parameter yang aman selama penyebaran.
nilai Tidak Ekspresi templat yang dievaluasi dan dikembalikan sebagai nilai output. Tentukan nilai ataumenyalin.
menyalin Tidak Digunakan untuk mengembalikan lebih dari satu nilai untuk output. Tentukan nilai atau salin. Untuk informasi selengkapnya, lihat Perulangan output di dalam templat ARM.

Untuk contoh penggunaan output, lihat Output di templat ARM.

Pada Bicep, lihat output.

Komentar dan metadata

Anda memiliki beberapa pilihan untuk menambahkan komentar dan metadata ke templat Anda.

Komentar

Untuk komentar sebaris, Anda dapat menggunakan // atau /* ... */. Di Visual Studio Code, simpan file parameter dengan komentar sebagai jenis file JSON with comments (JSONC), jika tidak, Anda akan mendapatkan pesan kesalahan yang mengatakan "Komentar tidak diizinkan di JSON".

Catatan

Saat menggunakan Azure CLI untuk menyebarkan templat dengan komentar, gunakan versi 2.3.0 atau versi lebih baru, dan tentukan pengalihan --handle-extended-json-format-nya.

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[parameters('location')]", //defaults to resource group location
  "dependsOn": [ /* storage account and network interface must be deployed first */
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

Di Visual Studio Code, ekstensi Azure Resource Manager Tool dapat mendeteksi templat ARM secara otomatis dan mengubah mode bahasa. Jika Anda melihat Templat Azure Resource Manager di sudut kanan bawah Visual Studio Code, Anda dapat menggunakan komentar sebaris. Komentar sebaris tidak lagi bertanda tidak valid.

Mode templat Azure Resource Manager Visual Studio Code

Pada Bicep, lihat komentar.

Metadata

Anda dapat menambahkan objek metadata hampir di mana saja di templat Anda. Resource Manager mengabaikan objek tersebut, tetapi editor JSON Anda mungkin memperingatkan Anda bahwa properti tersebut tidak valid. Di dalam objek, tentukan properti yang Anda butuhkan.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "comments": "This template was developed for demonstration purposes.",
    "author": "Example Name"
  },

Untuk parameters, tambahkan metadata objek dengan description properti.

"parameters": {
  "adminUsername": {
    "type": "string",
    "metadata": {
      "description": "User name for the Virtual Machine."
    }
  },

Ketika menyebarkan templat melalui portal, teks yang Anda berikan di dalam deskripsi secara otomatis digunakan sebagai tip untuk parameter tersebut.

Tampilkan tip parameter

Untuk resources, tambahkan comments elemen atau metadata objek. Contoh berikut menunjukkan comments elemen dan metadata objek.

"resources": [
  {
    "type": "Microsoft.Storage/storageAccounts",
    "apiVersion": "2018-07-01",
    "name": "[concat('storage', uniqueString(resourceGroup().id))]",
    "comments": "Storage account used to store VM disks",
    "location": "[parameters('location')]",
    "metadata": {
      "comments": "These tags are needed for policy compliance."
    },
    "tags": {
      "Dept": "[parameters('deptName')]",
      "Environment": "[parameters('environment')]"
    },
    "sku": {
      "name": "Standard_LRS"
    },
    "kind": "Storage",
    "properties": {}
  }
]

Untuk outputs, tambahkan metadata objek ke nilai output.

"outputs": {
  "hostname": {
    "type": "string",
    "value": "[reference(variables('publicIPAddressName')).dnsSettings.fqdn]",
    "metadata": {
      "comments": "Return the fully qualified domain name"
    }
  },

Anda tidak dapat menambahkan metadata objek ke fungsi yang ditentukan pengguna.

String multibaris

Anda dapat memecah string menjadi beberapa baris. Misalnya, lihat location properti dan salah satu komentar dalam contoh JSON berikut.

Catatan

Untuk menyebarkan templat dengan string multibaris, gunakan Azure PowerShell atau Azure CLI. Untuk CLI, gunakan versi 2.3.0 atau yang lebih baru, lalu tentukan pengalihan --handle-extended-json-format.

String multibaris tidak didukung saat Anda menyebarkan templat melalui portal Microsoft Azure, alur DevOps, atau REST API.

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[
    parameters('location')
    ]", //defaults to resource group location
  /*
    storage account and network interface
    must be deployed first
  */
  "dependsOn": [
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

Pada Bicep, lihat string multibaris.

Langkah berikutnya