Parâmetros no bíceps

  • Artigo

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.

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

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

Default value

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

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. 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 Description
permitido todos matriz Valores permitidos para o parâmetro. Use este decorador para se certificar de que o usuário fornece valores corretos.
descrição todos string Texto que explica como usar o parâmetro. A descrição é exibida aos usuários através do portal.
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.
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

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

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

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.

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

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

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:

Usar texto formatado com Markdown no VSCode

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

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.

Parâmetro de utilização

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

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óximos passos