Parameter dalam templat ARM

  • Artikel

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.

Selain minValue, maxValue, minLength, maxLength, dan allowedValues, languageVersion 2.0 memperkenalkan beberapa batasan validasi jenis agregat yang akan digunakan dalam definisi, parameter , dan definisi output . Batasan ini meliputi:

Catatan

Rilis ekstensi Azure Resource Manager Tools saat ini untuk Visual Studio Code tidak mengenali penyempurnaan yang dibuat dalam languageVersion 2.0.

Tip

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

Anda dibatasi hingga 256 parameter dalam templat. Untuk informasi selengkapnya, lihat Batas templat.

Untuk praktik terbaik parameter, 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
  }
}

Batasan objek

Batasan objek hanya diperbolehkan pada objek, dan hanya dapat digunakan dengan languageVersion 2.0.

Properti

Nilai adalah properties peta definisi nama properti =>type.

Contoh berikut akan menerima {"foo": "string", "bar": 1}, tetapi menolak {"foo": "string", "bar": -1}, , {"foo": "", "bar": 1}atau objek apa pun tanpa foo properti atau bar .

"parameters": {
  "objectParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    }
  }
}

Semua properti diperlukan kecuali definisi jenis properti memiliki "nullable": batasan true . Untuk membuat kedua properti dalam contoh sebelumnya opsional, ini akan terlihat seperti:

"parameters": {
  "objectParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3,
        "nullable": true
      },
      "bar": {
        "type": "int",
        "minValue": 0,
        "nullable": true
      }
    }
  }
}

additionalProperties

Nilai adalah additionalPropertiesdefinisi jenis atau nilai boolean. Jika tidak ada additionalProperties batasan yang ditentukan, nilai defaultnya adalah true.

Jika nilai adalah definisi jenis, nilai menjelaskan skema yang diterapkan ke semua properti yang tidak disebutkan dalam properties batasan. Contoh berikut akan menerima {"fizz": "buzz", "foo": "bar"} tetapi menolak {"property": 1}.

"parameters": {
  "dictionaryParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3,
        "nullable": true
      },
      "bar": {
        "type": "int",
        "minValue": 0,
        "nullable": true
      }
    },
    "additionalProperties": {
      "type": "string"
    }
  }
}

Jika nilainya adalah false, tidak ada properti di luar properti yang ditentukan dalam properties batasan yang dapat disediakan. Contoh berikut akan menerima {"foo": "string", "bar": 1}, tetapi menolak {"foo": "string", "bar": 1, "fizz": "buzz"}.

"parameters": {
  "dictionaryParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    },
    "additionalProperties": false
  }
}

Jika nilainya adalah true, properti apa pun yang properties tidak ditentukan dalam batasan menerima nilai apa pun. Contoh berikut akan menerima {"foo": "string", "bar": 1, "fizz": "buzz"}.

"parameters": {
  "dictionaryParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    },
    "additionalProperties": true
  }
}

diskriminator

Nilai discriminator menentukan skema apa yang akan diterapkan berdasarkan properti diskriminator. Contoh berikut akan menerima atau {"type": "ints", "foo": 1, "bar": 2}{"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}, tetapi menolak {"type": "ints", "fizz": "buzz"}.

"parameters": {
  "taggedUnionParameter": {
    "type": "object",
    "discriminator": {
      "propertyName": "type",
      "mapping": {
        "ints": {
          "type": "object",
          "additionalProperties": {"type": "int"}
        },
        "strings": {
          "type": "object",
          "additionalProperties": {"type": "string"}
          }
      }
    }
  }
}

Batasan array

Batasan array hanya diperbolehkan pada array, dan hanya dapat digunakan dengan languageVersion 2.0.

prefixItems

Nilai adalah prefixItems array definisi jenis. Setiap definisi jenis dalam nilai adalah skema yang akan digunakan untuk memvalidasi elemen array pada indeks yang sama. Contoh berikut akan menerima [1, true] tetapi menolak [1, "string"] atau [1]:

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  }
}

item

Nilai adalah itemsdefinisi jenis atau boolean. Jika tidak ada items batasan yang ditentukan, nilai defaultnya adalah true.

Jika nilai adalah definisi jenis, nilai menjelaskan skema yang diterapkan ke semua elemen array yang indeksnya lebih besar dari indeks terbesar batasan prefixItems . Contoh berikut akan menerima [1, true, 1] atau [1, true, 1, 1] tetapi menolak [1, true, "foo"]:

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      { "type": "int" },
      { "type": "bool" }
    ],
    "items": { "type": "int" },
    "defaultValue": [1, true, "foo"]
  }
}

Anda dapat menggunakan items tanpa menggunakan prefixItems. Contoh berikut akan menerima [1, 2] atau [1] tetapi menolak ["foo"]:

"parameters": {
  "intArrayParameter": {
    "type": "array",
    "items": {"type": "int"}
  }
}

Jika nilainya adalah false, array yang divalidasi harus memiliki panjang prefixItems yang sama persis dengan batasan. Contoh berikut akan menerima [1, true], tetapi menolak [1, true, 1], dan [1, true, false, "foo", "bar"].

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ],
    "items": false
  }
}

Jika nilainya benar, elemen array yang indeksnya lebih besar dari indeks terbesar batasan prefixItems menerima nilai apa pun. Contoh berikut akan menerima [1, true], [1, true, 1] dan [1, true, false, "foo", "bar"].

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  }
}

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  },
  "items": true
}

batasan nullable

Batasan nullable hanya dapat digunakan dengan languageVersion 2.0. Ini menunjukkan bahwa nilainya mungkin atau dihilangkan null . Lihat Properti untuk contoh.

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