Paramètres dans Bicep
Cet article explique comment définir et utiliser des paramètres dans un fichier Bicep. En fournissant des valeurs différentes pour les paramètres, vous pouvez réutiliser un fichier Bicep 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é, Resource Manager le remplace par la valeur résolue.
Chaque paramètre doit être défini sur l’un des types de données.
Bicep autorise un maximum de 256 paramètres. Pour plus d’informations, consultez Limites du modèle.
Pour connaître les meilleures pratiques relatives aux paramètres, consultez Paramètres.
Ressources de formation
Si vous préférez découvrir les paramètres via des instructions d’aide pas à pas, consultez Créer des modèles Bicep réutilisables en utilisant des paramètres.
Déclaration
Chaque paramètre a un nom et un type de données. Si vous le souhaitez, vous pouvez attribuer une valeur par défaut à un paramètre.
param <parameter-name> <parameter-data-type> = <default-value>
Un paramètre ne peut pas avoir le même nom qu’une variable, qu’une ressource, qu’une sortie ou qu’un autre paramètre dans la même étendue.
L’exemple suivant montre des déclarations de base de paramètres.
param demoString string
param demoInt int
param demoBool bool
param demoObject object
param demoArray array
Le param
mot clé est également utilisé dans les fichiers .bicepparam. Dans les fichiers .bicepparam, vous n’avez pas besoin de spécifier le type de données, tel qu’il est défini dans les fichiers Bicep.
param <parameter-name> = <value>
Si vous souhaitez obtenir plus d’informations, consultez Fichier de paramètres.
Les expressions de type définies par l’utilisateur peuvent être utilisées comme clause de type d’une instruction param
. Par exemple :
param storageAccountConfig {
name: string
sku: string
}
Pour plus d'informations, voir Type de données définis par l’utilisateur.
Valeur par défaut
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.
param demoParam string = 'Contoso'
Vous pouvez utiliser des expressions avec la valeur par défaut. Les expressions ne sont pas autorisées avec d’autres propriétés de paramètre. 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.
param location string = 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.
param siteName string = 'site${uniqueString(resourceGroup().id)}'
param hostingPlanName string = '${siteName}-plan'
output siteNameOutput string = siteName
output hostingPlanOutput string = hostingPlanName
Toutefois, vous ne pouvez pas référencer une variable comme valeur par défaut.
Décorateurs
Les paramètres utilisent des décorateurs pour les contraintes ou les métadonnées. Les décorateurs sont au format @expression
et sont placés au-dessus de la déclaration du paramètre. Vous pouvez marquer un paramètre comme sécurisé, spécifier des valeurs autorisées, définir la longueur minimale et maximale d’une chaîne, définir la valeur minimale et maximale d’un entier et fournir une description du paramètre.
L’exemple suivant montre deux utilisations courantes des éléments décoratifs.
@secure()
param demoPassword string
@description('Must be at least Standard_A3 to support 2 NICs.')
param virtualMachineSize string = 'Standard_DS1_v2'
Le tableau suivant décrit les éléments décoratifs disponibles et leur utilisation.
Élément décoratif | S’applique à | Argument | Description |
---|---|---|---|
autorisé | all | tableau | Utilisez cet élément décoratif pour vérifier que l’utilisateur fournit des valeurs correctes. L’élément décoratif n’est autorisé que sur les instructions param . Pour déclarer qu’une propriété doit faire partie d’un ensemble de valeurs prédéfinies dans une instruction type ou output , utilisez la syntaxe de type union. La syntaxe de type Union peut également être utilisée dans les instructions param . |
description | all | string | Texte qui explique comment utiliser le paramètre. La description apparaît aux utilisateurs dans le portail. |
maxLength | array, string | int | Longueur maximale des paramètres de type chaîne et tableau. La valeur est inclusive. |
maxValue | int | int | Valeur maximale du paramètre de type entier. Cette valeur est inclusive. |
métadonnées | all | object | Propriétés personnalisées à appliquer au paramètre. Peut inclure une propriété Description qui est équivalente à l’élément décoratif de description. |
minLength | array, string | int | Longueur minimale des paramètres de type chaîne et tableau. La valeur est inclusive. |
minValue | int | int | Valeur minimale du paramètre de type entier. Cette valeur est inclusive. |
secure | string, object | Aucun | Marque le paramètre comme sécurisé. 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. Pour plus d’informations, consultez Sécuriser les chaînes et les objets. |
Les éléments décoratifs se trouvent dans l’espace de noms sys. Si vous devez différencier un élément décoratif d'un autre élément portant le même nom, faites précéder l’élément décoratif de sys
. Par exemple, si votre fichier Bicep contient un paramètre nommé description
, vous devez ajouter l’espace de noms sys lors de l’utilisation de l’élément décoratif description.
@sys.description('The name of the instance.')
param name string
@sys.description('The description of the instance to display.')
param description string
Les éléments décoratifs disponibles sont décrits dans les sections suivantes.
Paramètres sécurisés
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.
@secure()
param demoPassword string
@secure()
param demoSecretObject object
Valeurs autorisées
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.
@allowed([
'one'
'two'
])
param demoEnum string
Si vous définissez des valeurs autorisées pour un paramètre de tableau, la valeur réelle peut être n’importe quel sous-ensemble des valeurs autorisées.
Contraintes de longueur
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.
@minLength(3)
@maxLength(24)
param storageAccountName string
@minLength(1)
@maxLength(5)
param appNames array
Contraintes d’entier
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.
@minValue(1)
@maxValue(12)
param month int
Description
Pour aider les utilisateurs à comprendre la valeur qu’ils doivent fournir, ajoutez une description au paramètre. Lorsqu’un utilisateur déploie le modèle par le biais du portail, le texte de 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.
@description('Must be at least Standard_A3 to support 2 NICs.')
param virtualMachineSize string = 'Standard_DS1_v2'
Du texte au format Markdown peut être utilisé pour le texte de description :
@description('''
Storage account name restrictions:
- Storage account names must be between 3 and 24 characters in length and may contain numbers and lowercase letters only.
- Your storage account name must be unique within Azure. No two storage accounts can have the same name.
''')
@minLength(3)
@maxLength(24)
param storageAccountName string
Quand vous placez le curseur sur storageAccountName dans VS Code, vous voyez le texte mis en forme :
Assurez-vous que le texte suit la mise en forme Markdown appropriée. Sinon, il peut ne pas s’afficher correctement lors du rendu.
Métadonnées
Si vous disposez de propriétés personnalisées que vous souhaitez appliquer à un paramètre, ajoutez un élément décoratif de métadonnées. Dans les métadonnées, définissez un objet avec des noms et valeurs personnalisés. L’objet que vous définissez pour les métadonnées peut contenir des propriétés de n’importe quel nom et type.
Vous pouvez utiliser cet élément décoratif pour suivre les informations relatives au paramètre qu'il n'est pas utile d'ajouter à la description.
@description('Configuration values that are applied when the application starts.')
@metadata({
source: 'database'
contact: 'Web team'
})
param settings object
Lorsque vous fournissez un @metadata()
élément décoratif avec une propriété qui est en conflit avec un autre élément décoratif, cet élément décoratif est toujours prioritaire sur tout ce qui se passe dans @metadata()
l’élément décoratif. Par conséquent, la propriété en conflit dans la valeur @metadata()
est redondante et sera remplacée. Pour plus d’informations, consultez Aucune métadonnée en conflit.
Utiliser un paramètre
Pour référencer la valeur d’un paramètre, utilisez le nom du paramètre. L’exemple suivant utilise une valeur de paramètre comme nom de coffre de clés.
param vaultName string = 'keyVault${uniqueString(resourceGroup().id)}'
resource keyvault 'Microsoft.KeyVault/vaults@2019-09-01' = {
name: vaultName
...
}
Objets en tant que paramètres
Il peut s’avérer plus facile d’organiser des valeurs connexes en les transmettant en tant qu’objets. 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.
param vNetSettings object = {
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'
}
]
}
resource vnet 'Microsoft.Network/virtualNetworks@2023-11-01' = {
name: vNetSettings.name
location: vNetSettings.location
properties: {
addressSpace: {
addressPrefixes: [
vNetSettings.addressPrefixes[0].addressPrefix
]
}
subnets: [
{
name: vNetSettings.subnets[0].name
properties: {
addressPrefix: vNetSettings.subnets[0].addressPrefix
}
}
{
name: vNetSettings.subnets[1].name
properties: {
addressPrefix: vNetSettings.subnets[1].addressPrefix
}
}
]
}
}
Étapes suivantes
- Pour plus d’informations sur les propriétés qui sont disponibles pour les paramètres, consultez Présentation de la structure et de la syntaxe des fichiers Bicep.
- Pour en savoir plus sur le passage de valeurs de paramètre sous forme de fichier, consultez Créer un fichier de paramètres Bicep.
- Pour en savoir plus sur la fourniture de valeurs de paramètres lors du déploiement, consultez Déployer avec azure CLI et Déployer avec Azure PowerShell.