共用方式為

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

Bicep 参数文件允许你在单个文件中定义值，然后将其传递到 main.bicep 文件中。 参数文件显示了可能因特定订阅、环境和/或区域而变化的值。 利用参数文件可推动 IaC 部署中的一致性，同时提供灵活性。 这种灵活性的一些可能允许组织通过在维护相同的核心基础结构的同时正确调整非生产环境的大小来利用成本优势。

这些参数文件还有助于启用简化的 CI/CD 部署方法。 每个参数文件都在源代码管理下，并传递到相应的自动部署步骤中。 这些参数文件可确保部署体验一致。

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

注意

Bicep 参数文件仅在 Bicep CLI 0.18.4 或更高版本、Azure CLI 2.47.0 或更高版本和 Azure PowerShell 9.7.1 或更高版本中受支持。 using none Bicep CLI 0.31.0 或更高版本支持此功能。

单个 Bicep 文件可以与多个参数文件相关联。 但是，每个参数文件通常链接到一个特定的 Bicep 文件，除非指定了 using none。 此关联是使用using参数文件中的语句建立的。

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

参数文件

参数文件使用以下格式：

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

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 statement。

可以应用 using none 该语句来指示参数文件在创作或编译期间未绑定到特定的 Bicep 模板。 这会将参数文件与特定模板分离，从而在跨部署定义和使用参数的方式方面具有更大的灵活性。 有关详细信息，请参阅 Using none 语句。

可以使用表达式作为参数值。 例如：

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'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

在参数文件中，查找每个参数的名称。 参数文件中的参数名必须与 Bicep 文件中的参数名匹配。

using 'main.bicep'

param storagePrefix
param storageAccountType

using 语句将 Bicep 参数文件绑定到 Bicep 文件。 有关更多信息，请参阅 Using statement。

在 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 语句时，无需在为 --template-file 开关指定 Bicep 参数文件时提供 --parameters 开关。

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 的参数与 ResourceGroupName 中的 New-AzResourceGroupDeployment 参数冲突，系统会提示你提供 的值。 为了避免这种混淆，请使用未用于部署命令的参数名称。

相关内容