通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

为 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>

可以对 Bicep 文件、Azure 资源管理器 JSON 模板、Bicep 模块和模板规格使用 using 语句。 例如：

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

有关详细信息，请参阅 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 文件的“参数”部分。 下面的示例显示名为 main.bicep 的 Bicep 文件中的参数：

@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  '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 必须指定允许的值。

using 'main.bicep'

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

生成参数文件

可以通过两种方式创建参数文件：使用 VS Code 或 Bicep CLI。 这两种工具都支持使用 Bicep 文件生成参数文件。 请参阅生成参数文件以了解 VS 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 或更高版本。

参数优先级

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

虽然当前不支持外部 Bicep 参数文件，但可以通过提供文件的 URI 来使用外部 JSON 参数文件。 当使用外部参数文件时，请在外部文件中提供所有参数值，因为无法以内联方式或从本地文件传递其他值，并且会忽略所有内联参数。

参数名冲突

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

后续步骤