Parámetros en Bicep

En este artículo se describe cómo definir y usar parámetros en un archivo Bicep. Si proporciona valores diferentes para los parámetros, podrá volver a usar un archivo Bicep para distintos entornos.

Resource Manager resuelve los valores de parámetro antes de iniciar las operaciones de implementación. Siempre que se use el parámetro, Resource Manager lo reemplaza por el valor resuelto.

Cada parámetro debe establecerse en uno de los tipos de datos.

Tiene un límite de 256 parámetros en un archivo Bicep. Para obtener más información, consulte Límites de plantilla.

Para conocer los procedimientos recomendados de parámetros, consulte Parámetros.

Recursos de aprendizaje

Si prefiere información sobre los parámetros mediante instrucciones paso a paso, consulte Creación de plantillas de Bicep reutilizables mediante parámetros.

Declaración

Cada parámetro tiene un nombre y un tipo de datos. Opcionalmente, puede proporcionar un valor predeterminado para el parámetro.

param <parameter-name> <parameter-data-type> = <default-value>

Un parámetro no puede tener el mismo nombre que una variable, recurso, salida u otro parámetro en el mismo ámbito.

En el ejemplo siguiente se muestran declaraciones básicas de parámetros.

param demoString string
param demoInt int
param demoBool bool
param demoObject object
param demoArray array

La palabra clave param se usa también en archivos .bicepparam. En los archivos .bicepparam, no es necesario especificar el tipo de datos tal como se define en los archivos de Bicep.

param <parameter-name> = <value>

Para obtener más información, consulte Archivo de parámetros.

Las expresiones de tipo definidas por el usuario se pueden usar como cláusula tipo de una instrucción param. Por ejemplo:

param storageAccountConfig {
  name: string
  sku: string
}

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

Valor predeterminado

Puede especificar un valor predeterminado para un parámetro. El valor predeterminado se usa cuando no se proporciona un valor durante la implementación.

param demoParam string = 'Contoso'

Puede usar expresiones con el valor predeterminado. No se permiten expresiones con otras propiedades de parámetro. La función no puede usar la función reference ni ninguna de las funciones list de la sección de parámetros. Estas funciones obtienen el estado del runtime del recurso y no se pueden ejecutar antes de la implementación cuando se resuelven parámetros.

param location string = resourceGroup().location

Puede usar otro valor de parámetro para compilar un valor predeterminado. La plantilla siguiente crea un nombre de plan de host a partir del nombre del sitio.

param siteName string = 'site${uniqueString(resourceGroup().id)}'
param hostingPlanName string = '${siteName}-plan'

output siteNameOutput string = siteName
output hostingPlanOutput string = hostingPlanName

Elementos Decorator

Los parámetros usan decoradores para restricciones o metadatos. Los decoradores tienen el formato @expression y se colocan encima de la declaración del parámetro. Puede marcar un parámetro como seguro, especificar los valores permitidos, establecer la longitud mínima y máxima de una cadena, establecer el valor mínimo y máximo de un entero y proporcionar una descripción del parámetro.

En el ejemplo siguiente, se muestran dos usos comunes de los decoradores.

@secure()
param demoPassword string

@description('Must be at least Standard_A3 to support 2 NICs.')
param virtualMachineSize string = 'Standard_DS1_v2'

En la tabla siguiente se describen los decoradores disponibles y cómo usarlos.

Decorador	Aplicar a	Argumento	Descripción
permitidas	all	array	Valores permitidos para el parámetro. Use este decorador para asegurarse de que el usuario proporciona los valores correctos.
description	all	string	Texto que explica cómo usar el parámetro. La descripción se muestra a los usuarios a través del portal.
maxLength	array, string	int	Longitud máxima de los parámetros de cadena y matriz. El valor es inclusivo.
maxValue	int	int	Valor máximo del parámetro entero. Este valor es inclusivo.
metadata	all	object	Propiedades personalizadas que se van a aplicar al parámetro. Pueden incluir una propiedad de descripción equivalente al decorador de la descripción.
minLength	array, string	int	Longitud mínima de los parámetros de cadena y matriz. El valor es inclusivo.
minValue	int	int	Valor mínimo del parámetro entero. Este valor es inclusivo.
secure	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.

Los decoradores están en el espacio de nombres sys. Si tiene que diferenciar un decorador de otro elemento con el mismo nombre, anteceda el decorador con sys. Por ejemplo, si el archivo de Bicep incluye un parámetro llamado description, debe agregar el espacio de nombres sys al usar el decorador description.

@sys.description('The name of the instance.')
param name string
@sys.description('The description of the instance to display.')
param description string

Los decoradores disponibles se describen en las secciones siguientes.

Parámetros seguros

Puede marcar los parámetros de objeto o cadena como seguros. El valor de un parámetro seguro no se guarda en el historial de implementaciones y no se registra.

@secure()
param demoPassword string

@secure()
param demoSecretObject object

Valores permitidos

Puede definir valores permitidos para un parámetro. Los valores permitidos se proporcionan en una matriz. Se produce un error en la implementación durante la validación si se pasa un valor para el parámetro que no es uno de los valores permitidos.

@allowed([
  'one'
  'two'
])
param demoEnum string

Si define los valores permitidos para un parámetro de matriz, el valor real puede ser cualquier subconjunto de los valores permitidos.

Restricciones de longitud

Puede especificar la longitud mínima y máxima de los parámetros de matriz y de cadena. Puede establecer una o las dos restricciones. Para las cadenas, la longitud indica el número de caracteres. Para las matrices, la longitud indica el número de elementos de la matriz.

En el ejemplo siguiente se declaran dos parámetros. Un parámetro es para un nombre de cuenta de almacenamiento que debe tener entre 3 y 24 caracteres. El otro parámetro es una matriz que debe tener entre 1 y 5 elementos.

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

@minLength(1)
@maxLength(5)
param appNames array

Restricciones de enteros

Puede establecer valores mínimos y máximos para los parámetros de entero. Puede establecer una o las dos restricciones.

@minValue(1)
@maxValue(12)
param month int

Descripción

Para ayudar a los usuarios a comprender el valor que se debe proporcionar, agregue una descripción al parámetro. Cuando un usuario implementa la plantilla mediante el portal, el texto de la descripción se utiliza automáticamente como sugerencia para ese parámetro. Agregue solo una descripción cuando el texto proporcione más información de la que se puede deducir del nombre del parámetro.

@description('Must be at least Standard_A3 to support 2 NICs.')
param virtualMachineSize string = 'Standard_DS1_v2'

El texto con formato Markdown se puede usar para el texto de descripción:

@description('''
Storage account name restrictions:
- Storage account names must be between 3 and 24 characters in length and may contain numbers and lowercase letters only.
- Your storage account name must be unique within Azure. No two storage accounts can have the same name.
''')
@minLength(3)
@maxLength(24)
param storageAccountName string

Si mantiene el cursor sobre storageAccountName en VS Code, verá el texto con formato:

Asegúrese de que el texto sigue el formato correcto de Markdown; de lo contrario, es posible que no se muestre correctamente cuando se represente

Metadatos

Si tiene propiedades personalizadas que desea aplicar a un parámetro, agregue un decorador de metadatos. Dentro de los metadatos, defina un objeto con los nombres y valores personalizados. El objeto que defina para los metadatos puede contener propiedades de cualquier nombre y tipo.

Puede utilizar este decorador para realizar un seguimiento de la información sobre el parámetro que no tiene sentido agregar a la descripción.

@description('Configuration values that are applied when the application starts.')
@metadata({
  source: 'database'
  contact: 'Web team'
})
param settings object

Cuando se proporciona un decorador @metadata() con una propiedad que está en conflicto con otro decorador, ese decorador siempre tiene prioridad sobre cualquier elemento del decorador @metadata(). Por tanto, la propiedad en conflicto dentro del valor @metadata() es redundante y se reemplazará. Para obtener más información, consulte Regla de linter: no-conflicting-metadata.

Uso del parámetro

Para hacer referencia al valor de un parámetro, use el nombre del parámetro. En el ejemplo siguiente se usa un valor de parámetro para un nombre de almacén de claves.

param vaultName string = 'keyVault${uniqueString(resourceGroup().id)}'

resource keyvault 'Microsoft.KeyVault/vaults@2019-09-01' = {
  name: vaultName
  ...
}

Objetos como parámetros

Puede ser más fácil organizar los valores relacionados pasándolos como objetos. Con este enfoque también se reduce el número de parámetros de la plantilla.

En el ejemplo siguiente se muestra un parámetro que es un objeto. El valor predeterminado muestra las propiedades esperadas para el objeto. Esas propiedades se usan al definir el recurso que se va a implementar.

param vNetSettings object = {
  name: 'VNet1'
  location: 'eastus'
  addressPrefixes: [
    {
      name: 'firstPrefix'
      addressPrefix: '10.0.0.0/22'
    }
  ]
  subnets: [
    {
      name: 'firstSubnet'
      addressPrefix: '10.0.0.0/24'
    }
    {
      name: 'secondSubnet'
      addressPrefix: '10.0.1.0/24'
    }
  ]
}

resource vnet 'Microsoft.Network/virtualNetworks@2020-06-01' = {
  name: vNetSettings.name
  location: vNetSettings.location
  properties: {
    addressSpace: {
      addressPrefixes: [
        vNetSettings.addressPrefixes[0].addressPrefix
      ]
    }
    subnets: [
      {
        name: vNetSettings.subnets[0].name
        properties: {
          addressPrefix: vNetSettings.subnets[0].addressPrefix
        }
      }
      {
        name: vNetSettings.subnets[1].name
        properties: {
          addressPrefix: vNetSettings.subnets[1].addressPrefix
        }
      }
    ]
  }
}

Pasos siguientes

• Para más información sobre las propiedades disponibles para parámetros, consulte Nociones sobre la estructura y la sintaxis de los archivos Bicep.
• Para más información sobre cómo pasar valores de parámetro como un archivo, consulte Creación de un archivo de parámetros de Bicep.
• Para obtener más información sobre cómo proporcionar valores de parámetro en la implementación, consulte Implementación con la CLI de Azure e Implementación con Azure PowerShell.