Comprendre la structure et la syntaxe des fichiers Bicep

Article
08/28/2024

Cet article décrit la structure et la syntaxe d’un fichier Bicep. Il présente les différentes sections du fichier et les propriétés disponibles dans ces sections.

Pour obtenir un didacticiel pas à pas qui vous guide tout au long du processus de création d’un fichier Bicep, consultez Démarrage rapide : créer des fichiers Bicep avec Visual Studio Code.

Format Bicep

Bicep est un langage déclaratif, ce qui signifie que les éléments peuvent apparaître dans n’importe quel ordre. Contrairement aux langages impératifs, l’ordre des éléments n’a pas d’incidence sur le mode de traitement du déploiement.

Un fichier Bicep contient les éléments suivants.

metadata <metadata-name> = ANY

targetScope = '<scope>'

@<decorator>(<argument>)
type <user-defined-data-type-name> = <type-expression>

@<decorator>(<argument>)
func <user-defined-function-name> (<argument-name> <data-type>, <argument-name> <data-type>, ...) <function-data-type> => <expression>

@<decorator>(<argument>)
param <parameter-name> <parameter-data-type> = <default-value>

@<decorator>(<argument>)
var <variable-name> = <variable-value>

@<decorator>(<argument>)
resource <resource-symbolic-name> '<resource-type>@<api-version>' = {
  <resource-properties>
}

@<decorator>(<argument>)
module <module-symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

output <output-name> <output-data-type> = <output-value>

L’exemple suivant montre une implémentation de ces éléments.

metadata description = 'Creates a storage account and a web app'

@description('The prefix to use for the storage account name.')
@minLength(3)
@maxLength(11)
param storagePrefix string

param storageSKU string = 'Standard_LRS'
param location string = resourceGroup().location

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

module webModule './webApp.bicep' = {
  name: 'webDeploy'
  params: {
    skuName: 'S1'
    location: location
  }
}

Métadonnées

Les métadonnées dans Bicep constituent une valeur non typée qui peut être incluse dans les fichiers Bicep. Elle vous permet de fournir des informations supplémentaires sur vos fichiers Bicep, y compris des détails tels que son nom, sa description, son auteur, la date de création, etc.

Étendue cible

Par défaut, l’étendue cible est définie sur resourceGroup. Si vous effectuez un déploiement au niveau du groupe de ressources, vous n’avez pas besoin de définir l’étendue cible dans votre fichier Bicep.

Les valeurs autorisées sont les suivantes :

resourceGroup : valeur par défaut, utilisée pour les déploiements de groupes de ressources.
subscription : utilisée pour les déploiements d’abonnements.
managementGroup : utilisée pour les déploiements de groupes d’administration.
tenant : utilisée pour les déploiements de locataires.

Dans un module, vous pouvez spécifier une étendue différente de celle du reste du fichier Bicep. Pour plus d'informations, consultez Configurer l’étendue du module

Décorateurs

Vous pouvez ajouter un ou plusieurs éléments décoratifs pour chacun des éléments suivants :

param
var
resource
module
output
func
type

Élément décoratif	Appliquer à l’élément	Appliquer au type de données	Argument	Description
autorisé	param	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`.
batchSize	resource, module	S/O	entier	Configurer des instances pour un déploiement séquentiel.
description	param, var, resource, module, output, type, func	all	string	Fournir des descriptions pour les éléments. Du texte au format Markdown peut être utilisé pour le texte de description.
discriminator	param, type, output	object	string	Utilisez ce décorateur pour vous assurer que la sous-classe appropriée est identifiée et gérée. Pour plus d’informations, consultez Type de données union étiqueté personnalisé.
export	var, type, func	all	Aucune	Indique que l’élément peut être importé par un autre fichier Bicep.
maxLength	param, output	array, string	int	Longueur maximale des éléments de type chaîne et tableau. La valeur est inclusive.
maxValue	param, output	int	int	Valeur maximale des éléments de type entier. Cette valeur est inclusive.
metadata	param, output	all	object	Propriétés personnalisées à appliquer aux éléments. Peut inclure une propriété Description qui est équivalente à l’élément décoratif de description.
minLength	param, output	array, string	int	Longueur minimale des éléments de type chaîne et tableau. La valeur est inclusive.
minValue	param, output	int	int	Valeur minimale des éléments de type entier. Cette valeur est inclusive.
sealed	param, type, output	object	Aucune	Élever BCP089 d’avertissement à erreur lorsqu’un nom de propriété d’un type de données défini par l’utilisateur est probablement une faute de frappe. Pour plus d’informations, consultez Élever le niveau d’erreur.
secure	param	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.

Paramètres

Utilisez des paramètres pour les valeurs qui doivent varier en fonction des différents déploiements. Vous pouvez définir une valeur par défaut pour le paramètre qui sera utilisé si aucune valeur n’est fournie pendant le déploiement.

Par exemple, vous pouvez ajouter un paramètre SKU pour spécifier différentes tailles pour une ressource. Vous pouvez transmettre des valeurs différentes selon que vous effectuez le déploiement en test ou en production.

param storageSKU string = 'Standard_LRS'

Le paramètre peut être utilisé dans votre fichier Bicep.

sku: {
  name: storageSKU
}

Vous pouvez ajouter un ou plusieurs éléments décoratifs pour chaque paramètre. Pour plus d’informations, consultez Utiliser des éléments décoratifs.

Pour plus d’informations, consultez Paramètres dans Bicep.

Variables

Vous pouvez rendre votre fichier Bicep plus lisible en encapsulant des expressions complexes dans une variable. Par exemple, vous pouvez ajouter une variable pour un nom de ressource construit en concaténant plusieurs valeurs ensemble.

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

Appliquez cette variable partout où vous avez besoin de l’expression complexe.

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: uniqueStorageName

Vous pouvez ajouter un ou plusieurs éléments décoratifs pour chaque variable. Pour plus d’informations, consultez Utiliser des éléments décoratifs.

Pour plus d’informations, consultez Variables dans Bicep.

Types

Vous pouvez employer l’instruction type pour définir les types de données définis par l’utilisateur.

param location string = resourceGroup().location

type storageAccountSkuType = 'Standard_LRS' | 'Standard_GRS'

type storageAccountConfigType = {
  name: string
  sku: storageAccountSkuType
}

param storageAccountConfig storageAccountConfigType = {
  name: 'storage${uniqueString(resourceGroup().id)}'
  sku: 'Standard_LRS'
}

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

Vous pouvez ajouter un ou plusieurs éléments décoratifs pour chaque type de données défini par l’utilisateur. Pour plus d’informations, consultez Utiliser des éléments décoratifs.

Pour plus d'informations, voir Type de données définis par l’utilisateur.

Functions

Dans votre fichier Bicep, vous pouvez créer vos propres fonctions en plus d'utiliser les fonctions Bicep standard qui sont automatiquement disponibles dans vos fichiers Bicep. Créez vos propres fonctions lorsque vous avez des expressions complexes utilisées à plusieurs reprises dans vos fichiers Bicep.

func buildUrl(https bool, hostname string, path string) string => '${https ? 'https' : 'http'}://${hostname}${empty(path) ? '' : '/${path}'}'

output azureUrl string = buildUrl(true, 'microsoft.com', 'azure')

Pour plus d'informations, consultez Fonctions définies par l’utilisateur.

Ressources

Utilisez le mot clé resource pour définir une ressource à déployer. Votre déclaration de ressource comprend un nom symbolique pour la ressource. Pour obtenir une valeur de la ressource, utilisez ce nom symbolique dans d’autres parties du fichier Bicep.

La déclaration de ressource comprend le type de ressource et la version de l’API. Dans le corps de la déclaration de ressource, incluez les propriétés spécifiques au type de ressource.

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

Vous pouvez ajouter un ou plusieurs éléments décoratifs pour chaque ressource. Pour plus d’informations, consultez Utiliser des éléments décoratifs.

Pour plus d’informations, consultez Déclaration de ressource dans Bicep.

Certaines ressources ont une relation parent/enfant. Vous pouvez définir une ressource enfant à l’intérieur de la ressource parent ou en dehors de cette ressource.

L’exemple suivant montre comment définir une ressource enfant au sein d’une ressource parent. Elle contient un compte de stockage avec une ressource enfant (service de fichiers) définie dans le compte de stockage. Le service de fichiers comprend également une ressource enfant (partage) qui est définie dedans.

resource storage 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: 'examplestorage'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }

  resource service 'fileServices' = {
    name: 'default'

    resource share 'shares' = {
      name: 'exampleshare'
    }
  }
}

L’exemple suivant montre la ressource enfant en dehors de la ressource parent. La propriété parent vous servira à identifier une relation parent/enfant. Les trois mêmes ressources sont définies.

resource storage 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: 'examplestorage'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

resource service 'Microsoft.Storage/storageAccounts/fileServices@2023-04-01' = {
  name: 'default'
  parent: storage
}

resource share 'Microsoft.Storage/storageAccounts/fileServices/shares@2023-04-01' = {
  name: 'exampleshare'
  parent: service
}

Pour plus d’informations, consultez Définition du nom et du type des ressources enfants dans Bicep.

Modules

Les modules vous permettent de réutiliser du code à partir d’un fichier Bicep dans d’autres fichiers Bicep. Dans la déclaration de module, vous pouvez créer un lien vers le fichier à réutiliser. Lorsque vous déployez le fichier Bicep, les ressources du module sont également déployées.

module webModule './webApp.bicep' = {
  name: 'webDeploy'
  params: {
    skuName: 'S1'
    location: location
  }
}

Le nom symbolique vous permet de référencer le module à partir d’un autre emplacement dans le fichier. Par exemple, vous pouvez obtenir une valeur de sortie à partir d’un module en utilisant le nom symbolique et le nom de la valeur de sortie.

Vous pouvez ajouter un ou plusieurs éléments décoratifs pour chaque module. Pour plus d’informations, consultez Utiliser des éléments décoratifs.

Pour plus d’informations, consultez Utiliser des modules Bicep.

Outputs

Utilisez des sorties pour renvoyer des valeurs à partir du déploiement. En règle générale, vous renvoyez une valeur d’une ressource déployée lorsque vous devez réutiliser cette valeur pour une autre opération.

output storageEndpoint object = stg.properties.primaryEndpoints

Vous pouvez ajouter un ou plusieurs éléments décoratifs pour chaque sortie. Pour plus d’informations, consultez Utiliser des éléments décoratifs.

Pour plus d’informations, consultez Sorties dans Bicep.

Boucles

Vous pouvez ajouter des boucles itératives à votre fichier Bicep pour définir plusieurs copies d’un :

resource
module
variable
propriété
sortie

Utilisez l’expression for pour définir une boucle.

param moduleCount int = 2

module stgModule './example.bicep' = [for i in range(0, moduleCount): {
  name: '${i}deployModule'
  params: {
  }
}]

Vous pouvez effectuer une itération sur un tableau, un objet ou un index d’entiers.

Pour plus d’informations, consultez Boucles itératives dans Bicep.

Déploiement conditionnel

Vous pouvez ajouter une ressource ou un module à votre fichier Bicep qui est déployé de manière conditionnelle. Pendant le déploiement, la condition est évaluée et le résultat détermine si la ressource ou le module est déployé. Utilisez l’expression if pour définir un déploiement conditionnel.

param deployZone bool

resource dnsZone 'Microsoft.Network/dnsZones@2023-07-01-preview' = if (deployZone) {
  name: 'myZone'
  location: 'global'
}

Pour plus d’informations, consultez Déploiement conditionnel dans Bicep.

Espace blanc

Les espaces et les tabulations sont ignorés lors de la création de fichiers Bicep.

Bicep est sensible aux sauts de ligne. Par exemple :

resource sa 'Microsoft.Storage/storageAccounts@2023-04-01' = if (newOrExisting == 'new') {
  ...
}

Ne peut pas être écrit sous la forme :

resource sa 'Microsoft.Storage/storageAccounts@2023-04-01' =
    if (newOrExisting == 'new') {
      ...
    }

Définir des objets et des tableaux sur plusieurs lignes.

Commentaires

Utilisez // pour les commentaires d’une seule ligne ou /* ... */ pour les commentaires de plusieurs lignes.

L’exemple suivant montre un commentaire d’une seule ligne.

// This is your primary NIC.
resource nic1 'Microsoft.Network/networkInterfaces@2023-11-01' = {
  ...
}

L’exemple suivant montre un commentaire de plusieurs lignes.

/*
  This Bicep file assumes the key vault already exists and
  is in same subscription and resource group as the deployment.
*/
param existingKeyVaultName string

Chaînes à lignes multiples

Vous pouvez scinder une chaîne en plusieurs lignes. Utilisez trois caractères guillemets simples ''' pour commencer et terminer la chaîne à plusieurs lignes.

Les caractères de la chaîne à plusieurs lignes sont traités tels quels. Les caractères d’échappement ne sont pas nécessaires. Vous ne pouvez pas inclure ''' dans la chaîne à plusieurs lignes. L’interpolation de chaîne n’est pas prise en charge actuellement.

Vous pouvez démarrer votre chaîne juste après l’ouverture ''' ou inclure une nouvelle ligne. Dans les deux cas, la chaîne résultante n’inclut pas de nouvelle ligne. Selon les fins de ligne dans votre fichier Bicep, les nouvelles lignes sont interprétées comme \r\n ou \n.

L’exemple suivant montre une chaîne à plusieurs lignes.

var stringVar = '''
this is multi-line
  string with formatting
  preserved.
'''

L’exemple précédent équivaut au code JSON suivant.

"variables": {
  "stringVar": "this is multi-line\r\n  string with formatting\r\n  preserved.\r\n"
}

Déclarations sur plusieurs lignes

Vous pouvez maintenant utiliser plusieurs lignes dans les déclarations de fonction, de tableau et d’objet. Cette fonctionnalité nécessite Bicep CLI version 0.7.X ou supérieure.

Dans l’exemple suivant, la définition resourceGroup() est répartie sur plusieurs lignes.

var foo = resourceGroup(
  mySubscription,
  myRgName)

Consultez Tableaux et Objets pour obtenir des exemples de déclaration sur plusieurs lignes.

Limitations connues

Aucun support pour le concept d’apiProfile utilisé pour mapper un apiProfile à une apiVersion définie pour chaque type de ressource.
Les fonctions définies par l’utilisateur ne sont pas prises en charge pour le moment. Toutefois, une fonctionnalité expérimentale est actuellement accessible. Pour plus d’informations, consultez Fonctions définies par l’utilisateur dans Bicep.
Certaines fonctionnalités Bicep nécessitent une modification correspondante de la langue intermédiaire (modèles JSON Azure Resource Manager). Nous annonçons ces fonctionnalités comme étant disponibles lorsque toutes les mises à jour requises ont été déployées dans Azure global. Si vous utilisez un environnement différent, tel qu’Azure Stack, la disponibilité de la fonctionnalité peut être retardée. La fonctionnalité Bicep n’est disponible que lorsque la langue intermédiaire a également été mise à jour dans cet environnement.

Étapes suivantes

Pour une présentation de Bicep, consultez Qu’est-ce que Bicep ? Pour les types de données Bicep, consultez Types de données.

Partage via

Comprendre la structure et la syntaxe des fichiers Bicep

Format Bicep

Métadonnées

Étendue cible

Décorateurs

Paramètres

Variables

Types

Functions

Ressources

Modules

Outputs

Boucles

Déploiement conditionnel

Espace blanc

Commentaires

Chaînes à lignes multiples

Déclarations sur plusieurs lignes

Limitations connues

Étapes suivantes

Commentaires

Ressources supplémentaires