Partilhar via

Criar um arquivo de parâmetros para a implantação do Bicep

  • Artigo

Este artigo mostra como criar um arquivo de parâmetros, que você pode usar em vez de passar parâmetros como valores embutidos em seu script. Você pode usar um arquivo de parâmetros Bicep com a extensão de .bicepparam arquivo ou um arquivo de parâmetros JSON que contém o valor do parâmetro.

Nota

Os arquivos de parâmetros do Bicep são suportados somente na CLI do Bicep versão 0.18.4 ou posterior, na CLI do Azure versão 2.47.0 ou posterior e no Azure PowerShell versão 9.7.1 ou posterior.

Um único arquivo Bicep pode ter vários arquivos de parâmetros Bicep associados a ele. No entanto, cada arquivo de parâmetros Bicep destina-se a um arquivo Bicep específico. Você pode estabelecer essa relação aplicando a using instrução dentro do arquivo de parâmetros do Bicep.

Você pode compilar arquivos de parâmetros do Bicep em arquivos de parâmetros JSON que você pode implantar usando um arquivo Bicep. Para obter mais informações, veja build-params. Você também pode descompilar um arquivo de parâmetros JSON em um arquivo de parâmetros Bicep. Para obter mais informações, veja decompile-params.

Arquivo de parâmetros

Um arquivo de parâmetros usa o seguinte formato:

using '<path>/<file-name>.bicep'

param <first-parameter-name> = <first-value>
param <second-parameter-name> = <second-value>

Você pode aplicar a using instrução usando um arquivo Bicep, modelos JSON Azure Resource Manager, módulos Bicep e especificações de modelo. Por exemplo:

using './main.bicep'
...

using './azuredeploy.json'
...

using 'br/public:avm/res/storage/storage-account:0.9.0' 
...

using 'br:myacr.azurecr.io/bicep/modules/storage:v1'
...

using 'ts:00000000-0000-0000-0000-000000000000/myResourceGroup/storageSpec:1.0'
...

Para obter mais informações, consulte Usando instrução.

Você pode usar expressões com o valor padrão. Por exemplo:

using 'main.bicep'

param storageName = toLower('MyStorageAccount')
param intValue = 2 + 2

Você pode fazer referência a variáveis de ambiente como valores de parâmetro. Por exemplo:

using './main.bicep'

param intFromEnvironmentVariables = int(readEnvironmentVariable('intEnvVariableName'))

Você pode definir e usar variáveis. Você deve usar a CLI do Bicep versão 0.21.X ou posterior para usar variáveis em .bicepparam arquivos. Veja os exemplos seguintes:

using './main.bicep'

var storagePrefix = 'myStorage'
param primaryStorageName = '${storagePrefix}Primary'
param secondaryStorageName = '${storagePrefix}Secondary'

using './main.bicep'

var testSettings = {
  instanceSize: 'Small'
  instanceCount: 1
}

var prodSettings = {
  instanceSize: 'Large'
  instanceCount: 4
}

param environmentSettings = {
  test: testSettings
  prod: prodSettings
}

Nota

Um arquivo de parâmetros salva valores de parâmetros como texto sem formatação. Por motivos de segurança, não recomendamos o uso dessa abordagem com valores confidenciais, como senhas.

Se precisar passar um parâmetro com um valor sensível, você deve manter o valor em um cofre de chaves. Em vez de adicionar um valor sensível ao seu arquivo de parâmetros, use a getSecret função para recuperá-lo. Para obter mais informações, consulte Usar o Cofre da Chave do Azure para passar um segredo como parâmetro durante a implantação do Bicep.

Formatos de tipo de parâmetro

O exemplo a seguir mostra os formatos de vários tipos de parâmetro: string, integer, Boolean, array e object.

using './main.bicep'

param exampleString = 'test string'
param exampleInt = 2 + 2
param exampleBool = true
param exampleArray = [
  'value 1'
  'value 2'
]
param exampleObject = {
  property1: 'value 1'
  property2: 'value 2'
}

Use a sintaxe Bicep para declarar objetos e matrizes.

Nome de ficheiro

A extensão de arquivo para um arquivo de parâmetros Bicep é .bicepparam.

Para implantar em vários ambientes, crie mais de um arquivo de parâmetros. Quando você usa vários arquivos de parâmetros, rotule-os de acordo com seu uso. Por exemplo, para implantar recursos, use o rótulo main.dev.bicepparam para desenvolvimento e o rótulo main.prod.bicepparam para produção.

Definir valores de parâmetros

Para determinar como definir nomes e valores de parâmetros, abra o arquivo Bicep. Observe a seção de parâmetros do arquivo Bicep. Os exemplos a seguir mostram os parâmetros de um arquivo Bicep chamado main.bicep:

@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

No arquivo de parâmetros, procure o nome de cada parâmetro. Os nomes dos parâmetros no arquivo de parâmetros devem corresponder aos nomes dos parâmetros no arquivo Bicep.

using 'main.bicep'

param storagePrefix
param storageAccountType

A using instrução vincula o arquivo de parâmetros Bicep a um arquivo Bicep. Para obter mais informações, consulte Usando instrução.

Quando você digita a palavra-chave param no Visual Studio Code, ele solicita os parâmetros disponíveis e suas descrições do arquivo Bicep vinculado.

Captura de tela do prompt dos parâmetros disponíveis.

Ao passar o mouse sobre um param nome, você pode ver o tipo de dados e a descrição do parâmetro.

Captura de tela do tipo de dados e descrição do parâmetro.

Revise o tipo de parâmetro, porque os tipos de parâmetro no arquivo de parâmetros devem usar os mesmos tipos que o arquivo Bicep. Neste exemplo, ambos os tipos de parâmetros são cadeias de caracteres:

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

Verifique o arquivo Bicep para parâmetros que incluem um valor padrão. Se um parâmetro tiver um valor padrão, você poderá fornecer um valor no arquivo de parâmetros, mas ele não será necessário. O valor do arquivo de parâmetros substitui o valor padrão do arquivo Bicep.

using 'main.bicep'

param storagePrefix = '' // This value must be provided.
param storageAccountType = '' // This value is optional. Bicep uses default value if not provided.

Para ver se há alguma restrição como comprimento máximo, verifique os valores permitidos do arquivo Bicep. Os valores permitidos especificam o intervalo de valores que você pode fornecer para um parâmetro. Neste exemplo, storagePrefix pode ter no máximo 11 caracteres e storageAccountType deve especificar um valor permitido.

using 'main.bicep'

param storagePrefix = 'storage'
param storageAccountType = 'Standard_ZRS'

Gerar arquivo de parâmetros

Você pode criar um arquivo de parâmetros usando o Visual Studio Code ou a CLI do Bicep. Ambas as ferramentas permitem que você use um arquivo Bicep para gerar um arquivo de parâmetros. Consulte Gerar arquivo de parâmetros para o método Visual Studio Code e Gerar arquivo de parâmetros para o método Bicep CLI.

Construir arquivo de parâmetros Bicep

A partir da CLI do Bicep, você pode criar um arquivo de parâmetros do Bicep em um arquivo de parâmetros JSON. Para obter mais informações, consulte Arquivo de parâmetros de compilação.

Implantar arquivo Bicep com arquivo de parâmetros

CLI do Azure

Na CLI do Azure, você pode passar um arquivo de parâmetros com sua implantação de arquivo Bicep.

Você pode implantar um arquivo Bicep usando um arquivo de parâmetros Bicep com a CLI do Azure versão 2.53.0 ou posterior e a CLI do Bicep versão 0.22.X ou posterior. Com a using instrução dentro do arquivo de parâmetros Bicep, não há necessidade de fornecer o --template-file switch ao especificar um arquivo de parâmetros Bicep para o --parameters switch.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam

Você pode usar parâmetros embutidos e um arquivo de parâmetros de localização na mesma operação de implantação. Por exemplo:

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam \
  --parameters storageAccountType=Standard_LRS

Para obter mais informações, consulte Implantar arquivos Bicep usando a CLI do Azure.

Azure PowerShell

No Azure PowerShell, passe um arquivo de parâmetros locais usando o TemplateParameterFile parâmetro.

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.bicepparam

Você pode usar parâmetros embutidos e um arquivo de parâmetros de localização na mesma operação de implantação. Por exemplo:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.bicepparam `
  -storageAccountType Standard_LRS

Para obter mais informações, consulte Implantar arquivos Bicep usando o Azure PowerShell. Para implantar .bicep arquivos, você precisa do Azure PowerShell versão 5.6.0 ou posterior.

Precedência dos parâmetros

Você pode usar parâmetros embutidos e um arquivo de parâmetros locais na mesma operação de implantação. Por exemplo, você pode especificar alguns valores no arquivo de parâmetros locais e adicionar outros valores embutidos durante a implantação. Se você fornecer valores para um parâmetro no arquivo de parâmetros locais e embutido, o valor embutido terá precedência.

Embora os arquivos de parâmetros externos do Bíceps não sejam suportados no momento, você pode usar um arquivo de parâmetros JSON externo fornecendo o URI para o arquivo. Quando você usa um arquivo de parâmetros externos, forneça todos os valores de parâmetro no arquivo externo. Quando você usa um arquivo externo, não pode passar outros valores embutidos ou de um arquivo local e todos os parâmetros embutidos são ignorados.

Conflitos de nome de parâmetro

Se o arquivo Bicep incluir um parâmetro com o mesmo nome de um dos parâmetros no comando do Azure PowerShell, o Azure PowerShell apresentará o parâmetro do arquivo Bicep com o FromTemplate postfix. Por exemplo, se um parâmetro nomeado ResourceGroupName no arquivo Bicep entrar em conflito com o ResourceGroupName parâmetro no New-AzResourceGroupDeployment cmdlet, você será solicitado a fornecer um valor para ResourceGroupNameFromTemplate. Para evitar essa confusão, use nomes de parâmetros que não são usados para comandos de implantação.

Conteúdos relacionados