Parâmetros no Bicep

  • Artigo

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.

Você está limitado a 256 parâmetros em um arquivo Bicep. 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.

Declaração

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

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.

Valor 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

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. Você pode marcar um parâmetro como seguro, especificar valores permitidos, definir o comprimento mínimo e máximo para uma cadeia de caracteres, definir o valor mínimo e máximo para um inteiro e fornecer uma descrição do parâmetro.

O exemplo a seguir mostra dois usos comuns para decoradores.

@secure()
param demoPassword string

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

A tabela a seguir descreve os decoradores disponíveis e como usá-los.

Decorador Aplicar a Argumento Descrição
permitido all array Valores permitidos ao parâmetro. Use este decorador para garantir que o usuário forneça valores corretos.
descrição all string Texto que explica como usar o parâmetro. A descrição é exibida aos usuários por meio do portal.
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.
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

Os decoradores disponíveis são descritos nas seções a seguir.

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

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.

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

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

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:

Usar texto formatado em Markdown no VSCode

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

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.

Usar parâmetro

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

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@2020-06-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