Nociones sobre la estructura y la sintaxis de los archivos Bicep

En este artículo se describen la estructura y la sintaxis de un archivo Bicep. Presenta las distintas secciones del archivo y las propiedades que están disponibles en esas secciones.

Para obtener un tutorial paso a paso que le guía por el proceso de creación de un archivo de Bicep, consulte Inicio rápido: Creación de plantillas de archivos de Bicep con Visual Studio Code.

Formato de Bicep

Bicep es un lenguaje declarativo, lo que significa que los elementos pueden aparecer en cualquier orden. A diferencia de los lenguajes imperativos, el orden de los elementos no afecta a cómo se procesa la implementación.

Un archivo Bicep contiene los elementos siguientes.

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>

En el ejemplo siguiente se muestra una implementación de estos elementos.

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

Metadatos

Los metadatos de Bicep son un valor sin tipo que se puede incluir en los archivos de Bicep. Le permite proporcionar información complementaria sobre los archivos de Bicep, incluidos detalles como nombre, descripción, autor, fecha de creación, etc.

Ámbito de destino

De manera predeterminada, el ámbito de destino está establecido en resourceGroup. Si va a realizar la implementación en el nivel de grupo de recursos, no es necesario establecer el ámbito de destino en el archivo Bicep.

Los valores permitidos son:

• resourceGroup: valor predeterminado que se usa para las implementaciones de grupos de recursos.
• subscription: se usa para las implementaciones de suscripciones.
• managementGroup: se usa para las implementaciones de grupos de administración.
• tenant: se usa para las implementaciones de inquilinos.

En un módulo, puede especificar un ámbito que sea diferente del ámbito para el resto del archivo de Bicep. Para más información, consulte Configuración del ámbito de módulo.

Tipos

Puedes usar la instrucción type para definir tipos de datos definidos por el usuario.

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

Para obtener más información, consulte Tipos de datos definidos por el usuario.

Functions (versión preliminar)

Nota:

Para habilitar la característica en versión preliminar, consulte Habilitación de características experimentales.

En el archivo de Bicep, puede crear sus propias funciones además de usar las funciones estándar de Bicep que están disponibles automáticamente en los archivos de Bicep. Cree sus propias funciones cuando tenga expresiones complicadas que se usen repetidamente en los archivos de 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')

Para más información, consulte Funciones definidas por el usuario.

Parámetros

Use los parámetros para los valores que deben variar en las distintas implementaciones. Puede definir un valor predeterminado para el parámetro que se usa si no se proporciona ningún valor durante la implementación.

Por ejemplo, puede agregar un parámetro de SKU para especificar diferentes tamaños para un recurso. Puede pasar valores diferentes en función de si va a realizar la implementación en prueba o en producción.

param storageSKU string = 'Standard_LRS'

El parámetro está disponible para su uso en el archivo Bicep.

sku: {
  name: storageSKU
}

Para más información, consulte Parámetros en Bicep.

Decoradores de parámetro

Puede agregar uno o varios decoradores para cada parámetro. Estos decoradores describen el parámetro y definen restricciones para los valores que se pasan. En el ejemplo siguiente se muestra un decorador, pero hay muchos otros disponibles.

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

Para más información, incluidas las descripciones de todos los decoradores disponibles, consulte Elementos Decorator.

Variables

Puede hacer que el archivo Bicep sea más legible encapsulando expresiones complejas en una variable. Por ejemplo, puede agregar una variable para un nombre de recurso que se construye mediante la concatenación de varios valores.

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

Aplique esta variable siempre que necesite la expresión compleja.

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

Para más información, consulte Variables en Bicep.

Recursos

Use la palabra clave resource para definir un recurso que se va a implementar. La declaración de recursos incluye un nombre simbólico para el recurso. Se utiliza este nombre simbólico en otras partes del archivo Bicep para obtener un valor del recurso.

La declaración de recursos incluye el tipo de recurso y la versión de la API. Dentro del cuerpo de la declaración de recurso, incluya propiedades específicas del tipo de recurso.

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

Para más información, consulte Declaración de recursos en Bicep.

Algunos recursos tienen una relación de elementos primarios y secundarios. Puede definir un recurso secundario dentro del recurso primario o fuera de él.

En el ejemplo siguiente se muestra cómo definir un recurso secundario dentro de un recurso primario. Contiene una cuenta de almacenamiento con un recurso secundario (servicio de archivos) que se define dentro de la cuenta de almacenamiento. El servicio de archivos también tiene un recurso secundario (recurso compartido) que se define dentro de él.

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

En el ejemplo siguiente se muestra cómo definir el recurso secundario fuera del recurso primario. Use la propiedad primaria para identificar una relación de recursos primarios y secundarios. Se definen los mismos tres recursos.

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
}

Para más información, consulte el artículo sobre cómo establecer el nombre y el tipo de recursos secundarios en Bicep.

Módulos

Los módulos permiten reutilizar el código de un archivo Bicep en otros archivos Bicep. En la declaración del módulo, se vincula al archivo que va a reutilizar. Al implementar el archivo Bicep, también se implementan los recursos del módulo.

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

El nombre simbólico le permite hacer referencia al módulo desde otro lugar del archivo. Por ejemplo, puede obtener un valor de salida de un módulo mediante el uso del nombre simbólico y el nombre del valor de salida.

Para más información, consulte Uso de módulos de Bicep.

Decoradores de recursos y módulos

Puede agregar un decorador a una definición de recurso o de módulo. Los decoradores admitidos son batchSize(int) y description. Solo puede aplicarlo a una definición de recurso o de módulo que usa una expresión for.

De manera predeterminada, los recursos se implementan en paralelo. Cuando agrega el decorador batchSize(int), implementa las instancias en serie.

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

Para más información, consulte Implementación en lotes.

Salidas

Use las salidas para devolver unos valores a partir de la implementación. Por lo general, se devuelve un valor desde un recurso implementado cuando es necesario volver a utilizar ese valor para otra operación.

output storageEndpoint object = stg.properties.primaryEndpoints

Para más información, consulte Salidas en Bicep.

Bucles

Puede agregar bucles iterativos al archivo Bicep para definir varias copias de lo siguiente:

• resource
• module
• variable
• propiedad
• output

Utilice la expresión for para definir un bucle.

param moduleCount int = 2

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

Puede recorrer en iteración una matriz, un objeto o un índice de enteros.

Para más información, consulte Bucles iterativos en Bicep.

Implementación condicional

Puede agregar un recurso o módulo al archivo Bicep, que se implementa condicionalmente. Durante la implementación, se evalúa la condición, y el resultado determina si se implementa el recurso o el módulo. Utilice la expresión if para definir una implementación condicional.

param deployZone bool

resource dnsZone 'Microsoft.Network/dnszones@2018-05-01' = if (deployZone) {
  name: 'myZone'
  location: 'global'
}

Para obtener más información, consulte Implementación condicional en Bicep.

Espacio en blanco

Los espacios y las pestañas se omiten al crear archivos de Bicep.

Bicep diferencia las nuevas líneas. Por ejemplo:

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

No se puede escribir como:

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

Defina objetos y matrices en varias líneas.

Comentarios

Use // para los comentarios de una sola línea o /* ... */ para los comentarios de varias líneas.

En el ejemplo siguiente, se muestra un comentario de una sola línea.

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

En el ejemplo siguiente, se muestra un comentario de varias líneas.

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

Cadenas de varias líneas

Una cadena se puede dividir en varias líneas. Use tres caracteres de comillas simples ''' para iniciar y finalizar la cadena multilínea.

Los caracteres de la cadena multilínea se controlan tal cual. No se necesitan caracteres de escape. No se puede incluir ''' en la cadena multilínea. Actualmente, no se admite la interpolación de cadenas.

Puede iniciar la cadena justo después de las ''' de apertura, o bien incluir una línea nueva. Cualquiera sea el caso, la cadena resultante no incluye una línea nueva. En función de cómo finalizan las líneas en el archivo Bicep, las líneas nuevas se interpretan como \r\n o \n.

En el ejemplo siguiente, se muestra una cadena multilínea.

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

El ejemplo anterior es equivalente al JSON siguiente.

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

Declaraciones de varias líneas

Ahora puede usar varias líneas en las declaraciones de función, matriz y objeto. Para esta característica se necesita la versión 0.7.X o posterior de la CLI de Bicep.

En el ejemplo siguiente, la definición resourceGroup() se divide en varias líneas.

var foo = resourceGroup(
  mySubscription,
  myRgName)

Consulte Matrices y Objetos para ejemplos de declaración en varias líneas.

Restricciones conocidas

• No se admite el concepto de apiProfile, que se usa para asignar un único apiProfile a un valor de apiVersion establecido para cada tipo de recurso.
• Las funciones definidas por el usuario no se admiten en este momento. Sin embargo, actualmente se puede acceder a una característica experimental. Para más información, consulte Funciones definidas por el usuario en Bicep.
• Algunas características de Bicep requieren un cambio correspondiente al lenguaje intermedio (plantillas JSON de Azure Resource Manager). Anunciamos estas características como disponibles cuando todas las actualizaciones necesarias se han implementado en Azure global. Si usa un entorno diferente, como Azure Stack, puede que haya un retraso en la disponibilidad de la característica. La característica de Bícep solo está disponible cuando el lenguaje intermedio también se ha actualizado en ese entorno.

Pasos siguientes

Si necesita una introducción a Bicep, consulte ¿Qué es Bicep? Para los tipos de datos de Bicep, consulte Tipos de datos.