Parâmetros no Bicep

Este artigo descreve como definir e usar os parâmetros em um arquivo Bicep. Ao fornecer valores diferentes para os parâmetros, você poderá reutilizar um arquivo Bicep para ambientes diferentes.

O Azure Resource Manager resolve os valores dos parâmetros antes de iniciar as operações de implantação. Independente de onde o parâmetro é usado, o Resource Manager substitui pelo valor resolvido.

Cada parâmetro deve ser definido para um dos tipos de dados.

O Bicep permite, no máximo, 256 parâmetros. Para obter mais informações, confira Limites de modelo.

Para obter as práticas recomendadas sobre parâmetro, confira Parâmetros.

Recursos de treinamento

Se você preferir aprender sobre parâmetros por meio de diretrizes passo a passo, confira Criar modelos Bicep reutilizáveis usando parâmetros.

Definir parâmetros

Cada parâmetro tem um nome e um tipo de dados. Opcionalmente, você pode fornecer um valor padrão para o parâmetro.

@<decorator>(<argument>)
param <parameter-name> <parameter-data-type> = <default-value>

Um parâmetro não pode ter o mesmo nome de uma variável, recurso, saída ou outro parâmetro no mesmo escopo.

O exemplo a seguir mostra declarações básicas de parâmetros.

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

A palavra-chave param também é usada nos arquivos .bicepparam. Nos arquivos .bicepparam, você não precisa especificar o tipo de dados como ele é definido nos arquivos Bicep.

param <parameter-name> = <value>

Para obter mais informações, consulte Arquivo de parâmetros.

Expressões de tipo definidas pelo usuário podem ser usadas como a cláusula de tipo de uma instrução param. Por exemplo:

param storageAccountConfig {
  name: string
  sku: string
}

Para obter mais informações, confira Tipos de dados definidos pelo usuário.

Definir os valores padrão

É possível especificar um valor padrão para um parâmetro. O valor padrão é usado quando um valor não é fornecido durante a implantação.

param demoParam string = 'Contoso'

É possível usar as expressões com o valor padrão. Não é permitido usar expressões com outras propriedades de parâmetro. Não é possível usar a função de referência ou outras funções de lista na seção de parâmetros. Essas funções obtêm o estado de tempo de execução do recurso e não podem ser executadas antes da implantação quando os parâmetros são resolvidos.

param location string = resourceGroup().location

Você pode usar outro valor de parâmetro para criar um valor padrão. O modelo a seguir constrói um nome de plano de host a partir do nome do site.

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

output siteNameOutput string = siteName
output hostingPlanOutput string = hostingPlanName

No entanto, você não pode fazer referência a uma variável como o valor padrão.

Usar decoradores

Os parâmetros usam decoradores para restrições ou metadados. Os decoradores estão no formato @expression são colocados acima da declaração do parâmetro. A tabela a seguir mostra os decoradores disponíveis para parâmetros.

Decorador	Aplicar a	Argumento	Descrição
permitido	all	matriz	Use este decorador para garantir que o usuário forneça valores corretos. Esse decorador só é permitido em instruções param. Para declarar que uma propriedade deve ser um de um conjunto de valores predefinidos em uma instrução type ou output, use a sintaxe de tipo de união. A sintaxe de tipo de união também pode ser usada em instruções param.
descrição	all	string	Texto que explica como usar o parâmetro. A descrição é exibida aos usuários por meio do portal.
discriminator	objeto	string	Use esse decorador para garantir que a subclasse correta seja identificada e gerenciada. Para obter mais informações, consulte Tipo de dados de união com marcas personalizadas.
maxLength	matriz, cadeia de caracteres	INT	Tamanho máximo de parâmetros do tipo matriz e cadeia de caracteres. O valor é inclusivo.
maxValue	INT	INT	Valor máximo do parâmetro inteiro. Esse valor é inclusivo.
metadados	all	objeto	Propriedades personalizadas a serem aplicadas ao parâmetro. Pode incluir uma propriedade de descrição que seja equivalente ao decorador da descrição.
minLength	matriz, cadeia de caracteres	INT	Tamanho mínimo de parâmetros do tipo matriz e cadeia de caracteres. O valor é inclusivo.
minValue	INT	INT	Valor mínimo do parâmetro inteiro. Esse valor é inclusivo.
sealed	objeto	nenhum	Eleve o BCP089 de aviso para 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 nível de erro.
seguro	cadeia de caracteres, objeto	nenhum	Marca o parâmetro como seguro. O valor de um parâmetro seguro não é salvo no histórico de implantação e não é registrado em log. Para obter mais informações, confira Proteger cadeias de caracteres e objetos.

Os decoradores estão no namespace sys. Se você precisar diferenciar um decorador de outro item com o mesmo nome, preceda o decorador com sys. Por exemplo, se o arquivo Bicep incluir um parâmetro chamadodescription, você deverá adicionar o namespace sys ao usar o decorador de descrição.

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

Valores permitidos

É possível definir os valores permitidos para um parâmetro. Você fornece os valores permitidos em uma matriz. A implantação falhará durante a validação se um valor for passado para o parâmetro que não é um dos valores permitidos.

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

Se você definir valores permitidos para um parâmetro de matriz, o valor real poderá ser qualquer subconjunto dos valores permitidos.

Descrição

Para ajudar os usuários a reconhecer o valor a ser fornecido, adicione uma descrição ao parâmetro. Quando um usuário implanta o modelo por meio do portal, o texto da descrição é usado automaticamente como dica para esse parâmetro. Adicione apenas uma descrição quando o texto fornecer mais informações do que podem ser inferida do nome do parâmetro.

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

O texto formatado por Markdown pode ser usado para o texto de descrição:

@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

Quando você posicionar seu cursor sobre storageAccountName no VS Code, você verá o texto formatado:

Verifique se o texto segue a formatação de Markdown adequada, caso contrário, talvez ele não seja exibido corretamente quando renderizado.

Discriminador

Consulte Tipo de dados de união marcados sob medida.

Restrições de inteiro

É possível definir os valores mínimos e máximos para parâmetros inteiros. É possível definir uma ou ambas as restrições.

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

Restrições de comprimento

É possível especificar os comprimentos mínimos e máximos para os parâmetros de cadeia de caracteres e matriz. É possível 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 parâmetros. Um parâmetro é para um nome de conta de armazenamento que deve ter de 3 a 24 caracteres. O outro parâmetro é uma matriz que deve ter de 1 a 5 itens.

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

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

Metadados

Se você tiver propriedades personalizadas que deseja aplicar a um parâmetro, adicione um decorador de metadados. Dentro dos metadados, defina um objeto com os nomes e os valores personalizados. O objeto que você define para os metadados pode conter propriedades de qualquer nome e tipo.

Você pode usar esse decorador para controlar informações sobre o parâmetro que não precisem ser adicionadas à descrição.

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

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

Selado

Consulte Elevar nível de erro.

Parâmetros seguros

É possível marcar os parâmetros de cadeia de caracteres ou de objeto como seguros. O valor de um parâmetro seguro não é salvo no histórico de implantação nem registrado em log.

@secure()
param demoPassword string

@secure()
param demoSecretObject object

Há várias regras de linter relacionadas a esse decorador: Padrão de parâmetro seguro, Parâmetros seguros em implantações aninhadas, Segredos seguros em parâmetros.

Usar parâmetros

Para referenciar o valor de um parâmetro, use o nome do parâmetro. O exemplo a seguir usa um valor de parâmetro para um nome de cofre de chaves.

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

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

Usar objetos como parâmetros

Pode ser mais fácil organizar valores relacionados, passando-os como um objeto. Essa abordagem também reduz o número de parâmetros no modelo.

O exemplo a seguir mostra um parâmetro que é um objeto. O valor padrão mostra as propriedades esperadas para o objeto. Essas propriedades são usadas ao definir o recurso a ser implantado.

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@2023-11-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
        }
      }
    ]
  }
}

Próximas etapas

• Para saber mais sobre as propriedades disponíveis para os parâmetros, consulte Entender a estrutura e a sintaxe dos arquivos Bicep.
• Para saber mais sobre como passar valores de parâmetro como um arquivo, consulte Criar um arquivo de parâmetro Bicep.
• Para saber mais sobre como fornecer valores de parâmetro na implantação, consulte Implantar com a CLI do Azure e Implantar com o Azure PowerShell.