Parametry v šablonách ARM
Tento článek popisuje, jak definovat a používat parametry v šabloně Azure Resource Manager (šablona ARM). Zadáním různých hodnot parametrů můžete šablonu znovu použít pro různá prostředí.
Resource Manager před spuštěním operací nasazení přeloží hodnoty parametrů. Bez ohledu na to, kde se v šabloně použije parametr, Resource Manager ho nahradí přeloženou hodnotou.
Každý parametr musí být nastavený na jeden z datových typů.
Kromě minValue, maxValue, minLength, maxLength a allowedValues zavádí languageVersion 2.0 některá omezení ověřování agregovaného typu, která se mají použít v definicích, parametrech a definicích výstupů. Mezi tato omezení patří:
Poznámka
Aktuální verze rozšíření Azure Resource Manager Tools pro Visual Studio Code nerozpoznává vylepšení vytvořená v languageVersion 2.0.
Tip
Doporučujeme Bicep , protože nabízí stejné funkce jako šablony ARM a syntaxe se snadněji používá. Další informace najdete v tématu parametry.
V šabloně jste omezeni na 256 parametrů. Další informace najdete v tématu Limity šablon.
Osvědčené postupy pro parametry najdete v tématu Parametry.
Minimální deklarace
Minimálně každý parametr potřebuje název a typ.
Když nasadíte šablonu prostřednictvím Azure Portal, názvy parametrů s velbloudy a písmeny se změní na názvy oddělené mezerami. Například demoString v následujícím příkladu je zobrazen jako Ukázkový řetězec. Další informace najdete v tématech Použití tlačítka nasazení k nasazení šablon z úložiště GitHub a Nasazení prostředků pomocí šablon ARM a Azure Portal.
"parameters": {
"demoString": {
"type": "string"
},
"demoInt": {
"type": "int"
},
"demoBool": {
"type": "bool"
},
"demoObject": {
"type": "object"
},
"demoArray": {
"type": "array"
}
}
Zabezpečené parametry
Parametry řetězce nebo objektu můžete označit jako zabezpečené. Hodnota zabezpečeného parametru se neuloží do historie nasazení a nezaprotokoluje se.
"parameters": {
"demoPassword": {
"type": "secureString"
},
"demoSecretObject": {
"type": "secureObject"
}
}
Povolené hodnoty
Pro parametr můžete definovat povolené hodnoty. V poli zadáte povolené hodnoty. Nasazení se během ověřování nezdaří, pokud je předána hodnota parametru, který není jednou z povolených hodnot.
"parameters": {
"demoEnum": {
"type": "string",
"allowedValues": [
"one",
"two"
]
}
}
Výchozí hodnota
Pro parametr můžete zadat výchozí hodnotu. Výchozí hodnota se použije, když se během nasazení nezadá hodnota.
"parameters": {
"demoParam": {
"type": "string",
"defaultValue": "Contoso"
}
}
Pokud chcete zadat výchozí hodnotu spolu s dalšími vlastnostmi parametru, použijte následující syntaxi.
"parameters": {
"demoParam": {
"type": "string",
"defaultValue": "Contoso",
"allowedValues": [
"Contoso",
"Fabrikam"
]
}
}
Můžete použít výrazy s výchozí hodnotou. V oddílu parametrů nemůžete použít referenční funkci ani žádnou ze seznamu funkcí. Tyto funkce získají stav modulu runtime prostředku a nelze je spustit před nasazením, když se parametry přeloží.
Výrazy nejsou povoleny s jinými vlastnostmi parametrů.
"parameters": {
"location": {
"type": "string",
"defaultValue": "[resourceGroup().location]"
}
}
K vytvoření výchozí hodnoty můžete použít jinou hodnotu parametru. Následující šablona vytvoří název plánu hostitele z názvu webu.
"parameters": {
"siteName": {
"type": "string",
"defaultValue": "[concat('site', uniqueString(resourceGroup().id))]"
},
"hostingPlanName": {
"type": "string",
"defaultValue": "[concat(parameters('siteName'),'-plan')]"
}
}
Omezení délky
Pro parametry řetězce a pole můžete zadat minimální a maximální délku. Můžete nastavit jedno nebo obě omezení. U řetězců délka označuje počet znaků. U polí určuje délka počet položek v poli.
Následující příklad deklaruje dva parametry. Jeden parametr je pro název účtu úložiště, který musí mít 3 až 24 znaků. Druhý parametr je pole, které musí obsahovat 1 až 5 položek.
"parameters": {
"storageAccountName": {
"type": "string",
"minLength": 3,
"maxLength": 24
},
"appNames": {
"type": "array",
"minLength": 1,
"maxLength": 5
}
}
Omezení celého čísla
Můžete nastavit minimální a maximální hodnoty pro celočíselné parametry. Můžete nastavit jedno nebo obě omezení.
"parameters": {
"month": {
"type": "int",
"minValue": 1,
"maxValue": 12
}
}
Omezení objektu
Omezení objektu jsou povolena pouze u objektů a lze je použít pouze s languageVersion 2.0.
Vlastnosti
Hodnota properties
je mapa názvu vlastnosti =>definice typu.
Následující příklad by přijal {"foo": "string", "bar": 1}
, ale odmítl {"foo": "string", "bar": -1}
, {"foo": "", "bar": 1}
nebo jakýkoli objekt bez foo
vlastnosti nebo bar
.
"parameters": {
"objectParameter": {
"type": "object",
"properties": {
"foo": {
"type": "string",
"minLength": 3
},
"bar": {
"type": "int",
"minValue": 0
}
}
}
}
Všechny vlastnosti jsou povinné, pokud definice typu vlastnosti nemá hodnotu nullable: true constraint. Aby byly obě vlastnosti v předchozím příkladu volitelné, vypadaly by takto:
"parameters": {
"objectParameter": {
"type": "object",
"properties": {
"foo": {
"type": "string",
"minLength": 3,
"nullable": true
},
"bar": {
"type": "int",
"minValue": 0,
"nullable": true
}
}
}
}
další Vlastnosti
Hodnota additionalProperties
je definice typu nebo logická hodnota. Pokud není definováno žádné additionalProperties
omezení, výchozí hodnota je true
.
Pokud je hodnota definicí typu, tato hodnota popisuje schéma, které se použije u všech vlastností, které nejsou uvedené v properties
omezení. Následující příklad by přijal, {"fizz": "buzz", "foo": "bar"}
ale odmítl {"property": 1}
.
"parameters": {
"dictionaryParameter": {
"type": "object",
"properties": {
"foo": {
"type": "string",
"minLength": 3,
"nullable": true
},
"bar": {
"type": "int",
"minValue": 0,
"nullable": true
}
},
"additionalProperties": {
"type": "string"
}
}
}
Pokud je false
hodnota , nesmí být zadány žádné vlastnosti nad rámec těch, které jsou definovány properties
v omezení. Následující příklad by přijal {"foo": "string", "bar": 1}
, ale odmítl {"foo": "string", "bar": 1, "fizz": "buzz"}
.
"parameters": {
"dictionaryParameter": {
"type": "object",
"properties": {
"foo": {
"type": "string",
"minLength": 3
},
"bar": {
"type": "int",
"minValue": 0
}
},
"additionalProperties": false
}
}
Pokud je true
hodnota , jakákoli vlastnost, která není definována properties
v omezení, přijímá jakoukoli hodnotu. Následující příklad by přijal {"foo": "string", "bar": 1, "fizz": "buzz"}
.
"parameters": {
"dictionaryParameter": {
"type": "object",
"properties": {
"foo": {
"type": "string",
"minLength": 3
},
"bar": {
"type": "int",
"minValue": 0
}
},
"additionalProperties": true
}
}
Diskriminátor
Hodnota discriminator
definuje, jaké schéma se má použít na základě diskriminující vlastnosti. Následující příklad by přijal buď {"type": "ints", "foo": 1, "bar": 2}
nebo , {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}
ale odmítl {"type": "ints", "fizz": "buzz"}
.
"parameters": {
"taggedUnionParameter": {
"type": "object",
"discriminator": {
"propertyName": "type",
"mapping": {
"ints": {
"type": "object",
"additionalProperties": {"type": "int"}
},
"strings": {
"type": "object",
"additionalProperties": {"type": "string"}
}
}
}
}
}
Omezení pole
Omezení pole jsou povolena pouze u polí a lze je použít pouze s languageVersion 2.0.
prefixItems
Hodnota je prefixItems
pole definic typů. Každá definice typu v hodnotě je schéma, které se má použít k ověření prvku pole ve stejném indexu. Následující příklad by přijal, [1, true]
ale odmítl [1, "string"]
nebo [1]
:
"parameters": {
"tupleParameter": {
"type": "array",
"prefixItems": [
{"type": "int"},
{"type": "bool"}
]
}
}
položky
Hodnota items
je definice typu nebo logická hodnota. Pokud není definováno žádné items
omezení, výchozí hodnota je true
.
Pokud je hodnota definice typu, tato hodnota popisuje schéma, které se použije na všechny prvky pole, jejichž index je větší než největší index prefixItems
omezení. Následující příklad by přijal [1, true, 1]
nebo [1, true, 1, 1]
odmítl [1, true, "foo"]
:
"parameters": {
"tupleParameter": {
"type": "array",
"prefixItems": [
{ "type": "int" },
{ "type": "bool" }
],
"items": { "type": "int" },
"defaultValue": [1, true, "foo"]
}
}
Můžete použít items
bez použití prefixItems
. Následující příklad by přijal [1, 2]
nebo [1]
odmítl ["foo"]
:
"parameters": {
"intArrayParameter": {
"type": "array",
"items": {"type": "int"}
}
}
Pokud je false
hodnota , musí být ověřená matice přesně stejná jako prefixItems
omezení. Následující příklad by přijal [1, true]
, ale odmítl [1, true, 1]
a [1, true, false, "foo", "bar"]
.
"parameters": {
"tupleParameter": {
"type": "array",
"prefixItems": [
{"type": "int"},
{"type": "bool"}
],
"items": false
}
}
Pokud je hodnota true, prvky pole, jejichž index je větší než největší index omezení, přijímají libovolnou prefixItems
hodnotu. Následující příklady by akceptovaly [1, true]
, [1, true, 1]
a [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
}
Omezení s možnou hodnotou null
Omezení s možnou hodnotou null lze použít pouze s languageVersion 2.0. Označuje, že hodnota může být null
nebo vynechána. Příklad najdete v tématu Vlastnosti .
Description
K parametru můžete přidat popis, který uživatelům šablony pomůže pochopit hodnotu, kterou mají poskytnout. Při nasazování šablony prostřednictvím portálu se text, který zadáte v popisu, automaticky použije jako tip pro daný parametr. Popis přidejte pouze v případech, kdy text obsahuje více informací, než je možné odvodit z názvu parametru.
"parameters": {
"virtualMachineSize": {
"type": "string",
"metadata": {
"description": "Must be at least Standard_A3 to support 2 NICs."
},
"defaultValue": "Standard_DS1_v2"
}
}
Použití parametru
Pokud chcete odkazovat na hodnotu parametru, použijte funkci parameters . Následující příklad používá hodnotu parametru pro název trezoru klíčů.
{
"$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')]",
...
}
]
}
Objekty jako parametry
Související hodnoty můžete uspořádat tak, že je předáte jako objekt. Tento přístup také snižuje počet parametrů v šabloně.
Následující příklad ukazuje parametr, který je objektem. Výchozí hodnota zobrazuje očekávané vlastnosti objektu. Tyto vlastnosti se používají při definování prostředku, který se má nasadit.
{
"$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]"
}
}
]
}
}
]
}
Ukázkové šablony
Následující příklady ukazují scénáře použití parametrů.
Template (Šablona) | Description |
---|---|
parametry s funkcemi pro výchozí hodnoty | Ukazuje, jak používat funkce šablony při definování výchozích hodnot pro parametry. Šablona nenasadí žádné prostředky. Vytvoří hodnoty parametrů a vrátí tyto hodnoty. |
parameter – objekt | Ukazuje použití objektu pro parametr. Šablona nenasadí žádné prostředky. Vytvoří hodnoty parametrů a vrátí tyto hodnoty. |
Další kroky
- Informace o dostupných vlastnostech parametrů najdete v tématu Vysvětlení struktury a syntaxe šablon ARM.
- Informace o předávání hodnot parametrů jako souboru najdete v tématu Vytvoření souboru parametrů Resource Manager.
- Doporučení k vytváření parametrů najdete v tématu Osvědčené postupy – parametry.