Parameter dalam templat ARM

Artikel ini menjelaskan cara menentukan dan menggunakan parameter dalam templat Azure Resource Manager (templat ARM). Dengan menyediakan nilai yang berbeda untuk parameter, Anda dapat menggunakan kembali templat untuk lingkungan yang berbeda.

Resource Manager menyelesaikan nilai parameter sebelum memulai operasi penyebaran. Di mana pun parameter digunakan dalam templat, Resource Manager menggantinya dengan nilai yang diselesaikan.

Setiap parameter harus diatur ke salah satu jenis data.

Tip

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

Deklarasi minimal

Minimal, setiap parameter membutuhkan nama dan jenis.

Saat Anda menyebarkan templat melalui portal Microsoft Azure, nama parameter dengan camel case diubah menjadi nama yang dipisahkan spasi. Misalnya, demoString dalam contoh berikut diperlihatkan sebagai Demo String. Untuk informasi selengkapnya, lihat Menggunakan tombol penyebaran untuk menyebarkan templat dari repositori GitHub dan Menyebarkan sumber daya dengan templat ARM dan portal Microsoft Azure.

"parameters": {
  "demoString": {
    "type": "string"
  },
  "demoInt": {
    "type": "int"
  },
  "demoBool": {
    "type": "bool"
  },
  "demoObject": {
    "type": "object"
  },
  "demoArray": {
    "type": "array"
  }
}

Parameter aman

Anda dapat menandai parameter string atau objek sebagai aman. Nilai parameter aman tidak disimpan ke riwayat penyebaran dan tidak dicatat.

"parameters": {
  "demoPassword": {
    "type": "secureString"
  },
  "demoSecretObject": {
    "type": "secureObject"
  }
}

Nilai yang diizinkan

Anda dapat menentukan nilai yang diizinkan untuk parameter. Anda memberikan nilai yang diizinkan dalam array. Penyebaran gagal selama validasi jika nilai diteruskan untuk parameter yang bukan salah satu nilai yang diizinkan.

"parameters": {
  "demoEnum": {
    "type": "string",
    "allowedValues": [
      "one",
      "two"
    ]
  }
}

Nilai default

Anda dapat menentukan nilai default untuk parameter. Nilai default digunakan saat nilai tidak diberikan selama penyebaran.

"parameters": {
  "demoParam": {
    "type": "string",
    "defaultValue": "Contoso"
  }
}

Untuk menentukan nilai default bersama dengan properti lain untuk parameter, gunakan sintaksis berikut.

"parameters": {
  "demoParam": {
    "type": "string",
    "defaultValue": "Contoso",
    "allowedValues": [
      "Contoso",
      "Fabrikam"
    ]
  }
}

Anda dapat menggunakan ekspresi dengan nilai default. Anda tidak dapat menggunakan fungsi referensi atau fungsi daftar apa pun di bagian parameter. Fungsi ini memerlukan status runtime sumber daya, dan tidak dapat dieksekusi sebelum penyebaran ketika parameter diselesaikan.

Ekspresi tidak diperbolehkan dengan properti parameter lainnya.

"parameters": {
  "location": {
    "type": "string",
    "defaultValue": "[resourceGroup().location]"
  }
}

Anda dapat menggunakan nilai parameter lain untuk membangun nilai default. Templat berikut menyusun nama paket host dari nama situs.

"parameters": {
  "siteName": {
    "type": "string",
    "defaultValue": "[concat('site', uniqueString(resourceGroup().id))]"
  },
  "hostingPlanName": {
    "type": "string",
    "defaultValue": "[concat(parameters('siteName'),'-plan')]"
  }
}

Batasan panjang

Anda dapat menentukan panjang minimum dan maksimum untuk parameter string dan array. Anda dapat mengatur salah satu atau kedua batasan. Untuk string, panjangnya menunjukkan jumlah karakter. Untuk array, panjangnya menunjukkan jumlah item dalam array.

Contoh berikut menjelaskan dua parameter. Salah satu parameter adalah untuk nama akun penyimpanan yang harus memiliki 3-24 karakter. Parameter lainnya adalah array yang harus memiliki dari 1-5 item.

"parameters": {
  "storageAccountName": {
    "type": "string",
    "minLength": 3,
    "maxLength": 24
  },
  "appNames": {
    "type": "array",
    "minLength": 1,
    "maxLength": 5
  }
}

Batasan bilangan bulat

Anda dapat mengatur nilai minimum dan maksimum untuk parameter bilangan bulat. Anda dapat mengatur salah satu atau kedua batasan.

"parameters": {
  "month": {
    "type": "int",
    "minValue": 1,
    "maxValue": 12
  }
}

Deskripsi

Anda dapat menambahkan deskripsi ke parameter untuk membantu pengguna templat Anda memahami nilai yang akan diberikan. Saat menyebarkan templat melalui portal, teks yang Anda berikan dalam deskripsi secara otomatis digunakan sebagai tip untuk parameter tersebut. Hanya tambahkan deskripsi ketika teks memberikan lebih banyak informasi daripada yang dapat disimpulkan dari nama parameter.

"parameters": {
  "virtualMachineSize": {
    "type": "string",
    "metadata": {
      "description": "Must be at least Standard_A3 to support 2 NICs."
    },
    "defaultValue": "Standard_DS1_v2"
  }
}

Menggunakan parameter

Untuk mereferensikan nilai parameter, gunakan fungsi parameter. Contoh berikut menggunakan nilai parameter untuk nama brankas kunci.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "vaultName": {
      "type": "string",
      "defaultValue": "[format('keyVault{0}', uniqueString(resourceGroup().id))]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.KeyVault/vaults",
      "apiVersion": "2021-06-01-preview",
      "name": "[parameters('vaultName')]",
      ...
    }
  ]
}

Objek sebagai parameter

Anda dapat mengatur nilai terkait dengan meneruskannya sebagai objek. Pendekatan ini juga mengurangi jumlah parameter dalam templat.

Contoh berikut menunjukkan parameter yang merupakan objek. Nilai default menunjukkan properti yang diharapkan untuk objek. Properti tersebut digunakan saat menentukan sumber daya untuk disebarkan.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "vNetSettings": {
      "type": "object",
      "defaultValue": {
        "name": "VNet1",
        "location": "eastus",
        "addressPrefixes": [
          {
            "name": "firstPrefix",
            "addressPrefix": "10.0.0.0/22"
          }
        ],
        "subnets": [
          {
            "name": "firstSubnet",
            "addressPrefix": "10.0.0.0/24"
          },
          {
            "name": "secondSubnet",
            "addressPrefix": "10.0.1.0/24"
          }
        ]
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.Network/virtualNetworks",
      "apiVersion": "2021-02-01",
      "name": "[parameters('vNetSettings').name]",
      "location": "[parameters('vNetSettings').location]",
      "properties": {
        "addressSpace": {
          "addressPrefixes": [
            "[parameters('vNetSettings').addressPrefixes[0].addressPrefix]"
          ]
        },
        "subnets": [
          {
            "name": "[parameters('vNetSettings').subnets[0].name]",
            "properties": {
              "addressPrefix": "[parameters('vNetSettings').subnets[0].addressPrefix]"
            }
          },
          {
            "name": "[parameters('vNetSettings').subnets[1].name]",
            "properties": {
              "addressPrefix": "[parameters('vNetSettings').subnets[1].addressPrefix]"
            }
          }
        ]
      }
    }
  ]
}

Contoh templat

Contoh berikut menunjukkan skenario untuk menggunakan parameter.

Templat Deskripsi
parameter dengan fungsi untuk nilai default Menunjukkan cara menggunakan fungsi templat saat menentukan nilai default untuk parameter. Templat tidak menyebarkan sumber daya apa pun. Templat membangun nilai parameter dan mengembalikan nilai-nilai tersebut.
objek parameter Menunjukkan menggunakan objek untuk parameter. Templat tidak menyebarkan sumber daya apa pun. Templat membangun nilai parameter dan mengembalikan nilai-nilai tersebut.

Langkah berikutnya