Tipos de dados definidos pelo usuário no Bicep

Artigo
10/29/2024

Saiba como criar tipos de dados definidos pelo usuário no Bicep. Para tipos de dados definidos pelo sistema, consulte Tipos de dados. O uso de tipos de dados definidos pelo usuário habilita automaticamente a geração de código da versão 2.0 do idioma.

A CLI do Bicep versão 0.12.X ou superior é necessária para usar esse recurso.

Definir tipos

Você pode usar a type instrução para criar tipos de dados definidos pelo usuário. Você também pode usar expressões de texto em alguns lugares para definir tipos personalizados.

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

O @allowed decorador só é permitido em param declarações. Para declarar um tipo com um conjunto de valores predefinidos em um type, use a sintaxe de tipo união.

As expressões de tipo válidas incluem:

Referências simbólicas são identificadores que se referem a um tipo de ambiente (como string ou int) ou um símbolo de tipo definido pelo usuário declarado em uma type instrução:
```
// Bicep data type reference
type myStringType = string

// user-defined type reference
type myOtherStringType = myStringType
```

Literais primitivos, incluindo strings, inteiros e booleanos, são expressões de tipo válidas. Por exemplo:

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

Você pode declarar tipos de matriz anexando a qualquer expressão 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)[]

Os tipos de objeto contêm zero ou mais propriedades entre colchetes:
```
type storageAccountConfigType = {
  name: string
  sku: string
}
```
Cada propriedade em um objeto consiste em uma chave e um valor separados por dois pontos :. A chave pode ser qualquer cadeia de caracteres, com valores não identificadores entre aspas. O valor pode ser qualquer tipo de expressão.

As propriedades são necessárias, a menos que tenham um marcador ? de opcionalidade após o valor da propriedade. Por exemplo, a sku propriedade no exemplo a seguir é opcional:
```
type storageAccountConfigType = {
  name: string
  sku: string?
}
```
Você pode usar decoradores em propriedades. Você pode usar um asterisco (*) para fazer com que todos os valores exijam uma restrição. Você pode definir mais propriedades usando *. Este exemplo cria um objeto que requer uma chave do tipo int chamada id. Todas as outras entradas no objeto devem ter um valor de cadeia de caracteres com pelo menos 10 caracteres.
```
type obj = {
  @description('The object ID')
  id: int

  @description('Additional properties')
  @minLength(10)
  *: string
}
```
O exemplo a seguir mostra como usar a sintaxe de tipo união para listar um conjunto de valores predefinidos:
```
type directions = 'east' | 'south' | 'west' | 'north'

type obj = {
  level: 'bronze' | 'silver' | 'gold'
}
```
Os tipos de objeto podem usar recursão direta ou indireta se pelo menos a perna do caminho até o ponto de recursão for opcional. Por exemplo, a myObjectType definição no exemplo a seguir é válida porque a propriedade diretamente recursiva recursiveProp é opcional:
```
type myObjectType = {
  stringProp: string
  recursiveProp: myObjectType?
}
```
A definição de tipo a seguir não seria válida porque nenhum dos level1, level2, level3, level4, ou level5 é opcional.
```
type invalidRecursiveObjectType = {
  level1: {
    level2: {
      level3: {
        level4: {
          level5: invalidRecursiveObjectType
        }
      }
    }
  }
}
```

Você pode usar operadores unários de bíceps com literais inteiros e booleanos ou referências a inteiros ou símbolos booleanos digitados literalmente:

type negativeIntLiteral = -10
type negatedIntReference = -negativeIntLiteral

type negatedBoolLiteral = !true
type negatedBoolReference = !negatedBoolLiteral

As uniões podem incluir qualquer número de expressões digitadas literalmente. Os tipos de união são traduzidos na restrição de valor permitido no Bicep, portanto, apenas literais são permitidos como membros.
```
type oneOfSeveralObjects = {foo: 'bar'} | {fizz: 'buzz'} | {snap: 'crackle'}
type mixedTypeArray = ('fizz' | 42 | {an: 'object'} | null)[]
```

Você pode usar expressões de tipo na type instrução e também pode usar expressões de tipo para criar tipos de dados definidos pelo usuário, conforme mostrado nos seguintes locais:

Como a cláusula de tipo de uma param instrução. Por exemplo:

param storageAccountConfig {
  name: string
  sku: string
}

Seguindo a : propriedade in an object type. Por exemplo:

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

Precedendo o [] em uma expressão de tipo de matriz. Por exemplo:
```
param mixedTypeArray ('fizz' | 42 | {an: 'object'} | null)[]
```

Um arquivo Bicep típico para criar uma conta de armazenamento se parece com:

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

Com tipos de dados definidos pelo usuário, ele pode se parecer com:

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

Use decoradores

Os decoradores são escritos no formato @expression e são colocados acima das declarações do tipo de dados definido pelo usuário. A tabela a seguir mostra os decoradores disponíveis para tipos de dados definidos pelo usuário.

Decorador	Aplicar a	Argumento	Description
descrição	todos	string	Forneça descrições para o tipo de dados definido pelo usuário.
discriminador	objeto	string	Use este decorador para garantir que a subclasse correta seja identificada e gerenciada.
exportação	todos	nenhum	Indica que o tipo de dados definido pelo usuário está disponível para importação por outro arquivo Bicep.
maxComprimento	matriz, string	número inteiro	O comprimento máximo para tipos de dados de cadeia de caracteres e matriz. O valor é inclusivo.
maxValor	número inteiro	número inteiro	O valor máximo para os tipos de dados inteiros. Este valor é inclusivo.
metadados	todos	objeto	Propriedades personalizadas a serem aplicadas aos tipos de dados. Pode incluir uma propriedade de descrição equivalente ao decorador de descrição.
minComprimento	matriz, string	número inteiro	O comprimento mínimo para tipos de dados de cadeia de caracteres e matriz. O valor é inclusivo.
minValor	número inteiro	número inteiro	O valor mínimo para os tipos de dados inteiros. Este valor é inclusivo.
selado	objeto	nenhum	Eleve o BCP089 de um aviso a um erro quando um nome de propriedade de um tipo de dados definido pelo usuário for provavelmente um erro de digitação. Para obter mais informações, consulte Elevar o nível de erro.
seguro	string, objeto	nenhum	Marca os tipos como seguros. O valor de um tipo seguro não é salvo no histórico de implantação e não é registrado. Para obter mais informações, consulte Proteger cadeias de caracteres e objetos.

Os decoradores estão no namespace sys. Se você precisa diferenciar um decorador de outro item com o mesmo nome, prefacie o decorador com sys. Por exemplo, se o arquivo Bicep incluir uma variável chamada description, você deverá adicionar o sys namespace ao usar o description decorador.

Discriminador

Consulte Tipo de dados de união com marcação.

Description

Adicione uma descrição ao tipo de dados definido pelo usuário. Você pode usar decoradores em propriedades. Por exemplo:

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

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

Você pode usar texto formatado em Markdown para o texto de descrição.

Exportar

Use @export() para compartilhar o tipo de dados definido pelo usuário com outros arquivos Bicep. Para obter mais informações, consulte Exportar variáveis, tipos e funções.

Restrições de números inteiros

Você pode definir valores mínimos e máximos para o tipo inteiro. Você pode definir uma ou ambas as restrições.

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

Restrições de comprimento

Você pode especificar comprimentos mínimos e máximos para tipos de cadeia de caracteres e matrizes. Você pode definir uma ou ambas as restrições. Para cadeias de caracteres, o comprimento indica o número de caracteres. Para matrizes, o comprimento indica o número de itens na matriz.

O exemplo a seguir declara dois tipos. Um tipo é para um nome de conta de armazenamento que deve ter de 3 a 24 caracteres. O outro tipo é uma matriz que deve ter de um a cinco itens.

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

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

Metadados

Se você tiver propriedades personalizadas que deseja aplicar a um tipo de dados definido pelo usuário, adicione um decorador de metadados. Dentro dos metadados, defina um objeto com os nomes e valores personalizados. O objeto definido para os metadados pode conter propriedades de qualquer nome e tipo.

Você pode usar esse decorador para rastrear informações sobre o tipo de dados que não fazem sentido adicionar à descrição.

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

Quando você fornece a um @metadata() decorador uma propriedade que entra em conflito com outro decorador, esse decorador sempre tem precedência sobre qualquer coisa no @metadata() decorador. Assim, a propriedade conflitante dentro do @metadata() valor é redundante e é substituída. Para obter mais informações, consulte Sem metadados conflitantes.

Selado

Consulte Elevar nível de erro.

Tipos seguros

Você pode marcar uma cadeia de caracteres ou um tipo de dados definido pelo usuário como seguro. O valor de um tipo seguro não é salvo no histórico de implantação e não é registrado.

@secure()
type demoPassword string

@secure()
type demoSecretObject object

Elevar o nível de erro

Por padrão, declarar um tipo de objeto no Bicep permite que ele aceite mais propriedades de qualquer tipo. Por exemplo, o seguinte Bicep é válido, mas gera um aviso 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'
}

O aviso informa que o anObject tipo não inclui uma propriedade chamada otionalProperty. Embora nenhum erro ocorra durante a implantação, o compilador Bicep assume que otionalProperty é um erro de digitação e que você pretendia usar optionalProperty , mas digitou incorretamente. O bíceps alerta para a inconsistência.

Para escalar esses avisos para erros, aplique o @sealed() decorador ao tipo de objeto:

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

Você obtém os mesmos resultados aplicando o @sealed() decorador à param declaração:

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

O mecanismo de implantação do Azure Resource Manager também verifica tipos lacrados para outras propriedades. O fornecimento de quaisquer propriedades extras para parâmetros selados resulta em um erro de validação, que faz com que a implantação falhe. Por exemplo:

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

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

Tipo de dados de união marcados

Para declarar um tipo de dados de união marcado personalizado em um arquivo Bicep, você pode colocar um discriminator decorador acima de uma declaração de tipo definida pelo usuário. Bicep CLI versão 0.21.X ou superior é necessário para usar este decorador. O exemplo a seguir mostra como declarar um tipo de dados união marcado:

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 obter mais informações, consulte Tipo de dados de união com tags personalizadas.

Para obter uma lista dos tipos de dados Bicep, consulte Tipos de dados.

Partilhar via

Tipos de dados definidos pelo usuário no Bicep

Definir tipos

Use decoradores

Discriminador

Description

Exportar

Restrições de números inteiros

Restrições de comprimento

Metadados

Selado

Tipos seguros

Elevar o nível de erro

Tipo de dados de união marcados

Comentários

Recursos adicionais

Partilhar via

Tipos de dados definidos pelo usuário no Bicep

Definir tipos

Use decoradores

Discriminador

Description

Exportar

Restrições de números inteiros

Restrições de comprimento

Metadados

Selado

Tipos seguros

Elevar o nível de erro

Tipo de dados de união marcados

Conteúdos relacionados

Comentários

Recursos adicionais