Tipos de datos definidos por el usuario en Bicep

Aprende a crear tipos de datos definidos por el usuario en Bicep. Para los tipos de datos definidos por el sistema, consulte Tipos de datos. El uso de tipos de datos definidos por el usuario permite generar automáticamente código de la versión 2.0 del lenguaje.

Para usar esta característica se necesita la versión 0.12.X o posterior de la CLI de Bicep.

Definición de tipos

Puede usar la instrucción type para crear tipos de datos definidos por el usuario. También puede usar expresiones de tipo en algunos lugares para definir tipos personalizados.

@<decorator>(<argument>)
type <user-defined-data-type-name> = <type-expression>

El decorador @allowed solo se permite eninstrucciones param. Para declarar un tipo con un conjunto de valores predefinidos en un type, use sintaxis de tipo de unión.

Las expresiones de tipo válidas incluyen:

• Las referencias simbólicas son identificadores que hacen referencia a un tipo ambiente (como string o int) o a un símbolo de tipo definido por el usuario declarado en una instrucción type:

  // Bicep data type reference
  type myStringType = string
  
  // user-defined type reference
  type myOtherStringType = myStringType
  

• Los literales primitivos, incluidas las cadenas, los enteros y los booleanos, son expresiones de tipo válidas. Por ejemplo:

  // a string type with three allowed values.
  type myStringLiteralType = 'bicep' | 'arm' | 'azure'
  
  // an integer type with one allowed value
  type myIntLiteralType = 10
  
  // an boolean type with one allowed value
  type myBoolLiteralType = true
  

• Puede declarar tipos de matriz anexando [] a cualquier expresión de tipo válida:

  // A string type array
  type myStrStringsType1 = string[]
  // A string type array with three allowed values
  type myStrStringsType2 = ('a' | 'b' | 'c')[]
  
  type myIntArrayOfArraysType = int[][]
  
  // A mixed-type array with four allowed values
  type myMixedTypeArrayType = ('fizz' | 42 | {an: 'object'} | null)[]
  

• Los tipos de objeto contienen cero o más propiedades entre corchetes:

  type storageAccountConfigType = {
    name: string
    sku: string
  }
  

  Cada propiedad de un objeto consta de una clave y un valor, separados por dos puntos :. La clave puede ser cualquier cadena, con valores no identificadores entre comillas. El valor puede ser cualquier tipo de expresión.

  Las propiedades son necesarias a menos que tengan un marcador de opcionalidad ? después del nombre de propiedad y los dos puntos. Por ejemplo, la propiedad sku del ejemplo siguiente es opcional:

  type storageAccountConfigType = {
    name: string
    sku: string?
  }
  

  Puede usar decoradores en propiedades. Puede usar un asterisco (*) para hacer que todos los valores requieran una restricción. Puede definir más propiedades mediante *. En este ejemplo se crea un objeto que requiere una clave de tipo int denominada id. Todas las demás entradas del objeto deben ser un valor de cadena de al menos 10 caracteres de longitud.

  type obj = {
    @description('The object ID')
    id: int
  
    @description('Additional properties')
    @minLength(10)
    *: string
  }
  

  En el ejemplo siguiente se muestra cómo usar la sintaxis de tipo de unión para enumerar un conjunto de valores predefinidos:

  type directions = 'east' | 'south' | 'west' | 'north'
  
  type obj = {
    level: 'bronze' | 'silver' | 'gold'
  }
  

• Los tipos de objeto pueden usar la recursividad directa o indirecta si al menos la parte de la ruta de acceso al punto de recursividad es opcional. Por ejemplo, la definición myObjectType del ejemplo siguiente es válida porque la propiedad directamente recursiva recursiveProp es opcional:

  type myObjectType = {
    stringProp: string
    recursiveProp: myObjectType?
  }
  

  La siguiente definición de tipo no sería válida porque ninguna de level1, level2, level3, level4 o level5 es opcional.

  type invalidRecursiveObjectType = {
    level1: {
      level2: {
        level3: {
          level4: {
            level5: invalidRecursiveObjectType
          }
        }
      }
    }
  }
  

• Puede usar operadores unarios de Bicep con literales enteros y booleanos o referencias a símbolos de tipo literal booleano o entero:

  type negativeIntLiteral = -10
  type negatedIntReference = -negativeIntLiteral
  
  type negatedBoolLiteral = !true
  type negatedBoolReference = !negatedBoolLiteral
  

• Las uniones pueden incluir cualquier número de expresiones con tipo literal. Los tipos de unión se traducen en la restricción de valor permitido en Bicep, por lo que solo se permiten literales como miembros.

  type oneOfSeveralObjects = {foo: 'bar'} | {fizz: 'buzz'} | {snap: 'crackle'}
  type mixedTypeArray = ('fizz' | 42 | {an: 'object'} | null)[]
  

Puede usar expresiones de tipo en la instrucción type y también puede usar expresiones de tipo para crear tipos de datos definidos por el usuario, como se muestra en los siguientes lugares:

• Como la cláusula tipo de una instrucción param. Por ejemplo:

  param storageAccountConfig {
    name: string
    sku: string
  }
  

• Después de : en una propiedad de tipo de objeto. Por ejemplo:

  param storageAccountConfig {
   name: string
    properties: {
      sku: string
    }
  } = {
    name: 'store$(uniqueString(resourceGroup().id)))'
    properties: {
      sku: 'Standard_LRS'
    }
  }
  

• Anterior a [] en una expresión de tipo de matriz. Por ejemplo:

  param mixedTypeArray ('fizz' | 42 | {an: 'object'} | null)[]
  

Un archivo de Bicep típico para crear una cuenta de almacenamiento tiene el siguiente aspecto:

param location string = resourceGroup().location
param storageAccountName string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
])
param storageAccountSKU string = 'Standard_LRS'

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: storageAccountSKU
  }
  kind: 'StorageV2'
}

Con los tipos de datos definidos por el usuario, puede tener el siguiente aspecto:

param location string = resourceGroup().location

type storageAccountSkuType = 'Standard_LRS' | 'Standard_GRS'

type storageAccountConfigType = {
  name: string
  sku: storageAccountSkuType
}

param storageAccountConfig storageAccountConfigType

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

Uso de decoradores

Los decoradores se escriben en el formato @expression y se colocan encima de las declaraciones del tipo de datos definido por el usuario. En la tabla siguiente se muestran los decoradores disponibles para los tipos de datos definidos por el usuario.

Decorador	Aplicar a	Argumento	Descripción
descripción	all	string	Proporcione descripciones para el tipo de datos definido por el usuario.
discriminator	objeto	string	Use este decorador para asegurarse de que la subclase correcta se identifica y administra.
export	all	None	Indica que el tipo de datos definido por el usuario está disponible para la importación por otro archivo de Bicep.
maxLength	array, string	int	Longitud máxima de los tipos de datos de cadena y matriz. El valor es inclusivo.
maxValue	int	int	El valor máximo para los tipos de datos de enteros. Este valor es inclusivo.
metadata	all	objeto	Propiedades personalizadas que se aplicarán a los tipos de datos. Pueden incluir una propiedad de descripción equivalente al decorador de la descripción.
minLength	array, string	int	La longitud mínima para los tipos de datos de cadenas y matrices. El valor es inclusivo.
minValue	int	int	El valor mínimo para los tipos de datos de enteros. Este valor es inclusivo.
sealed	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	string, object	None	Marca los tipos como seguros. El valor de un tipo 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 una variable llamada description, debe agregar el espacio de nombres sys al usar el decorador description.

Discriminador

Consulte Tipo de datos de unión etiquetado.

Descripción

Agregue una descripción al tipo de datos definido por el usuario. Puede usar decoradores en propiedades. Por ejemplo:

@description('Define a new object type.')
type obj = {
  @description('The object ID')
  id: int

  @description('Additional properties')
  @minLength(10)
  *: string
}

Puede usar el texto con formato Markdown para el texto de descripción.

Exportación

Use @export() para compartir el tipo de datos definido por el usuario con otros archivos de Bicep. Para más información, consulte Exportación de variables, tipos y funciones.

Restricciones de enteros

Puede establecer valores mínimos y máximos para las salidas de tipos enteros. Puede establecer una o las dos restricciones.

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

Restricciones de longitud

Puede especificar longitudes mínimas y máximas para los tipos de cadenas y matrices. 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 declara dos tipos. Un tipo es para un nombre de cuenta de almacenamiento que debe tener entre 3 y 24 caracteres. El otro tipo es una matriz que debe tener de 1 a 5 elementos.

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

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

Metadatos

Si tiene propiedades personalizadas que desea aplicar a un tipo de datos definida por el usuario, 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.

Este decorador se puede utilizar para rastrear información sobre el tipo de datos que no tenga sentido añadir a la descripción.

@description('Configuration values that are applied when the application starts.')
@metadata({
  source: 'database'
  contact: 'Web team'
})
type 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.

Sellado

Consulte Elevación del nivel de error.

Tipos seguros

Puede marcar una cadena o un tipo de datos definido por el usuario como seguro. El valor de un parámetro seguro no se guarda en el historial de implementaciones y no se registra.

@secure()
type demoPassword string

@secure()
type demoSecretObject object

Elevar nivel de error

De forma predeterminada, declarar un tipo de objeto en Bicep permite aceptar propiedades adicionales de cualquier tipo. Por ejemplo, el Bicep siguiente es válido, pero genera una advertencia de [BCP089] - The property "otionalProperty" is not allowed on objects of type "{ property: string, optionalProperty: null | string }". Did you mean "optionalProperty"?:

type anObject = {
  property: string
  optionalProperty: string?
}
 
param aParameter anObject = {
  property: 'value'
  otionalProperty: 'value'
}

La advertencia le informa de que el tipo anObject no incluye una propiedad denominada otionalProperty. Aunque no se producen errores durante la implementación, el compilador de Bicep supone que otionalProperty es un error tipográfico y que el usuario pretende usar optionalProperty pero lo ha escrito mal. Bicep le avisa de la incoherencia.

Para escalar estas advertencias a errores, aplique el decorador @sealed() al tipo de objeto:

@sealed() 
type anObject = {
  property: string
  optionalProperty?: string
}

Para obtener los mismos resultados, aplique el decorador @sealed() a la declaración param:

type anObject = {
  property: string
  optionalProperty: string?
}
 
@sealed() 
param aParameter anObject = {
  property: 'value'
  otionalProperty: 'value'
}

El motor de implementación de Azure Resource Manager también comprueba los tipos sellados de otras propiedades. Si se proporcionan propiedades adicionales para los parámetros sellados, se produce un error de validación, lo cual provoca un error en la implementación. Por ejemplo:

@sealed()
type anObject = {
  property: string
}

param aParameter anObject = {
  property: 'value'
  optionalProperty: 'value'
}

Tipo de datos de unión etiquetado

Para declarar un tipo de datos de unión etiquetado personalizado dentro de un archivo de Bicep, puede colocar un decorador discriminator encima de una declaración de tipo definida por el usuario. Para usar este decorador se necesita la versión 0.21.X o posterior de la CLI de Bicep. En el ejemplo siguiente se muestra cómo declarar un tipo de datos de unión etiquetado:

type FooConfig = {
  type: 'foo'
  value: int
}

type BarConfig = {
  type: 'bar'
  value: bool
}

@discriminator('type')
type ServiceConfig = FooConfig | BarConfig | { type: 'baz', *: string }

param serviceConfig ServiceConfig = { type: 'bar', value: true }

output config object = serviceConfig

Para obtener más información, vea Tipo de datos de unión etiquetado personalizado.

Contenido relacionado

Para obtener una lista de los tipos de datos de Bicep, consulte Tipos de datos.