Comprendre les paramètres

  • 8 minutes

Grâce aux paramètres, vous pouvez fournir des informations au modèle Bicep au moment du déploiement. Vous pouvez rendre un modèle Bicep flexible et réutilisable en déclarant des paramètres dans le modèle.

Les éléments décoratifs permettent de joindre des contraintes et des métadonnées à un paramètre, ce qui permet à chaque personne utilisant vos modèles de comprendre les informations à fournir.

Dans cette leçon, vous allez découvrir les paramètres et les éléments décoratifs.

Déclarer un paramètre

Dans un modèle Bicep, un paramètre est déclaré à l’aide du mot clé param. Vous pouvez placer ces déclarations n’importe où dans le fichier de modèle. Cependant, il est généralement judicieux de les placer en haut du fichier afin de faciliter la lecture de votre code Bicep.

Voici comment déclarer un paramètre :

param environmentName string

Examinons chaque élément :

  • param indique à Bicep que vous déclarez un paramètre.

  • environmentName fait référence au nom du paramètre. Même si le nom du paramètre est entièrement libre, vous devez choisir un nom clair et explicite pour les utilisateurs du modèle. Dans le même modèle, vous pouvez également faire référence au paramètre à l’aide de son nom. Les noms de paramètre doivent être uniques. Il ne doit pas porter le même nom qu’une variable ni qu’une ressource dans le même fichier Bicep.

    Conseil

    Utilisez les bonnes pratiques liées aux conventions de nommage pour les déclarations de paramètres. De bonnes conventions de nommage rendent vos modèles faciles à lire et à comprendre. Veillez à utiliser des noms clairs et descriptifs, et adoptez une stratégie de nommage cohérente.

  • string fait référence au type de paramètre.

    Conseil

    Réfléchissez bien aux paramètres utilisés par votre modèle. Essayez d’utiliser des paramètres pour les valeurs qui varient entre les déploiements. Les variables et les valeurs codées en dur peuvent être utilisées pour les paramètres qui ne changent pas entre les déploiements.

Ajouter une valeur par défaut

Vous pouvez attribuer des valeurs par défaut aux paramètres dans vos modèles. En attribuant une valeur par défaut, vous rendez le paramètre facultatif. Si le modèle est déployé sans valeur spécifiée pour le paramètre, la valeur par défaut est attribuée.

Voici comment ajouter une valeur par défaut :

param environmentName string = 'dev'

Le paramètre environmentName est défini sur la valeur par défaut dev.

Vous pouvez utiliser des expressions en tant que valeurs par défaut. Voici un exemple de paramètre de chaîne nommé location avec une valeur par défaut définie sur l’emplacement du groupe de ressources actuel :

param location string = resourceGroup().location

Conseil

Faites attention aux valeurs par défaut que vous utilisez. Assurez-vous qu’il est possible de déployer le fichier Bicep en toute sécurité avec les valeurs par défaut. Par exemple, envisagez d’utiliser des niveaux de tarification et des références SKU peu coûteux afin d’éviter des frais inutilement élevés si quelqu’un déploie le modèle dans un environnement de test.

Comprendre les types de paramètres

Quand vous déclarez un paramètre, vous devez indiquer à Bicep le type d’informations qu’il contient. Bicep s’assure que la valeur assignée au paramètre est compatible avec le type de paramètre.

Voici les types de paramètres dans Bicep :

  • string permet d’entrer du texte arbitraire.
  • int permet d’entrer un nombre.
  • bool représente une valeur booléenne (true ou false).
  • object et array représentent des données structurées et des listes.

Objets

Vous pouvez utiliser des paramètres d’objet pour combiner des données structurées dans un même emplacement. Un objet peut avoir plusieurs propriétés de types différents. Vous pouvez utiliser des objets dans les définitions de ressources, dans des variables ou dans des expressions dans votre fichier Bicep. Voici un exemple d’objet :

param appServicePlanSku object = {
  name: 'F1'
  tier: 'Free'
  capacity: 1
}

Ce paramètre est un objet avec deux propriétés de chaîne, name et tier, et une propriété de type entier capacity. Notez que chacune des propriétés se trouve sur sa propre ligne.

Quand vous faites référence au paramètre dans le modèle, vous pouvez sélectionner les propriétés individuelles de l’objet à l’aide d’un point suivi du nom de la propriété, comme dans cet exemple :

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku.name
    tier: appServicePlanSku.tier
    capacity: appServicePlanSku.capacity
  }
}

Important

N’oubliez pas que vous ne spécifiez pas le type de chaque propriété dans un objet. Toutefois, quand vous utilisez une valeur de propriété, le type doit correspondre à ce qui est attendu. Dans l’exemple précédent, le nom et le niveau de la référence SKU du plan App Service doivent tous les deux être des chaînes.

Autre exemple : vous pouvez utiliser un paramètre d’objet pour spécifier des étiquettes de ressource. Vous pouvez joindre des métadonnées d’étiquette personnalisée aux ressources que vous déployez, qui permettront d’identifier les informations importantes sur une ressource.

Les étiquettes sont utiles dans des scénarios de suivi pour déterminer quelle équipe est propriétaire d’une ressource, ou bien quand une ressource appartient à un environnement de production ou hors production. En règle générale, vous utilisez différentes étiquettes pour chaque environnement. Toutefois, vous devez réutiliser les mêmes valeurs d’étiquette sur toutes les ressources de votre modèle. C’est pourquoi les étiquettes de ressource constituent une bonne utilisation pour un paramètre d’objet, comme dans cet exemple :

param resourceTags object = {
  EnvironmentName: 'Test'
  CostCenter: '1000100'
  Team: 'Human Resources'
}

Chaque fois que vous définissez une ressource dans votre fichier Bicep, vous pouvez la réutiliser partout où vous définissez la propriété tags :

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  tags: resourceTags
  sku: {
    name: 'S1'
  }
}

resource appServiceApp 'Microsoft.Web/sites@' = {
  name: appServiceAppName
  location: location
  tags: resourceTags
  kind: 'app'
  properties: {
    serverFarmId: appServicePlan.id
  }
}

Tableaux

Un tableau est une liste d’éléments. Par exemple, vous pouvez utiliser un tableau de valeurs de chaîne pour déclarer une liste d’adresses de messagerie d’un groupe d’actions Azure Monitor. Vous pouvez également utiliser un tableau d’objets pour représenter une liste de sous-réseaux d’un réseau virtuel.

Notes

Il n’est pas possible de spécifier le type d’éléments individuels qu’un tableau doit contenir. Par exemple, vous ne pouvez pas spécifier qu’un tableau doit contenir des chaînes.

Prenons un exemple. Azure Cosmos DB permet de créer des comptes de base de données qui s’étendent sur plusieurs régions. Le service gère automatiquement la réplication des données pour vous. Quand vous déployez un nouveau compte de base de données, vous devez spécifier la liste des régions Azure dans lesquelles vous souhaitez déployer le compte. La liste des emplacements est souvent différente pour les divers environnements. Par exemple, pour économiser de l’argent dans votre environnement de test, vous pouvez utiliser un seul, voire deux emplacements. En revanche, vous pouvez utiliser plusieurs emplacements dans votre environnement de production.

Vous pouvez créer un paramètre de tableau qui spécifie une liste d’emplacements :

param cosmosDBAccountLocations array = [
  {
    locationName: 'australiaeast'
  }
  {
    locationName: 'southcentralus'
  }
  {
    locationName: 'westeurope'
  }
]

Conseil

L’exemple précédent correspond à un tableau d’objets. Chaque objet possède une propriété locationName, comme attendu par Azure Cosmos DB. Quand vous utilisez une définition de ressource dans Visual Studio Code, vous pouvez commencer par entrer des propriétés de ressource afin d’avoir accès à IntelliSense à partir des outils Bicep. Vous pouvez créer des exemples de valeurs à l’aide de cette approche. Une fois que vous êtes satisfait de la configuration, déplacez cette section du code Bicep vers le paramètre. De cette façon, vous pouvez remplacer une propriété codée en dur par un paramètre qui peut être modifié lors de chaque déploiement, tout en garantissant que la ressource est correctement configurée.

Quand vous déclarez votre ressource Azure Cosmos DB, vous pouvez maintenant faire référence au paramètre de tableau :

resource account 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  name: accountName
  location: location
  properties: {
    locations: cosmosDBAccountLocations
  }
}

Il est ensuite facile d’utiliser une valeur de paramètre différente pour votre environnement de développement en modifiant la valeur du paramètre. Vous allez bientôt découvrir comment fournir des valeurs de paramètres différentes sans modifier le modèle d’origine.

Spécifier une liste de valeurs autorisées

Vous devez parfois vous assurer qu’un paramètre a certaines valeurs. Par exemple, votre équipe peut décider que les plans de production App Service doivent être déployés à l’aide des références SKU Premium v3. Pour appliquer cette règle, vous pouvez utiliser l’élément décoratif de paramètre @allowed. Un élément décoratif de paramètre constitue un moyen de fournir à Bicep des informations sur des caractéristiques de la valeur d’un paramètre. Voici comment un paramètre de chaîne nommé appServicePlanSkuName peut être limité de telle manière que seules certaines valeurs spécifiques sont autorisées :

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
param appServicePlanSkuName string

Conseil

Utilisez l’élément décoratif @allowed avec parcimonie. Si vous utilisez cet élément décoratif trop souvent, vous risquez de bloquer des déploiements valides si vous ne conservez pas la liste à jour. L’exemple précédent autorise uniquement les références SKU Premium v3 en production. Si vous devez utiliser le même modèle pour déployer des environnements hors production moins onéreux, la liste des valeurs autorisées peut vous empêcher d’utiliser les autres références SKU que vous devez utiliser.

Limiter la longueur et les valeurs des paramètres

Quand vous utilisez des paramètres de chaîne, vous devez souvent limiter la longueur de la chaîne. Prenons l’exemple du nommage des ressources Azure. Tous les types de ressources Azure présentent des limites concernant la longueur du nom. Il est recommandé de spécifier la longueur de caractère minimale et maximale pour les paramètres qui contrôlent le nommage afin d’éviter les erreurs ultérieures lors du déploiement. Vous pouvez utiliser les éléments décoratifs @minLength et @maxLength en indiquant les longueurs de caractères minimale et maximale que vous souhaitez autoriser pour un paramètre.

Voici un exemple qui déclare un paramètre de chaîne nommé storageAccountName, dont la longueur doit être comprise entre 5 et 24 caractères :

@minLength(5)
@maxLength(24)
param storageAccountName string

Ce paramètre comprend deux éléments décoratifs. Vous pouvez appliquer plusieurs éléments décoratifs à un paramètre en plaçant chaque élément décoratif sur sa propre ligne.

Notes

Vous pouvez également appliquer les éléments décoratifs @minLength et @maxLength aux paramètres de tableau pour contrôler le nombre d’éléments autorisés dans le tableau.

Quand vous utilisez des paramètres numériques, vous pouvez avoir besoin de valeurs dans une plage particulière. Par exemple, votre entreprise de jouets peut décider que chaque fois que quelqu’un déploie un plan App Service, il doit déployer au moins une instance, mais pas plus de 10 instances du plan. Afin de répondre aux exigences, vous pouvez utiliser les éléments décoratifs @minValue et @maxValue pour spécifier les valeurs minimale et maximale autorisées. L’exemple suivant déclare le paramètre entier appServicePlanInstanceCount dont la valeur doit être comprise entre 1 et 10 (inclus) :

@minValue(1)
@maxValue(10)
param appServicePlanInstanceCount int

Ajouter des descriptions aux paramètres

Les paramètres sont un excellent moyen de rendre vos modèles réutilisables par d’autres personnes. Quand quelqu’un utilise vos modèles, il doit comprendre la finalité de chaque paramètre afin de pouvoir fournir les valeurs correctes. Bicep fournit l’élément décoratif @description pour vous permettre de documenter la finalité de vos paramètres de manière explicite pour les personnes.

@description('The locations into which this Cosmos DB account should be configured. This parameter needs to be a list of objects, each of which has a locationName property.')
param cosmosDBAccountLocations array

Il est recommandé de fournir des descriptions pour vos paramètres. Essayez d’utiliser des descriptions utiles et fournissez toutes les informations importantes sur les exigences du modèle pour les valeurs de paramètres.

Notes

Les modèles Bicep peuvent parfois être mis à disposition des utilisateurs dans le portail Azure pour être déployés, comme quand vous utilisez des Specs de modèle. Le portail utilise les descriptions et autres éléments décoratifs sur les paramètres pour aider les utilisateurs à comprendre les exigences d’une valeur de paramètre.