Conocimiento de los parámetros

• 8 minutos

Con los parámetros, puede proporcionar información a una plantilla de Bicep en el momento de la implementación. Puede hacer que una plantilla de Bicep sea flexible y reutilizable mediante la declaración de parámetros dentro de la plantilla.

Los decoradores proporcionan una manera de adjuntar restricciones y metadatos a un parámetro, lo que ayuda a cualquier persona que use sus plantillas a comprender qué información es necesario proporcionar.

En esta unidad, obtendrá información sobre los parámetros y los decoradores.

Declaración de un parámetro

En una plantilla de Bicep, declare un parámetro mediante la palabra clave param. Puede colocar estas declaraciones en cualquier lugar del archivo de la plantilla, aunque normalmente es conveniente colocarlas en la parte superior del archivo para que el código Bicep sea fácil de leer.

Este es el modo en que se declara un parámetro:

param environmentName string

Veamos cómo funciona cada parte:

• param indica a Bicep que está declarando un parámetro.

• environmentName se refiere al nombre del parámetro. Aunque puede asignar cualquier nombre al parámetro, este debe ser claro y comprensible para los usuarios de la plantilla. Dentro de la misma plantilla, también puede hacer referencia al parámetro mediante su nombre. Los nombres de los parámetros deben ser únicos. No pueden tener el mismo nombre que una variable o un recurso en el mismo archivo de Bicep.

  Sugerencia

  Use las convenciones de nomenclatura recomendadas para las declaraciones de parámetros. Las convenciones de nomenclatura adecuadas permiten que las plantillas se lean y se comprendan fácilmente. Asegúrese de usar nombres claros y descriptivos y adopte una estrategia de nomenclatura coherente.

• string se refiere al tipo de parámetro.

  Sugerencia

  Piense detenidamente en los parámetros que usa la plantilla. Intente usar parámetros para la configuración que cambia entre las implementaciones. Las variables y los valores codificados de forma rígida se pueden usar para la configuración que no cambia entre las implementaciones.

Adición de un valor predeterminado

Puede asignar valores predeterminados a los parámetros en las plantillas. Al asignar un valor predeterminado, el parámetro se convierte en opcional. Si la plantilla se implementa sin un valor especificado para el parámetro, se asigna el valor predeterminado.

Aquí se muestra cómo agregar un valor predeterminado:

param environmentName string = 'dev'

Al parámetro environmentName se le asigna un valor predeterminado de dev.

Puede usar expresiones como valores predeterminados. Este es un ejemplo de un parámetro de cadena denominado location con un valor predeterminado establecido en la ubicación del grupo de recursos actual:

param location string = resourceGroup().location

Información sobre los tipos de parámetros

Al declarar un parámetro, debe indicar a Bicep qué tipo de información contendrá el parámetro. Bicep garantizará que el valor asignado al parámetro sea compatible con el tipo de parámetro.

Los parámetros de Bicep pueden ser de alguno de los siguientes tipos:

• string, que permite escribir texto arbitrario.
• int, que permite escribir un número.
• bool, que representa un valor booleano (true o false).
• object y array, que representan listas y datos estructurados.

Objetos

Puede usar parámetros de objeto para combinar datos estructurados en un solo lugar. Un objeto puede tener varias propiedades de tipos diferentes. Puede usar objetos dentro de definiciones de recursos, dentro de variables o dentro de expresiones en el archivo de Bicep. Este es un ejemplo de un objeto:

param appServicePlanSku object = {
  name: 'F1'
  tier: 'Free'
  capacity: 1
}

Este parámetro es un objeto con dos propiedades de cadena, name y tier, y una propiedad de entero, capacity. Observe que cada una de las propiedades está en su propia línea.

Al hacer referencia al parámetro en la plantilla, puede seleccionar las propiedades individuales del objeto mediante un punto seguido del nombre de la propiedad, como en este ejemplo:

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku.name
    tier: appServicePlanSku.tier
    capacity: appServicePlanSku.capacity
  }
}

Otro ejemplo de dónde podría usar un parámetro de objeto es para especificar etiquetas de recursos. Puede adjuntar metadatos de etiqueta personalizados a los recursos que implemente, que puede usar para identificar información importante sobre un recurso.

Las etiquetas son útiles para escenarios como el seguimiento de qué equipo posee un recurso o cuándo un recurso pertenece a un entorno de producción o que no es de producción. Normalmente, usará etiquetas diferentes para cada entorno, pero querrá reutilizar los mismos valores de etiqueta en todos los recursos de la plantilla. Por este motivo, las etiquetas de recursos son muy convenientes para un parámetro de objeto, como en este ejemplo:

param resourceTags object = {
  EnvironmentName: 'Test'
  CostCenter: '1000100'
  Team: 'Human Resources'
}

Siempre que defina un recurso en el archivo de Bicep, puede reutilizarlo siempre que defina la propiedad tags:

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  tags: resourceTags
  sku: {
    name: 'S1'
  }
}

resource appServiceApp 'Microsoft.Web/sites@' = {
  name: appServiceAppName
  location: location
  tags: resourceTags
  kind: 'app'
  properties: {
    serverFarmId: appServicePlan.id
  }
}

Matrices

Una matriz es una lista de elementos. Por ejemplo, puede usar una matriz de valores de cadena para declarar una lista de direcciones de correo electrónico para un grupo de acciones de Azure Monitor. O bien, puede usar una matriz de objetos para representar una lista de subredes para una red virtual.

Veamos un ejemplo. Azure Cosmos DB permite crear cuentas de base de datos que abarcan varias regiones y controla automáticamente la replicación de datos. Al implementar una nueva cuenta de base de datos, debe especificar la lista de regiones de Azure en las que desea implementar la cuenta. A menudo, deberá tener una lista diferente de ubicaciones para distintos entornos. Por ejemplo, para ahorrar dinero en el entorno de prueba, puede usar solo una o dos ubicaciones. Sin embargo, en el entorno de producción, puede usar varias ubicaciones.

Puede crear un parámetro de matriz que especifique una lista de ubicaciones:

param cosmosDBAccountLocations array = [
  {
    locationName: 'australiaeast'
  }
  {
    locationName: 'southcentralus'
  }
  {
    locationName: 'westeurope'
  }
]

Al declarar el recurso de Azure Cosmos DB, ya puede hacer referencia al parámetro de matriz:

resource account 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  name: accountName
  location: location
  properties: {
    locations: cosmosDBAccountLocations
  }
}

De esta forma, es fácil usar un valor de parámetro diferente para el entorno de desarrollo cambiando el valor del parámetro. Pronto aprenderá a proporcionar valores de parámetros diferentes sin modificar la plantilla original.

Definición de una lista de valores permitidos

A veces, debe asegurarse de que un parámetro tiene determinados valores. Por ejemplo, el equipo podría decidir que los planes de App Service de producción se deben implementar mediante las SKU Prémium v3. Para aplicar esta regla, puede usar el decorador de parámetros @allowed. Un decorador de parámetros es una manera de proporcionar información de Bicep sobre cuál debe ser el valor de un parámetro. Aquí se muestra cómo se puede restringir un parámetro de cadena denominado appServicePlanSkuName para que solo se puedan asignar algunos valores específicos:

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
param appServicePlanSkuName string

Restricción de la longitud y los valores de los parámetros

Cuando se usan parámetros de cadena, a menudo es necesario limitar la longitud de la cadena. Veamos el ejemplo de nomenclatura de recursos de Azure. Todos los tipos de recursos de Azure tienen límites en la longitud de sus nombres. Es una buena práctica especificar la longitud mínima y máxima de caracteres para los parámetros que controlan la nomenclatura, a fin de evitar errores más adelante durante la implementación. Puede usar los decoradores @minLength y @maxLength para las longitudes mínima y máxima de caracteres que desea admitir para un parámetro.

Este es un ejemplo que declara un parámetro de cadena denominado storageAccountName, cuya longitud solo puede ser de entre 5 y 24 caracteres:

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

Este parámetro incluye dos decoradores. Puede aplicar varios decoradores a un parámetro mediante la colocación de cada decorador en su propia línea.

Cuando trabaje con parámetros numéricos, puede que necesite que los valores se encuentren dentro de un intervalo determinado. Por ejemplo, la empresa de juguetes podría decidir que cada vez que alguien implemente un plan de App Service, siempre debe implementar al menos una instancia, pero no más de 10 instancias del plan. Para cumplir los requisitos, puede usar los decoradores @minValue y @maxValue para especificar los valores mínimo y máximo permitidos. En el ejemplo siguiente se declara el parámetro entero appServicePlanInstanceCount cuyo valor solo puede estar entre 1 y 10 (ambos inclusive):

@minValue(1)
@maxValue(10)
param appServicePlanInstanceCount int

Adición de descripciones a los parámetros

Los parámetros son ideales para permitir que otras personas puedan reutilizar las plantillas. Cuando usen las plantillas, necesitarán saber lo que hace cada parámetro para que puedan proporcionar los valores correctos. Bicep proporciona el decorador @description para que pueda documentar el propósito de los parámetros de una manera legible.

@description('The locations into which this Cosmos DB account should be configured. This parameter needs to be a list of objects, each of which has a locationName property.')
param cosmosDBAccountLocations array

Es conveniente proporcionar descripciones de los parámetros. Intente que las descripciones sean útiles y proporcione información importante sobre lo que la plantilla necesita que sean los valores de parámetros.