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 resolverá valores do parâmetro 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 deverá ser definido como 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.

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 em arquivos .bicepparam. Você não precisa especificar o tipo de dados em arquivos .bicepparam, pois ele é definido em arquivos Bicep.

param <parameter-name> = <value>

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, consulte tipos de dados definidos pelo usuário no Bicep.

Definir valores padrão

É possível especificar o valor padrão de 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 expressões com o valor padrão. Não é permitido usar expressões com outras propriedades de parâmetro. Você não pode usar a reference função ou qualquer uma das list funções na seção de parâmetros. Essas funções obtêm o estado de runtime 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 criará o nome do plano de host 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:

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 valores permitidos em um parâmetro. Forneça os valores permitidos em matriz. Caso um valor não permitido seja aprovado para o parâmetro, haverá falha na implantação durante a validação.

@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 usando o portal do Azure, o texto da descrição é usado automaticamente como uma dica para esse parâmetro. Adicione uma descrição somente quando o texto fornecer mais informações do que podem ser deduzidas 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 can only contain numbers and lowercase letters.
- 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 o cursor sobre storageAccountName no Visual Studio Code, verá o texto formatado:

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

Discriminador

Confira Tipo de dados de união com marcação personalizada.

Restrições do inteiro

É possível definir valores mínimos e máximos para parâmetros do inteiro. É possível definir uma restrição ou as duas.

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

Restrições de comprimento

É possível especificar comprimentos mínimos e máximos para parâmetros de cadeia de caracteres e matriz. É possível definir uma restrição ou as duas. Nas cadeias de caracteres, o comprimento indica o número de caracteres. Nas matrizes, o comprimento indica o número de itens da matriz.

O exemplo a seguir vai declarar 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 @metadata() decorador com uma propriedade que entra em conflito com a de outro decorador, esse decorador sempre tem precedência sobre qualquer coisa no @metadata() decorador, de modo que a propriedade conflitante dentro do valor @metadata() é redundante e será substituída. Para obter mais informações, consulte a regra linter - sem metadados conflitantes.

Lacrado

Consulte Elevar nível de erro.

Parâmetros seguros

É possível marcar parâmetros de cadeia de caracteres ou objeto como seguros. Quando um parâmetro é decorado com @secure(), o Azure Resource Manager trata o valor do parâmetro como confidencial, impedindo que ele seja registrado ou exibido no histórico de implantação, portal do Azure ou saídas de linha de comando.

@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 usará o valor do parâmetro em um nome do cofre de chaves.

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

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

O @secure() decorador é válido apenas para parâmetros de tipo cadeia de caracteres ou objeto, pois eles se alinham com os tipos secureString e secureObject em modelos arm. Para passar matrizes ou números com segurança, embrulhe-os em um secureObject ou serialize-os como um secureString.

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 mostrará as propriedades esperadas do objeto. Essas propriedades são usadas ao definir qual recurso implantar.

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@2025-01-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 parâmetros, consulte a estrutura e a sintaxe do arquivo Bicep.
• Para saber mais sobre como passar valores de parâmetro como um arquivo, consulte Criar um arquivo de parâmetros para implantação do Bicep.
• Para saber mais sobre como fornecer valores de parâmetro na implantação, consulte Implantar arquivos Bicep com a CLI do Azure e o Azure PowerShell.