Nociones sobre la estructura y la sintaxis de los archivos Bicep

Artículo
08/31/2024

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.

@<decorator>(<argument>)
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>
  }
}

@<decorator>(<argument>)
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@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
  }
}

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.

Elementos Decorator

Puede agregar uno o varios decoradores para cada uno de los siguientes elementos:

param
var
Recurso
module
output
func
type

Los decoradores incluyen:

Decorador	Aplicar al elemento	Aplicar al tipo de datos	Argumento	Descripción
allowed	param	all	array	Use este decorador para asegurarse de que el usuario proporciona los valores correctos. Este decorador solo se permite en instrucciones `param`. Para declarar que una propiedad debe ser uno de un conjunto de valores predefinidos en una instrucción`type` o `output`, use la sintaxis de tipo de unión. La sintaxis de tipo de unión también se puede usar en instrucciones `param`.
batchSize	módulo, recurso	N/D	integer	Configure instancias para implementarlas secuencialmente.
descripción	func, param, módulo, output, recurso, tipo, var	all	string	Proporcione descripciones para los elementos. El texto con formato Markdown se puede usar para el texto de descripción.
discriminator	param, type, output	objeto	string	Use este decorador para asegurarse de que la subclase correcta se identifica y administra. Para obtener más información, vea Tipo de datos de unión etiquetado personalizado.
exportar	func, tipo, var	all	None	Indica que otro archivo de Bicep puede importar el elemento.
maxLength	param, output, tipo	array, string	int	Longitud máxima de los elementos de cadena y matriz. El valor es inclusivo.
maxValue	param, output, tipo	int	int	El valor máximo para los elementos de enteros. Este valor es inclusivo.
metadata	func, output, param, tipo	all	objeto	Propiedades personalizadas que se aplicarán a los elementos. Pueden incluir una propiedad de descripción equivalente al decorador de la descripción.
minLength	param, output, tipo	array, string	int	La longitud mínima para los elementos de cadenas y matrices. El valor es inclusivo.
minValue	param, output, tipo	int	int	El valor mínimo para los elementos de enteros. Este valor es inclusivo.
sealed	param, type, output	objeto	None	Eleve BCP089 de una advertencia a un error cuando es probable que un nombre de propiedad de un tipo de datos use-define sea un error tipográfico. Para obtener más información, consulte Elevación del nivel de error.
secure	param, tipo	string, object	ninguno	Marca el parámetro como seguro. El valor de un parámetro seguro no se guarda en el historial de implementaciones y no se registra. Para más información, consulte Protección de cadenas y objetos.

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
}

Puede agregar uno o varios decoradores para cada parámetro. Para obtener más información, consulte Usar decoradores.

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

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

Puede agregar uno o varios decoradores para cada variable. Para obtener más información, consulte Usar decoradores.

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

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

Puede agregar uno o varios decoradores para cada tipo de datos definido por el usuario. Para obtener más información, consulte Usar decoradores.

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

Funciones

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.

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

Puede agregar uno o varios decoradores para cada recurso. Para obtener más información, consulte Usar decoradores.

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@2023-04-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@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
}

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.

Puede agregar uno o varios decoradores para cada módulo. Para obtener más información, consulte Usar decoradores.

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

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

Puede agregar uno o varios decoradores para cada salida. Para obtener más información, consulte Usar decoradores.

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@2023-07-01-preview' = 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@2023-04-01' = if (newOrExisting == 'new') {
  ...
}

No se puede escribir como:

resource sa 'Microsoft.Storage/storageAccounts@2023-04-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@2023-11-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.

Compartir a través de

Nociones sobre la estructura y la sintaxis de los archivos Bicep

Formato de Bicep

Metadatos

Ámbito de destino

Elementos Decorator

Parámetros

Variables

Tipos

Funciones

Recursos

Módulos

Salidas

Bucles

Implementación condicional

Espacio en blanco

Comentarios

Cadenas de varias líneas

Declaraciones de varias líneas

Restricciones conocidas

Pasos siguientes

Comentarios

Recursos adicionales