通过

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

创建用于 Bicep 部署的参数文件

  • 项目

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

注意

只有 Bicep CLI 版本 0.18.4 或更高版本、Azure CLI 版本 2.47.0 或更高版本以及 Azure PowerShell 版本 9.7.1 或更高版本支持 Bicep 参数文件。

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

可以将 Bicep 参数文件编译为通过使用 Bicep 文件可以部署的 JSON 参数文件。 有关详细信息，请参阅 build-params。 还可以将 JSON 参数文件反向编译为 Bicep 参数文件。 有关详细信息，请参阅 decompile-params。

参数文件

参数文件使用以下格式：

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

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

可以使用 Bicep 文件、JSON Azure 资源管理器模板、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 密钥保管库传递作为参数的机密。

参数类型格式

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

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 文件中的可用参数及其说明。

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

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

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

请查看参数类型，因为参数文件中的参数类型必须使用与 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 uses default value if not provided.

要查看是否存在任何限制（如最大长度），请检查 Bicep 文件的允许值。 允许值指定了可为参数提供的值的范围。 在本例中，storagePrefix 最多可以有 11 个字符，storageAccountType 必须指定允许的值。

using 'main.bicep'

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

生成参数文件

可以通过两种方式创建参数文件：使用 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

有关详细信息，请参阅使用 Azure CLI 部署 Bicep 文件。

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

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

参数优先级

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

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

参数名冲突

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

相关内容