Tipos de dados definidos pelo usuário no Bicep

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.

A regra de linter use-user-defined-types incentiva a utilização de tipos de dados definidos pelo utilizador em vez dos tipos genéricos object ou array.

Definir tipos

Use a type instrução para criar tipos de dados definidos pelo utilizador. 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 decorador @allowed só é permitido em instruções param. Para declarar um tipo com um conjunto de valores predefinidos num type, use a sintaxe de tipo de união.

Expressões de tipo válidas incluem:

Referências simbólicas

Referências simbólicas são identificadores que se referem a um tipo ambiente (como string ou int) ou a um símbolo de tipo definido pelo utilizador declarado numa type instrução.

// Bicep data type reference
type myStringType = string

// user-defined type reference
type myOtherStringType = myStringType

Literais primitivos

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

Tipos de matriz

Pode declarar tipos de array acrescentando [] a qualquer expressão de tipo válida. Por exemplo:

// 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)[]

Tipos de união

Um tipo union permite criar um tipo combinado composto por um conjunto de subtipos. Um valor corresponde ao tipo se corresponder a algum dos subtipos. Use o operador pipe (|) para separar os tipos individuais de membros. Bicep traduz os tipos de união para a restrição de valor permitido, pelo que apenas literais são permitidos como membros. As uniões podem incluir qualquer número de expressões digitadas literalmente.

type directions = 'east' | 'south' | 'west' | 'north'

type obj = {
  level: 'bronze' | 'silver' | 'gold'
}

Pode declarar tipos de união diretamente, e um dos membros pode ser uma referência a outro símbolo com tipo literal.

Sindicatos de tipos mistos

Os tipos de membros não precisam de ser do mesmo tipo de literal. Uma união pode combinar string, inteiro, booleano, objeto e null literais.

type mixedType = 'fizz' | 42 | { an: 'object' } | null

Tipos de objeto

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 obrigatórias, exceto se incluírem um marcador ? de carácter opcional 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'
}

Recursão

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 seguinte definição de tipo não é válida porque nenhum de level1, level2, level3, level4, ou level5 é opcional.

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

Operadores unários

Utilize operadores unários do Bicep com literais inteiros e booleanos ou referências a símbolos tipados como literais inteiros ou booleanos.

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. Bicep traduz os tipos de união para a restrição de valor permitido, pelo que apenas literais são permitidos como membros.

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

Use expressões tipográficas na type instrução. Também pode usar expressões de tipo para criar tipos de dados definidos pelo utilizador, como mostrado nos seguintes locais.

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

  param storageAccountConfig {
    name: string
    sku: string
  }
  

• Após a : numa propriedade de um tipo de objeto. 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@2025-06-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: storageAccountSKU
  }
  kind: 'StorageV2'
}

Com tipos de dados definidos pelo utilizador, pode ficar assim:

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

Utilize decoradores

Escreva decoradores no formato @expression e coloque-os acima das declarações do tipo de dado definido pelo utilizador. A tabela a seguir mostra os decoradores disponíveis para tipos de dados definidos pelo usuário.

Os decoradores estão no espaço de nomes 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

Ver tipo de dados de união etiquetada.

Descrição

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

Utilize @export() para partilhar o tipo de dados definido pelo utilizador com outros ficheiros Bicep. Para obter mais informações, consulte Exportar variáveis, tipos e funções.

Restrições de números inteiros

Defina 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

Especifique comprimentos mínimos e máximos para tipos de cordas e arrays. 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.

Utilize este decorador para registar informações sobre o tipo de dados que não faça sentido incluir na descrição.

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

Quando fornece um decorador @metadata() com uma propriedade que entra em conflito com outro decorador, a propriedade em conflito no valor de @metadata() é redundante e é substituída. Para obter mais informações, consulte Sem metadados conflitantes.

Selado

Consulte Nível de erro elevado.

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 é guardado no histórico de implementação nem registado.

@secure()
type demoPassword string

@secure()
type demoSecretObject object

Aumentar 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 emite 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 elevar estes avisos a erros, aplique o decorador @sealed() ao tipo do 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 selados 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 etiquetada

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 seguinte mostra como declarar um tipo de dados de união etiquetada:

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.

Tipos derivados de recursos

O Bicep permite derivar tipos diretamente dos esquemas de recursos do Azure ao utilizar as construções resourceInput<> e resourceOutput<>. Ao usar tipos derivados de recursos, pode verificar parâmetros e variáveis contra uma parte do corpo de um recurso em vez de usar um tipo personalizado. Para usar estes construtos, precisa da Bicep CLI versão 0.34.1 ou superior.

Os modelos podem reutilizar tipos de recursos sempre que um tipo é esperado.

resourceInput<'type@version'>

• resourceInput<>: Representa as propriedades graváveis de um tipo de recurso, removendo quaisquer propriedades marcadas como ReadOnly no esquema do modelo ARM. Utiliza o tipo que precisas de passar para a declaração de recurso.

resourceOutput<'type@version'>

• resourceOutput<>: Representa as propriedades legíveis de um tipo de recurso, removendo quaisquer propriedades marcadas como WriteOnly no esquema do modelo ARM. Ele corresponde ao tipo de valor retornado depois que o recurso é provisionado.

Você pode aplicar resourceInput<> ou resourceOutput<> extrair apenas uma parte de um esquema de recursos. Por exemplo, para digitar uma variável ou parâmetro com base apenas no kind ou properties de uma conta de armazenamento:

type accountKind = resourceInput<'Microsoft.Storage/storageAccounts@2024-01-01'>.kind

O exemplo anterior é equivalente a:

type accountKind = 'BlobStorage' | 'BlockBlobStorage' | 'FileStorage' | 'Storage' | 'StorageV2'

O exemplo a seguir mostra como usar resourceInput<> para criar um parâmetro tipado com base no properties de um recurso de conta de armazenamento. Esta abordagem define um parâmetro que corresponde às propriedades graváveis de uma conta de armazenamento, como accessTier, minimumTlsVersion, e outras propriedades:

// Typed parameter using the .properties path of a storage account
param storageAccountProps resourceInput<'Microsoft.Storage/storageAccounts@2023-01-01'>.properties = {
  accessTier: 'Hot'
  minimumTlsVersion: 'TLS1_2'
  allowBlobPublicAccess: false
  supportsHttpsTrafficOnly: true
}

// Resource declaration using the typed parameter
resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: 'mystorageacct123'
  location: resourceGroup().location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  properties: storageAccountProps
}

O exemplo a seguir mostra como utilizar resourceOutput<> para gerar uma saída tipada com base no primaryEndPoints de um recurso de conta de armazenamento.

output storageEndpoints resourceOutput<'Microsoft.Storage/storageAccounts@2024-01-01'>.properties.primaryEndpoints = ...

Ao contrário dos tipos de dados definidos pelo utilizador, o Bicep verifica tipos derivados de recursos quando edita ou compila um ficheiro, mas o serviço ARM não os verifica.

Conteúdos relacionados

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