Parametry w szablonach usługi ARM
W tym artykule opisano sposób definiowania i używania parametrów w szablonie usługi Azure Resource Manager (szablon usługi ARM). Podając różne wartości parametrów, można ponownie użyć szablonu dla różnych środowisk.
Usługa Resource Manager rozwiązuje wartości parametrów przed rozpoczęciem operacji wdrażania. Wszędzie tam, gdzie parametr jest używany w szablonie, usługa Resource Manager zastępuje go rozpoznaną wartością.
Każdy parametr musi być ustawiony na jeden z typów danych.
Oprócz parametrów minValue, maxValue, minLength, maxLength i allowedValues, languageVersion 2.0 wprowadza pewne ograniczenia weryfikacji typu agregacji, które mają być używane w definicjach, parametrach i danych wyjściowych. Te ograniczenia obejmują:
Uwaga
Bieżąca wersja rozszerzenia Narzędzi usługi Azure Resource Manager dla programu Visual Studio Code nie rozpoznaje ulepszeń w wersji languageVersion 2.0.
Napiwek
Zalecamy Bicep , ponieważ oferuje te same możliwości co szablony usługi ARM, a składnia jest łatwiejsza w użyciu. Aby dowiedzieć się więcej, zobacz parametry.
W szablonie można umieścić maksymalnie 256 parametrów. Aby uzyskać więcej informacji, zobacz Limity szablonów.
Aby uzyskać najlepsze rozwiązania dotyczące parametrów, zobacz Parametry.
Minimalna deklaracja
Co najmniej każdy parametr wymaga nazwy i typu.
Podczas wdrażania szablonu za pośrednictwem witryny Azure Portal nazwy parametrów wielbłądowych są zamieniane w nazwy rozdzielane spacjami. Na przykład demoString w poniższym przykładzie jest wyświetlany jako Ciąg demonstracyjny. Aby uzyskać więcej informacji, zobacz Używanie przycisku wdrażania do wdrażania szablonów z repozytorium GitHub i Wdrażanie zasobów przy użyciu szablonów usługi ARM i witryny Azure Portal.
"parameters": {
"demoString": {
"type": "string"
},
"demoInt": {
"type": "int"
},
"demoBool": {
"type": "bool"
},
"demoObject": {
"type": "object"
},
"demoArray": {
"type": "array"
}
}
Parametry zabezpieczeń
Parametry ciągu lub obiektu można oznaczyć jako bezpieczne. Wartość bezpiecznego parametru nie jest zapisywana w historii wdrażania i nie jest rejestrowana.
"parameters": {
"demoPassword": {
"type": "secureString"
},
"demoSecretObject": {
"type": "secureObject"
}
}
Dozwolone wartości
Dozwolone wartości parametru można zdefiniować. Dozwolone wartości są podane w tablicy. Wdrożenie kończy się niepowodzeniem podczas walidacji, jeśli wartość jest przekazywana dla parametru, który nie jest jedną z dozwolonych wartości.
"parameters": {
"demoEnum": {
"type": "string",
"allowedValues": [
"one",
"two"
]
}
}
Domyślna wartość
Możesz określić wartość domyślną parametru. Wartość domyślna jest używana, gdy wartość nie jest udostępniana podczas wdrażania.
"parameters": {
"demoParam": {
"type": "string",
"defaultValue": "Contoso"
}
}
Aby określić wartość domyślną wraz z innymi właściwościami parametru, użyj następującej składni.
"parameters": {
"demoParam": {
"type": "string",
"defaultValue": "Contoso",
"allowedValues": [
"Contoso",
"Fabrikam"
]
}
}
Możesz użyć wyrażeń z wartością domyślną. Nie można użyć funkcji referencyjnej ani żadnej funkcji listy w sekcji parameters. Te funkcje pobierają stan środowiska uruchomieniowego zasobu i nie można ich wykonać przed wdrożeniem po rozpoznaniu parametrów.
Wyrażenia nie są dozwolone z innymi właściwościami parametrów.
"parameters": {
"location": {
"type": "string",
"defaultValue": "[resourceGroup().location]"
}
}
Możesz użyć innej wartości parametru, aby utworzyć wartość domyślną. Poniższy szablon tworzy nazwę planu hosta z nazwy witryny.
"parameters": {
"siteName": {
"type": "string",
"defaultValue": "[concat('site', uniqueString(resourceGroup().id))]"
},
"hostingPlanName": {
"type": "string",
"defaultValue": "[concat(parameters('siteName'),'-plan')]"
}
}
Nie można jednak odwołać się do zmiennej jako wartości domyślnej.
Ograniczenia długości
Można określić minimalną i maksymalną długość parametrów ciągu i tablicy. Można ustawić jedno lub oba ograniczenia. W przypadku ciągów długość wskazuje liczbę znaków. W przypadku tablic długość wskazuje liczbę elementów w tablicy.
Poniższy przykład deklaruje dwa parametry. Jednym z parametrów jest nazwa konta magazynu, która musi mieć od 3 do 24 znaków. Drugi parametr jest tablicą, która musi zawierać od 1 do 5 elementów.
"parameters": {
"storageAccountName": {
"type": "string",
"minLength": 3,
"maxLength": 24
},
"appNames": {
"type": "array",
"minLength": 1,
"maxLength": 5
}
}
Ograniczenia liczb całkowitych
Można ustawić wartości minimalne i maksymalne dla parametrów liczb całkowitych. Można ustawić jedno lub oba ograniczenia.
"parameters": {
"month": {
"type": "int",
"minValue": 1,
"maxValue": 12
}
}
Ograniczenia obiektu
Ograniczenia obiektów są dozwolone tylko dla obiektów i mogą być używane tylko z languageVersion 2.0.
Właściwości
Wartość properties
to mapa nazwy właściwości =>definicja typu.
Poniższy przykład akceptuje {"foo": "string", "bar": 1}
element , ale odrzuca {"foo": "string", "bar": -1}
obiekt , {"foo": "", "bar": 1}
lub dowolny obiekt bez foo
właściwości lub bar
.
"parameters": {
"objectParameter": {
"type": "object",
"properties": {
"foo": {
"type": "string",
"minLength": 3
},
"bar": {
"type": "int",
"minValue": 0
}
}
}
}
Wszystkie właściwości są wymagane, chyba że definicja typu właściwości ma wartość "nullable": ograniczenie true. Aby ustawić obie właściwości w poprzednim przykładzie jako opcjonalne, wyglądałoby to następująco:
"parameters": {
"objectParameter": {
"type": "object",
"properties": {
"foo": {
"type": "string",
"minLength": 3,
"nullable": true
},
"bar": {
"type": "int",
"minValue": 0,
"nullable": true
}
}
}
}
additionalProperties
Wartość additionalProperties
jest definicją typu lub wartością logiczną. Jeśli nie additionalProperties
zdefiniowano żadnego ograniczenia, wartość domyślna to true
.
Jeśli wartość jest definicją typu, wartość opisuje schemat, który jest stosowany do wszystkich właściwości, które nie zostały wymienione w ograniczeniu properties
. Poniższy przykład akceptuje {"fizz": "buzz", "foo": "bar"}
, ale odrzuca {"property": 1}
element .
"parameters": {
"dictionaryParameter": {
"type": "object",
"properties": {
"foo": {
"type": "string",
"minLength": 3,
"nullable": true
},
"bar": {
"type": "int",
"minValue": 0,
"nullable": true
}
},
"additionalProperties": {
"type": "string"
}
}
}
Jeśli wartość to false
, nie można podać żadnych właściwości poza tymi zdefiniowanymi w ograniczeniu properties
. W poniższym przykładzie zostanie zaakceptowana {"foo": "string", "bar": 1}
wartość , ale odrzucisz {"foo": "string", "bar": 1, "fizz": "buzz"}
.
"parameters": {
"dictionaryParameter": {
"type": "object",
"properties": {
"foo": {
"type": "string",
"minLength": 3
},
"bar": {
"type": "int",
"minValue": 0
}
},
"additionalProperties": false
}
}
Jeśli wartość to true
, każda właściwość nie zdefiniowana w ograniczeniu properties
akceptuje dowolną wartość. Poniższy przykład będzie akceptował {"foo": "string", "bar": 1, "fizz": "buzz"}
element .
"parameters": {
"dictionaryParameter": {
"type": "object",
"properties": {
"foo": {
"type": "string",
"minLength": 3
},
"bar": {
"type": "int",
"minValue": 0
}
},
"additionalProperties": true
}
}
Rozróżniacza
Wartość discriminator
definiuje schemat, który ma być stosowany na podstawie właściwości dyskryminującej. W poniższym przykładzie zostanie zaakceptowana wartość {"type": "ints", "foo": 1, "bar": 2}
lub {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}
, ale odrzucisz {"type": "ints", "fizz": "buzz"}
element .
"parameters": {
"taggedUnionParameter": {
"type": "object",
"discriminator": {
"propertyName": "type",
"mapping": {
"ints": {
"type": "object",
"additionalProperties": {"type": "int"}
},
"strings": {
"type": "object",
"additionalProperties": {"type": "string"}
}
}
}
}
}
Ograniczenia tablicy
Ograniczenia tablic są dozwolone tylko w tablicach i mogą być używane tylko z languageVersion 2.0.
prefiksItems
Wartość prefixItems
to tablica definicji typów. Każda definicja typu w wartości jest schematem używanym do sprawdzania poprawności elementu tablicy w tym samym indeksie. Poniższy przykład akceptuje [1, true]
, ale odrzuca [1, "string"]
lub [1]
:
"parameters": {
"tupleParameter": {
"type": "array",
"prefixItems": [
{"type": "int"},
{"type": "bool"}
]
}
}
elementy
Wartość items
jest definicją typu lub wartością logiczną. Jeśli nie items
zdefiniowano żadnego ograniczenia, wartość domyślna to true
.
Jeśli wartość jest definicją typu, wartość opisuje schemat stosowany do wszystkich elementów tablicy, których indeks jest większy niż największy indeks prefixItems
ograniczenia. W poniższym przykładzie zostanie zaakceptowana [1, true, 1]
lub [1, true, 1, 1]
odrzucona:[1, true, "foo"]
"parameters": {
"tupleParameter": {
"type": "array",
"prefixItems": [
{ "type": "int" },
{ "type": "bool" }
],
"items": { "type": "int" },
"defaultValue": [1, true, "foo"]
}
}
Można użyć items
bez użycia polecenia prefixItems
. W poniższym przykładzie zostanie zaakceptowana [1, 2]
lub [1]
odrzucona:["foo"]
"parameters": {
"intArrayParameter": {
"type": "array",
"items": {"type": "int"}
}
}
Jeśli wartość to false
, zweryfikowana tablica musi być dokładnie taką samą długością jak prefixItems
ograniczenie. W poniższym przykładzie zostanie zaakceptowana [1, true]
wartość , ale odrzucona [1, true, 1]
wartość i [1, true, false, "foo", "bar"]
.
"parameters": {
"tupleParameter": {
"type": "array",
"prefixItems": [
{"type": "int"},
{"type": "bool"}
],
"items": false
}
}
Jeśli wartość ma wartość true, elementy tablicy, których indeks jest większy niż największy indeks prefixItems
ograniczenia, akceptują dowolną wartość. Poniższe przykłady akceptują [1, true]
wartości i [1, true, 1]
[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
}
ograniczenie dopuszczane do wartości null
Ograniczenie dopuszczane do wartości null może być używane tylko z languageVersion 2.0. Wskazuje, że wartość może być null
pominięta lub pominięta. Zobacz Właściwości , aby zapoznać się z przykładem.
opis
Możesz dodać opis do parametru, aby ułatwić użytkownikom szablonu zrozumienie wartości, którą należy podać. Podczas wdrażania szablonu za pośrednictwem portalu tekst w opisie jest automatycznie używany jako porada dla tego parametru. Dodaj opis tylko wtedy, gdy tekst zawiera więcej informacji niż można wywnioskować z nazwy parametru.
"parameters": {
"virtualMachineSize": {
"type": "string",
"metadata": {
"description": "Must be at least Standard_A3 to support 2 NICs."
},
"defaultValue": "Standard_DS1_v2"
}
}
Użyj parametru
Aby odwołać się do wartości parametru , użyj funkcji parameters . W poniższym przykładzie użyto wartości parametru dla nazwy magazynu kluczy.
{
"$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')]",
...
}
]
}
Obiekty jako parametry
Powiązane wartości można organizować, przekazując je jako obiekt. Takie podejście zmniejsza również liczbę parametrów w szablonie.
W poniższym przykładzie przedstawiono parametr, który jest obiektem. Wartość domyślna zawiera oczekiwane właściwości obiektu. Te właściwości są używane podczas definiowania zasobu do wdrożenia.
{
"$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]"
}
}
]
}
}
]
}
Przykładowe szablony
W poniższych przykładach przedstawiono scenariusze używania parametrów.
Szablon | opis |
---|---|
parametry z funkcjami dla wartości domyślnych | Pokazuje, jak używać funkcji szablonu podczas definiowania wartości domyślnych parametrów. Szablon nie wdraża żadnych zasobów. Tworzy wartości parametrów i zwraca te wartości. |
obiekt parametru | Demonstruje użycie obiektu dla parametru. Szablon nie wdraża żadnych zasobów. Tworzy wartości parametrów i zwraca te wartości. |
Następne kroki
- Aby dowiedzieć się więcej o dostępnych właściwościach parametrów, zobacz Omówienie struktury i składni szablonów usługi ARM.
- Aby dowiedzieć się więcej o przekazywaniu wartości parametrów jako pliku, zobacz Create Resource Manager parameter file (Tworzenie pliku parametrów usługi Resource Manager).
- Aby uzyskać zalecenia dotyczące tworzenia parametrów, zobacz Najlepsze rozwiązania — parametry.