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.

Vous êtes limité à 256 paramètres dans un fichier Bicep. 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

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	Valeurs autorisées pour le paramètre. Utilisez cet élément décoratif pour vérifier que l’utilisateur fournit des valeurs correctes.
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@2020-06-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.