Compartilhar via

Criar arquivos de parâmetros para implantação do Bicep

  • Artigo

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 arquivo .bicepparam ou um arquivo de parâmetros JSON que contém os valores de parâmetro. Este artigo mostra como criar arquivos de parâmetros.

Observação

O arquivo de parâmetros Bicep só tem suporte na CLI do Bicep versão 0.18.4 ou mais recente, na CLI do Azure versão 2.47.0 ou mais recente e no Azure PowerShell versão 9.7.1 ou mais recente.

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. Essa relação é estabelecida com a instrução using no arquivo de parâmetros do Bicep.

Você pode compilar arquivos de parâmetros Bicep em arquivos de parâmetros JSON para implantar com um arquivo Bicep. Confira os build-params. Você também pode descompilar um arquivo de parâmetros JSON em um arquivo de parâmetros do Bicep. Confira 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 usar a instrução using com um arquivo Bicep, modelos JSON do 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, confira a Instrução using.

É possível usar as expressões com o valor padrão. Por exemplo:

using 'main.bicep'

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

Você pode referenciar 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. Versão 0.21.X ou superior da CLI do Bicep é obrigatória para usar variáveis em arquivos .bicepparam. Estes são alguns exemplos:

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
}

É importante observar que o arquivo de parâmetros salva valores de parâmetro como texto sem formatação. Por motivos de segurança, essa abordagem não é recomendada para valores confidenciais, como senhas. Se você precisar passar um parâmetro com um valor confidencial, mantenha o valor em um cofre de chaves. Em vez de adicionar um valor confidencial ao arquivo de parâmetros, use a função getSecret para recuperá-lo. Para obter mais informações, confira Usar o Azure Key Vault para transmitir um valor de parâmetro seguro durante a implantação do Bicep.

Formatos do tipo de parâmetro

O exemplo a seguir mostra os formatos dos diferentes tipos de parâmetro: cadeia de caracteres, inteiro, booleano, matriz e objeto.

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 do arquivo

O arquivo de parâmetros Bicep tem a extensão de arquivo de .bicepparam.

Para implantar em ambientes diferentes, crie mais de um arquivo de parâmetros. Ao nomear vários arquivos de parâmetros, rotule seu uso como desenvolvimento e produção. Por exemplo, use main.dev.bicepparam para desenvolvimento e main.prod.bicepparam para produção para implantar recursos.

Definir valores de parâmetro

Para determinar como definir nomes e valores de parâmetros, abra o arquivo Bicep. Consulte a seção 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, o primeiro detalhe a ser observado é o nome de cada parâmetro. Os nomes de parâmetro no arquivo de parâmetros devem corresponder àqueles no seu arquivo Bicep.

using 'main.bicep'

param storagePrefix
param storageAccountType

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

Depois de digitar 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 da solicitação dos parâmetros disponíveis.

Ao passar o mouse sobre um nome de parâmetro, 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.

Observe o tipo de parâmetro. Os tipos de parâmetro no arquivo de parâmetros devem ser iguais àqueles no seu arquivo Bicep. Neste exemplo, ambos os tipos de parâmetro são cadeias de caracteres.

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

Verifique o arquivo Bicep em busca de parâmetros com um valor padrão. Se um parâmetro tiver um valor padrão, você poderá fornecer um valor no arquivo de parâmetros, mas isso não é obrigató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 will use default value if not provided.

Verifique os valores permitidos do arquivo Bicep e quaisquer restrições, como comprimento máximo. Esses valores 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 de duas maneiras: com o VS Code ou com a CLI do Bicep. Ambas as ferramentas permitem usar um arquivo Bicep para gerar um arquivo de parâmetros. Consulte Gerar arquivo de parâmetros para o método do VS Code e Gerar arquivo de parâmetros para o método da CLI do Bicep.

Arquivo de parâmetros de build Bicep

Na CLI do Bicep, você pode criar um arquivo de parâmetros Bicep em um arquivo de parâmetros JSON. Para obter mais informações, confira Arquivo de parâmetros de build.

Implantar o arquivo Bicep com o arquivo de parâmetros

CLI do Azure

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

Você pode implantar um arquivo Bicep usando um arquivo de parâmetros do Bicep com a versão 2.53.0 ou posterior da CLI do Azure e versão 0.22.X ou superior da CLI do Bicep. Com a instrução using no arquivo de parâmetros do Bicep, não é necessário fornecer a opção --template-file ao especificar um arquivo de parâmetros do Bicep para a opção --parameters.

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 recursos com o Bicep e a CLI do Azure.

PowerShell do Azure

No Azure PowerShell, transmita um arquivo de parâmetros local usando o parâmetro TemplateParameterFile.

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 recursos com o Bicep e o Azure PowerShell. Para implantar arquivos .bicep, você precisará da versão 5.6.0 ou posterior do Azure PowerShell.

Precedência de parâmetro

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

Embora não haja suporte para arquivos de parâmetros externos do Bicep no momento, é possível usar um arquivo de parâmetros JSON externo fornecendo o URI do arquivo. Ao usar um arquivo de parâmetros externo, forneça todos os valores de parâmetro no arquivo externo, pois você não poderá passar outros valores nem mesmo em linha ou de um arquivo local, e todos os parâmetros em linha serã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 do comando do PowerShell, o PowerShell apresentará o parâmetro do arquivo Bicep com o sufixo FromTemplate. Por exemplo, um parâmetro chamado ResourceGroupName no arquivo Bicep entra em conflito com o parâmetro ResourceGroupName no cmdlet New-AzResourceGroupDeployment. Você é 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.

Próximas etapas