Criar um arquivo de parâmetros para a implantação do Bicep
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'
}
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.
Ao passar o mouse sobre um param
nome, você pode ver o tipo de dados e a 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
- Para obter mais informações sobre como definir parâmetros em um arquivo Bicep, consulte Parâmetros no Bicep.
- Para obter valores confidenciais, consulte Usar o Cofre da Chave do Azure para passar o valor do parâmetro seguro durante a implantação.