Parâmetros no bíceps

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

O Resource Manager resolve valores de parâmetros antes de iniciar as operações de implantação. Onde quer que o parâmetro seja usado, o Resource Manager o substitui pelo valor resolvido.

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

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

Para obter as práticas recomendadas de parâmetros, consulte Parâmetros.

Recursos de formação

Se preferir aprender sobre parâmetros por meio de orientação passo a passo, consulte Criar modelos de 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 que 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 param palavra-chave também é usada em arquivos .bicepparam. Em arquivos .bicepparam, você não precisa especificar o tipo de dados como ele é definido em arquivos Bicep.

param <parameter-name> = <value>

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

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

param storageAccountConfig {
  name: string
  sku: string
}

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

Definir valores padrão

Você pode 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'

Você pode usar expressões com o valor padrão. As expressões não são permitidas com outras propriedades de parâmetro. Não é possível usar a função de referência ou qualquer uma das 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, não é possível fazer referência a uma variável como o valor padrão.

Use decoradores

Os parâmetros usam decoradores para restrições ou metadados. Os decoradores estão no formato @expression e 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	Description
permitido	todos	matriz	Use este decorador para se certificar de que o usuário fornece valores corretos. Este decorador só é permitido em param declarações. Para declarar que uma propriedade deve ser um de um conjunto de valores predefinidos em uma type instrução or output , use a sintaxe do tipo união. A sintaxe do tipo União também pode ser usada em param instruções.
descrição	todos	string	Texto que explica como usar o parâmetro. A descrição é exibida aos usuários através do portal.
discriminador	objeto	string	Use este decorador para garantir que a subclasse correta seja identificada e gerenciada. Para obter mais informações, consulte Tipo de dados de união com tags personalizadas.
maxComprimento	matriz, string	número inteiro	O comprimento máximo para parâmetros de cadeia de caracteres e matriz. O valor é inclusivo.
maxValor	número inteiro	número inteiro	O valor máximo para o parâmetro inteiro. Este valor é inclusivo.
metadados	todos	objeto	Propriedades personalizadas a serem aplicadas ao parâmetro. Pode incluir uma propriedade description equivalente ao decorador de descrição.
minComprimento	matriz, string	número inteiro	O comprimento mínimo para parâmetros de cadeia de caracteres e matriz. O valor é inclusivo.
minValor	número inteiro	número inteiro	O valor mínimo para o parâmetro inteiro. 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 de definição de uso for provavelmente um erro de digitação. Para obter mais informações, consulte Elevar o nível de erro.
seguro	string, 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. 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 um parâmetro chamado description, você deve 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

Você pode definir 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.

Description

Para ajudar os usuários a entender o valor a ser fornecido, adicione uma descrição ao parâmetro. Quando um usuário implanta o modelo através do portal, o texto da descrição é usado automaticamente como uma dica para esse parâmetro. Adicione apenas uma descrição quando o texto fornecer mais informações do que pode ser inferido a partir 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 com marcação 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ê passa o cursor sobre storageAccountName no VS Code, você vê o texto formatado:

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

Discriminador

Consulte Tipo de dados de união com tags personalizadas.

Restrições de números inteiros

Você pode definir valores mínimos e máximos para parâmetros inteiros. Você pode definir uma ou ambas as restrições.

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

Restrições de comprimento

Você pode especificar comprimentos mínimos e máximos para parâmetros de cadeia de caracteres e matriz. 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 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 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 parâmetro que não faz sentido adicionar à descrição.

@description('Configuration values that are applied when the application starts.')
@metadata({
  source: 'database'
  contact: 'Web team'
})
param 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 será substituída. Para obter mais informações, consulte Sem metadados conflitantes.

Selado

Consulte Elevar nível de erro.

Parâmetros seguros

Você pode marcar parâmetros de cadeia de caracteres ou objeto como seguros. O valor de um parâmetro seguro não é salvo no histórico de implantação e não é registrado.

@secure()
param demoPassword string

@secure()
param demoSecretObject object

Existem várias regras linter relacionadas a este decorador: Parâmetro seguro padrão, Parâmetros seguros em implantações aninhadas, Segredos seguros em parâmetros.

Utilizar parâmetros

Para fazer referência ao 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óximos passos

• Para saber mais sobre as propriedades disponíveis para parâmetros, consulte Compreender 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âmetros do Bíceps.
• Para saber mais sobre como fornecer valores de parâmetro na implantação, consulte Implantar com CLI do Azure e Implantar com o Azure PowerShell.