Parâmetros em Bicep

Este artigo descreve como definir e utilizar parâmetros num ficheiro Bicep. Ao fornecer valores diferentes para parâmetros, pode reutilizar um ficheiro Bicep para ambientes diferentes.

O Gestor de Recursos resolve valores de parâmetros antes de iniciar as operações de implementação. Sempre que o parâmetro for utilizado, o Gestor de Recursos substitui-o pelo valor resolvido.

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

Microsoft Learn

Se preferir saber mais sobre parâmetros através da orientação passo a passo, consulte Criar modelos Bicep reutilizáveis ao utilizar parâmetros no Microsoft Learn.

Declaração

Cada parâmetro tem um nome e um tipo de dados. Opcionalmente, pode fornecer um valor predefinido 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 âmbito.

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

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

Valor predefinido

Pode especificar um valor predefinido para um parâmetro. O valor predefinido é utilizado quando um valor não é fornecido durante a implementação.

param demoParam string = 'Contoso'

Pode utilizar expressões com o valor predefinido. As expressões não são permitidas com outras propriedades de parâmetros. Não pode utilizar a função de referência ou nenhuma das funções de lista na secção de parâmetros. Estas funções ocorrem o estado de tempo de execução do recurso e não podem ser executadas antes da implementação quando os parâmetros são resolvidos.

param location string = resourceGroup().location

Pode utilizar outro valor de parâmetro para criar um valor predefinido. O modelo seguinte construi o nome de um plano anfitrião 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 utilizam decoradores para restrições ou metadados. Os decoradores estão no formato e são @expression colocados acima da declaração do parâmetro. Pode marcar um parâmetro como seguro, especificar os valores permitidos, definir o comprimento mínimo e máximo de uma cadeia, definir o valor mínimo e máximo para um número inteiro e fornecer uma descrição do parâmetro.

O exemplo seguinte mostra duas utilizações comuns para os decoradores.

@secure()
param demoPassword string

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

A seguinte tabela descreve os decoradores disponíveis e como os utilizar.

Decorador Aplicar a Argumento Descrição
permitido tudo matriz Valores permitidos para o parâmetro. Utilize este decorador para se certificar de que o utilizador fornece os valores corretos.
descrição tudo cadeia Texto que explica como utilizar o parâmetro. A descrição é apresentada aos utilizadores através do portal.
maxLength matriz, cadeia int O comprimento máximo para os parâmetros de cadeia e matriz. O valor é inclusivo.
maxValue int int O valor máximo para o parâmetro inteiro. Este valor é inclusivo.
metadados tudo objeto Propriedades personalizadas a aplicar ao parâmetro. Pode incluir uma propriedade de descrição equivalente ao decorador de descrição.
minLength matriz, cadeia int O comprimento mínimo para os parâmetros de cadeia e matriz. O valor é inclusivo.
minValue int int O valor mínimo para o parâmetro inteiro. Este valor é inclusivo.
seguro cadeia, objeto nenhum Marca o parâmetro como seguro. O valor de um parâmetro seguro não é guardado no histórico de implementação e não está com sessão. Para obter mais informações, consulte Proteger cadeias e objetos.

Os decoradores estão no espaço de nomes sys. Se precisar de diferenciar um decorador de outro item com o mesmo nome, precede o decorador com sys . Por exemplo, se o seu ficheiro Bícep incluir um parâmetro chamado , tem de adicionar o espaço de nomes sys ao utilizar o description decorador de description descrições.

@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 estão descritos nas secções seguintes.

Parâmetros seguros

Pode marcar parâmetros de cadeia ou objeto como seguros. O valor de um parâmetro seguro não é guardado no histórico de implementação e não está com sessão.

@secure()
param demoPassword string

@secure()
param demoSecretObject object

Valores permitidos

Pode definir os valores permitidos para um parâmetro. Forneça os valores permitidos numa matriz. A implementação falha durante a validação se for transmitido um valor para o parâmetro que não seja um dos valores permitidos.

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

Restrições de comprimento

Pode especificar comprimentos mínimos e máximos para os parâmetros de cadeia e matriz. Pode definir uma ou ambas as restrições. Para cadeias, o comprimento indica o número de carateres. Para matrizes, o comprimento indica o número de itens na matriz.

O exemplo seguinte declara dois parâmetros. Um parâmetro é para o nome de uma conta de armazenamento que tem de ter 3 a 24 carateres. O outro parâmetro é uma matriz que tem de ter de 1 a 5 itens.

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

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

Restrições de valores inteiros

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

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

Descrição

Para ajudar os utilizadores a compreender o valor a fornecer, adicione uma descrição ao parâmetro. Ao implementar o modelo através do portal, o texto da descrição é utilizado automaticamente como descrição para esse parâmetro. Adicione apenas uma descrição quando o texto fornecer mais informações do que as que podem ser inferidas a partir do nome do parâmetro.

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

Utilizar parâmetro

Para referenciar o valor de um parâmetro, utilize o nome do parâmetro. O exemplo seguinte utiliza um valor de parâmetro para o nome de um cofre chave.

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

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

Objectos como parâmetros

Pode ser mais fácil organizar valores relacionados ao passá-los como um objeto. Esta abordagem também reduz o número de parâmetros no modelo.

O exemplo seguinte mostra um parâmetro que é um objeto. O valor predefinido mostra as propriedades esperadas do objeto. Essas propriedades são utilizadas para definir o recurso a implementar.

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

Passos seguintes