Comprendre la structure et la syntaxe des fichiers Bicep

  • Article

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>'

type <user-defined-data-type-name> = <type-expression>

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>

var <variable-name> = <variable-value>

resource <resource-symbolic-name> '<resource-type>@<api-version>' = {
  <resource-properties>
}

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@2022-09-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 :

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

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@2022-09-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

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

Fonctions (préversion)

Remarque

Pour activer la fonctionnalité en préversion, consultez Activer les fonctionnalités expérimentales.

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.

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
}

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

Éléments décoratifs de paramètres

Vous pouvez ajouter un ou plusieurs éléments décoratifs pour chaque paramètre. Ces décorateurs décrivent le paramètre et définissent des contraintes pour les valeurs qui sont passées. L’exemple suivant montre un décorateur, mais de nombreux autres sont disponibles.

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageSKU string = 'Standard_LRS'

Pour plus d’informations, y compris les descriptions de tous les décorateurs disponibles, consultez Décorateurs.

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@2019-04-01' = {
  name: uniqueStorageName

Pour plus d’informations, consultez Variables dans Bicep.

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@2019-06-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

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@2022-09-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@2022-09-01' = {
  name: 'examplestorage'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

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

resource share 'Microsoft.Storage/storageAccounts/fileServices/shares@2022-09-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.

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

Éléments décoratifs de ressources et de modules

Vous pouvez ajouter un élément décoratif à une définition de ressource ou de module. Les éléments décoratifs pris en charge sont batchSize(int) et description. Vous pouvez uniquement l’appliquer à une définition de ressource ou de module qui utilise une expression for.

Par défaut, les ressources sont déployées en parallèle. Lorsque vous ajoutez l’élément décoratif batchSize(int), vous déployez des instances en série.

@batchSize(3)
resource storageAccountResources 'Microsoft.Storage/storageAccounts@2019-06-01' = [for storageName in storageAccounts: {
  ...
}]

Pour plus d’informations, consultez Déployer par lots.

Sorties

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

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@2018-05-01' = 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@2019-06-01' = if (newOrExisting == 'new') {
  ...
}

Ne peut pas être écrit sous la forme :

resource sa 'Microsoft.Storage/storageAccounts@2019-06-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@2020-06-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.