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

Nota

O arquivo de parâmetros do Bicep só é suportado 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 usando 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 para implantar com um arquivo do Bicep. Consulte build-params. Você também pode descompilar um arquivo de parâmetros JSON em um arquivo de parâmetros Bicep. Consulte 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 o arquivo Bicep, modelos JSON ARM, módulos Bicep e especificações de modelo. Por exemplo:

using './main.bicep'
...

using './azuredeploy.json'
...

using 'br/public:storage/storage-account:3.0.1'
...

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 a instrução using .

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. A CLI do Bíceps versão 0.21.X ou superior é necessária para usar variáveis no arquivo .bicepparam. Seguem-se 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
}

Vale a pena notar que o arquivo de parâmetros salva valores de parâmetros 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 sensível, mantenha o valor em um cofre de chaves. Em vez de adicionar o valor sensível ao seu arquivo de parâmetros, use a função getSecret para recuperá-lo. Para obter mais informações, consulte Usar o Cofre da Chave do Azure para passar o valor do parâmetro seguro durante a implantação do Bicep.

Formatos de tipo de parâmetro

O exemplo a seguir mostra os formatos de diferentes tipos de parâmetros: 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

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

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

Definir valores de parâmetros

Para determinar como definir os nomes e valores dos 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, o primeiro detalhe a ser observado é 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.

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 do prompt dos parâmetros disponíveis.

Ao passar o mouse sobre um nome param, 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âmetros no arquivo de parâmetros devem usar os mesmos tipos que o arquivo Bicep. Neste exemplo, ambos os tipos de parâmetro são strings.

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

Verifique o arquivo Bicep para 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 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 will use default value if not provided.

Verifique os valores permitidos do Bíceps 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 um máximo de 11 caracteres e storageAccountType deve especificar um valor permitido.

using 'main.bicep'

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

Gerar arquivo de parâmetros

Para gerar um arquivo de parâmetros, você tem duas opções: por meio do Visual Studio Code ou usando a CLI do Bicep. Ambos os métodos permitem que você derive o arquivo de parâmetros de um arquivo Bicep. No Visual Studio Code, consulte Gerar arquivo de parâmetros. Na CLI do Bicep, consulte Gerar arquivo de parâmetros.

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âmetro com sua implantação de arquivo Bicep.

Com a CLI do Azure versão 2.53.0 ou posterior e a CLI do Bicep versão 0.22.X ou superior, você pode implantar um arquivo Bicep utilizando um arquivo de parâmetro Bicep. 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âmetro 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 recursos com Bicep e 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 recursos com Bicep e Azure PowerShell. Para implantar arquivos .bicep , 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.

É possível usar um arquivo de parâmetros JSON externo, fornecendo o URI para o arquivo. O arquivo de parâmetros externos do Bicep não é suportado no momento. Quando você usa um arquivo de parâmetros externos, não pode passar outros valores embutidos ou de um arquivo local. Todos os parâmetros embutidos são ignorados. Forneça todos os valores de parâmetro no arquivo externo.

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 PowerShell, o PowerShell apresentará o parâmetro do arquivo Bicep com o postfix FromTemplate. Por exemplo, um parâmetro nomeado ResourceGroupName no arquivo Bicep entra em conflito com o ResourceGroupName parâmetro no cmdlet New-AzResourceGroupDeployment . 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.

Próximos passos