Paramètres dans les modèles ARM
Cet article explique comment définir et utiliser des paramètres dans un modèle Azure Resource Manager (ARM). En fournissant des valeurs différentes pour les paramètres, vous pouvez réutiliser un modèle pour différents environnements.
Resource Manager résout les valeurs des paramètres avant de démarrer les opérations de déploiement. Chaque fois que le paramètre est utilisé dans le modèle, Resource Manager le remplace par la valeur résolue.
Chaque paramètre doit être défini sur l’un des types de données.
Outre minValue, maxValue, minLength, maxLength et allowedValues, languageVersion 2.0 introduit certaines contraintes de validation du type d’agrégation à utiliser dans les définitions, les paramètres et les définitions des sorties. Ces contraintes comprennent :
Notes
La version actuelle de l’extension Azure Resource Manager Tools pour Visual Studio Code ne reconnaît pas les améliorations apportées à languageVersion 2.0.
Conseil
Nous recommandons Bicep parce qu’il offre les mêmes fonctionnalités que les modèles ARM et que la syntaxe est plus facile d’utilisation. Pour en savoir plus, consultez Paramètres.
Vous êtes limité à 256 paramètres dans un modèle. Pour plus d’informations, consultez Limites du modèle.
Pour connaître les meilleures pratiques relatives aux paramètres, consultez Paramètres.
Au minimum, chaque paramètre a besoin d’un nom et d’un type.
Lorsque vous déployez un modèle via le portail Azure, les noms de paramètres en casse mixte sont convertis en noms séparés par des espaces. Par exemple, demoString dans l’exemple suivant est représenté sous la forme Demo String. Pour plus d’informations, consultez Utiliser un bouton de déploiement pour déployer des modèles à partir du référentiel GitHub et Déployer des ressources avec des modèles ARM et le portail Azure.
"parameters": {
"demoString": {
"type": "string"
},
"demoInt": {
"type": "int"
},
"demoBool": {
"type": "bool"
},
"demoObject": {
"type": "object"
},
"demoArray": {
"type": "array"
}
}
Vous pouvez marquer les paramètres de chaîne ou d’objet comme sécurisés. La valeur d’un paramètre sécurisé n’est pas enregistrée dans l’historique de déploiement et n’est pas journalisée.
"parameters": {
"demoPassword": {
"type": "secureString"
},
"demoSecretObject": {
"type": "secureObject"
}
}
Vous pouvez définir des valeurs autorisées pour un paramètre. Vous fournissez les valeurs autorisées dans un tableau. Le déploiement échoue pendant la validation si une valeur transmise pour le paramètre n’est pas l’une des valeurs autorisées.
"parameters": {
"demoEnum": {
"type": "string",
"allowedValues": [
"one",
"two"
]
}
}
Vous pouvez spécifier une valeur par défaut pour un paramètre. La valeur par défaut est utilisée quand aucune valeur n’est fournie pendant le déploiement.
"parameters": {
"demoParam": {
"type": "string",
"defaultValue": "Contoso"
}
}
Pour spécifier une valeur par défaut ainsi que d’autres propriétés pour le paramètre, utilisez la syntaxe suivante.
"parameters": {
"demoParam": {
"type": "string",
"defaultValue": "Contoso",
"allowedValues": [
"Contoso",
"Fabrikam"
]
}
}
Vous pouvez utiliser des expressions avec la valeur par défaut. Vous ne pouvez pas utiliser la fonction reference ni aucune des fonctions list dans la section parameters. Ces fonctions obtiennent l’état d’exécution d’une ressource et ne peuvent pas être exécutées avant le déploiement quand des paramètres sont résolus.
Les expressions ne sont pas autorisées avec d’autres propriétés de paramètre.
"parameters": {
"location": {
"type": "string",
"defaultValue": "[resourceGroup().location]"
}
}
Vous pouvez utiliser une autre valeur de paramètre pour générer une valeur par défaut. Le modèle suivant construit un nom de plan d’hôte à partir du nom de site.
"parameters": {
"siteName": {
"type": "string",
"defaultValue": "[concat('site', uniqueString(resourceGroup().id))]"
},
"hostingPlanName": {
"type": "string",
"defaultValue": "[concat(parameters('siteName'),'-plan')]"
}
}
Toutefois, vous ne pouvez pas référencer une variable comme valeur par défaut.
Vous pouvez spécifier des longueurs minimale et maximale pour les paramètres de chaîne et de tableau. Vous pouvez définir une contrainte ou les deux. Pour les chaînes, la longueur indique le nombre de caractères. Pour les tableaux, la longueur indique le nombre d’éléments dans le tableau.
L’exemple suivant déclare deux paramètres. Un paramètre est destiné à un nom de compte de stockage qui doit compter entre 3 et 24 caractères. L’autre paramètre est un tableau qui doit compter entre 1 et 5.
"parameters": {
"storageAccountName": {
"type": "string",
"minLength": 3,
"maxLength": 24
},
"appNames": {
"type": "array",
"minLength": 1,
"maxLength": 5
}
}
Vous pouvez définir des valeurs minimales et maximales pour les paramètres de type entier. Vous pouvez définir une contrainte ou les deux.
"parameters": {
"month": {
"type": "int",
"minValue": 1,
"maxValue": 12
}
}
Les contraintes d’objet sont uniquement autorisées sur les objets et ne peuvent être utilisées qu’avec languageVersion 2.0.
La valeur de properties
est une carte de la propriété name =>type definition.
L’exemple suivant accepte {"foo": "string", "bar": 1}
, mais rejette {"foo": "string", "bar": -1}
, {"foo": "", "bar": 1}
ou tout objet sans propriété foo
ou bar
.
"parameters": {
"objectParameter": {
"type": "object",
"properties": {
"foo": {
"type": "string",
"minLength": 3
},
"bar": {
"type": "int",
"minValue": 0
}
}
}
}
Toutes les propriétés sont requises, sauf si la définition de type de la propriété a la contrainte « pouvant accepter la valeur Null » : vrai. Pour rendre les deux propriétés de l’exemple précédent facultatives, cela se présente ainsi :
"parameters": {
"objectParameter": {
"type": "object",
"properties": {
"foo": {
"type": "string",
"minLength": 3,
"nullable": true
},
"bar": {
"type": "int",
"minValue": 0,
"nullable": true
}
}
}
}
La valeur de additionalProperties
est une définition de type ou une valeur booléenne. Si aucune contrainte additionalProperties
n’est définie, la valeur par défaut est true
.
Si la valeur est une définition de type, la valeur décrit le schéma appliqué à toutes les propriétés non mentionnées dans la contrainte properties
. L’exemple suivant accepte {"fizz": "buzz", "foo": "bar"}
mais rejette {"property": 1}
.
"parameters": {
"dictionaryParameter": {
"type": "object",
"properties": {
"foo": {
"type": "string",
"minLength": 3,
"nullable": true
},
"bar": {
"type": "int",
"minValue": 0,
"nullable": true
}
},
"additionalProperties": {
"type": "string"
}
}
}
Si la valeur est false
, aucune propriété au-delà de celles définies dans la contrainte properties
ne peut être fournie. L’exemple suivant accepte {"foo": "string", "bar": 1}
mais rejette {"foo": "string", "bar": 1, "fizz": "buzz"}
.
"parameters": {
"dictionaryParameter": {
"type": "object",
"properties": {
"foo": {
"type": "string",
"minLength": 3
},
"bar": {
"type": "int",
"minValue": 0
}
},
"additionalProperties": false
}
}
Si la valeur est true
, toute propriété non définie dans la contrainte properties
accepte n'importe quelle valeur. L’exemple suivant accepte {"foo": "string", "bar": 1, "fizz": "buzz"}
.
"parameters": {
"dictionaryParameter": {
"type": "object",
"properties": {
"foo": {
"type": "string",
"minLength": 3
},
"bar": {
"type": "int",
"minValue": 0
}
},
"additionalProperties": true
}
}
La valeur discriminator
définit le schéma à appliquer en fonction d’une propriété de discriminateur. L’exemple suivant accepte {"type": "ints", "foo": 1, "bar": 2}
ou {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"}
, mais rejette {"type": "ints", "fizz": "buzz"}
.
"parameters": {
"taggedUnionParameter": {
"type": "object",
"discriminator": {
"propertyName": "type",
"mapping": {
"ints": {
"type": "object",
"additionalProperties": {"type": "int"}
},
"strings": {
"type": "object",
"additionalProperties": {"type": "string"}
}
}
}
}
}
Les contraintes de tableau sont uniquement autorisées sur les tableaux et ne peuvent être utilisées qu’avec languageVersion 2.0.
La valeur de prefixItems
est un tableau de définitions de type. Chaque définition de type dans la valeur est le schéma à utiliser pour valider l’élément d’un tableau au même index. L’exemple suivant accepte [1, true]
mais rejette [1, "string"]
ou [1]
:
"parameters": {
"tupleParameter": {
"type": "array",
"prefixItems": [
{"type": "int"},
{"type": "bool"}
]
}
}
La valeur de items
est une définition de type ou un booléen. Si aucune contrainte items
n’est définie, la valeur par défaut est true
.
Si la valeur est une définition de type, la valeur décrit le schéma appliqué à tous les éléments du tableau dont l’index est supérieur à l’index le plus grand de la contrainte prefixItems
. L’exemple suivant accepte [1, true, 1]
ou [1, true, 1, 1]
, mais rejette [1, true, "foo"]
:
"parameters": {
"tupleParameter": {
"type": "array",
"prefixItems": [
{ "type": "int" },
{ "type": "bool" }
],
"items": { "type": "int" },
"defaultValue": [1, true, "foo"]
}
}
Vous pouvez utiliser items
sans utiliser prefixItems
. L’exemple suivant accepte [1, 2]
ou [1]
, mais rejette ["foo"]
:
"parameters": {
"intArrayParameter": {
"type": "array",
"items": {"type": "int"}
}
}
Si la valeur est false
, le tableau validé doit avoir exactement la même longueur que la contrainte prefixItems
. L’exemple suivant accepte [1, true]
, mais rejette [1, true, 1]
et [1, true, false, "foo", "bar"]
.
"parameters": {
"tupleParameter": {
"type": "array",
"prefixItems": [
{"type": "int"},
{"type": "bool"}
],
"items": false
}
}
Si la valeur est true, les éléments du tableau dont l’index est supérieur au plus grand index de la contrainte prefixItems
acceptent n’importe quelle valeur. Les exemples suivants acceptent [1, true]
, [1, true, 1]
et [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
}
La contrainte pouvant accepter la valeur Null ne peut être utilisée qu’avec languageVersion 2.0. La valeur peut être null
ou omise. Pour obtenir un exemple, consultez Propriétés.
Vous pouvez ajouter une description à un paramètre pour aider les utilisateurs de votre modèle à comprendre la valeur à fournir. Lorsque vous déployez le modèle par le biais du portail, le texte que vous fournissez dans la description est automatiquement utilisé comme une info-bulle pour ce paramètre. Ajoutez une description uniquement quand le texte fournit des informations en plus de celles qui peuvent être déduites du nom du paramètre.
"parameters": {
"virtualMachineSize": {
"type": "string",
"metadata": {
"description": "Must be at least Standard_A3 to support 2 NICs."
},
"defaultValue": "Standard_DS1_v2"
}
}
Pour référencer la valeur d’un paramètre, utilisez la fonction parameters. L’exemple suivant utilise une valeur de paramètre pour un nom de coffre de clés.
{
"$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')]",
...
}
]
}
Vous pouvez organiser des valeurs connexes en les transmettant en tant qu’objet. Cette approche réduit également le nombre de paramètres dans le modèle.
L’exemple suivant illustre un paramètre qui est un objet. La valeur par défaut affiche les propriétés attendues pour l’objet. Ces propriétés sont utilisées lors de la définition de la ressource à déployer.
{
"$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]"
}
}
]
}
}
]
}
Les exemples suivants illustrent des scénarios d’utilisation de paramètres.
Modèle | Description |
---|---|
Paramètres avec fonctions pour les valeurs par défaut | Montre comment utiliser les fonctions de modèle durant la définition des valeurs par défaut des paramètres. Le modèle ne déploie aucune ressource. Il crée et retourne des valeurs de paramètres. |
Objet de paramètre | Montre comment utiliser un objet pour un paramètre. Le modèle ne déploie aucune ressource. Il crée et retourne des valeurs de paramètres. |
- Pour plus d’informations sur les propriétés disponibles pour les paramètres, consultez Présentation de la structure et de la syntaxe des modèles ARM.
- Pour en savoir plus sur le passage de valeurs de paramètre sous forme de fichier, consultez Créer un fichier de paramètres Resource Manager.
- Pour obtenir des recommandations sur la création de paramètres, consultez Bonnes pratiques - Paramètres.