通过

为 Bicep 部署创建参数文件

  • 项目

可以使用带 .bicepparam 文件扩展名的 Bicep 参数文件或包含参数值的 JSON 参数文件，而不是在脚本中以内联值的形式传递参数。 本文介绍如何创建参数文件。

注意

Bicep 参数文件仅在 Bicep CLI 0.18.4 或更新版本、Azure CLI 版本 2.47.0 或更新版本以及 Azure PowerShell 版本 9.7.1 或更新版本中受支持。

一个 Bicep 文件可以有多个与之关联的 Bicep 参数文件。 但是，每个 Bicep 参数文件都只用于一个特定的 Bicep 文件。 此关系是通过 Bicep 参数文件中的 using 语句建立的。

可以将 Bicep 参数文件编译为 JSON 参数文件，以便使用 Bicep 文件进行部署。 请参阅 build-params。 还可以将 JSON 参数文件反向编译为 Bicep 参数文件。 请参阅 decompile-params。

参数文件

参数文件使用以下格式：

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

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

可以将 using 语句与 Bicep 文件、ARM JSON 模板、Bicep 模块和模板规范配合使用。 例如：

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'
...

有关详细信息，请参阅 using 语句。

可以使用具有默认值的表达式。 例如：

using 'main.bicep'

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

可以将环境变量引用为参数值。 例如：

using './main.bicep'

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

可以定义和使用变量。 需要安装 Bicep CLI 0.21.X 或更高版本才能在 .bicepparam 文件中使用变量。 下面是一些示例：

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
}

值得注意的是，参数文件会将参数值另存为纯文本。 出于安全原因，不建议对密码等敏感值使用此方法。 如果必须传递带有敏感值的参数，请将值保存在密钥保管库中。 使用 getSecret 函数检索敏感值，而不是将敏感值添加到参数文件。 有关详细信息，请参阅在部署 Bicep 过程中使用 Azure Key Vault 传递安全参数值。

参数类型格式

下面的示例显示了不同参数类型的格式：字符串、整数、布尔值、数组和对象。

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

使用 Bicep 语法声明对象和数组。

文件名

Bicep 参数文件的文件扩展名为 .bicepparam。

若要部署到不同的环境，请创建多个参数文件。 命名参数文件时，请标识其用途，如开发和生产。 例如，使用 main.dev.bicepparam 和 main.prod.bicepparam 来部署资源。

定义参数值

若要确定如何定义参数名称和值，请打开 Bicep 文件。 查看 Bicep 文件的 parameters 节。 下面的示例显示名为 main.bicep 的 Bicep 文件中的参数。

@maxLength(11)
param storagePrefix string

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

在参数文件中，要注意的第一个细节是每个参数的名称。 参数文件中的参数名必须与 Bicep 文件中的参数名匹配。

using 'main.bicep'

param storagePrefix
param storageAccountType

using 语句将 Bicep 参数文件绑定到 Bicep 文件。 有关详细信息，请参阅 using 语句。

在 Visual Studio Code 中键入关键字 param 后，系统会提示链接的 Bicep 文件中的可用参数及其说明：

提示可用参数的屏幕截图。

将鼠标悬停在参数名称上时，可以看到参数数据类型和说明。

参数数据类型和说明的屏幕截图。

注意参数类型。 参数文件中的参数类型必须使用与 Bicep 文件相同的类型。 在本例中，两个参数类型都是字符串。

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

检查 Bicep 文件中的参数是否有默认值。 如果参数具有默认值，则可以在参数文件中提供值，但不一定要这样做。 参数文件值会替代 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.

检查 Bicep 的允许值和任何限制，例如最大长度。 这些值指定可为参数提供的值的范围。 在本例中，storagePrefix 最多可以有 11 个字符，storageAccountType 必须指定允许的值。

注意

参数文件只能包含在 Bicep 文件中定义的参数的值。 如果参数文件包含的额外参数与 Bicep 文件参数不匹配，则会收到错误。

生成参数文件

若要生成参数文件，你有两个选择：通过 Visual Studio Code 或使用 Bicep CLI。 这两种方法都可以从 Bicep 文件派生参数文件。 Visual Studio Code 中的具体操作请参阅生成参数文件。 Bicep CLI 中的具体操作请参阅生成参数文件。

生成 Bicep 参数文件

在 Bicep CLI 中，可以将 Bicep 参数文件生成为 JSON 参数文件。 有关详细信息，请参阅生成 Bicep 参数文件。

使用参数文件部署 Bicep 文件

Azure CLI

从 Azure CLI 中，可以通过 Bicep 文件部署传递参数文件。

使用 Azure CLI 2.53.0 或更高版本和 Bicep CLI 0.22.X 或更高版本，可以使用 Bicep 参数文件来部署 Bicep 文件。 在 Bicep 参数文件中使用 using 语句时，无需在为 --parameters 开关指定 Bicep 参数文件时提供 --template-file 开关。

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

可以在同一部署操作中使用内联参数和位置参数文件。 例如：

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

有关详细信息，请参阅使用 Bicep 和 Azure CLI 部署资源。

Azure PowerShell

在 Azure PowerShell 中，使用 TemplateParameterFile 参数传递本地参数文件。

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

可以在同一部署操作中使用内联参数和位置参数文件。 例如：

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

有关详细信息，请参阅使用 Bicep 和 Azure PowerShell 部署资源。 要部署 .bicep 文件，需要 Azure PowerShell 版本 5.6.0 或更高版本。

参数优先级

可以在同一部署操作中使用内联参数和本地参数文件。 例如，可以在本地参数文件中指定某些值，并在部署期间添加其他内联值。 如果同时为本地参数文件中的参数和内联参数提供值，则内联值优先。

可以通过提供文件的 URI 来使用外部 JSON 参数文件。 当前不支持外部 Bicep 参数文件。 使用外部参数文件时，不能传递是内联值的或来自本地文件的其他值。 会忽略所有内联参数。 提供外部文件中的所有参数值。

参数名冲突

如果 Bicep 文件中有一个参数与 PowerShell 命令中的某个参数同名，PowerShell 会使用后缀 FromTemplate 显示 Bicep 文件中的参数。 例如，Bicep 文件中名为 ResourceGroupName 的参数与 New-AzResourceGroupDeployment cmdlet 中的 ResourceGroupName 参数冲突。 系统会提示你提供 ResourceGroupNameFromTemplate 的值。 为了避免这种混淆，请使用未用于部署命令的参数名称。

后续步骤