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

Bicep 参数文件允许你在单独的文件中定义参数值，并将这些值传递给 main.bicep。 它们非常适合用于因订阅、环境或区域不同而变化的值。

主要优势包括：

  • 在实现灵活性的同时，保持基础结构即代码（IaC）部署之间的一致性。
  • 支持成本优化，例如在不更改核心基础结构的情况下正确调整非生产环境的大小。
  • 通过在源代码管理中保留参数文件并将相应的文件传递到每个部署阶段，实现简化的 CI/CD 管道。

注意

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

你可以使用：

  • 原生 Bicep 参数文件（扩展名为 .bicepparam），或
  • 标准 JSON 参数文件。

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

若要部署到多个环境，请创建多个参数文件。 使用多个参数文件时，请根据它们的使用对其进行标记。 例如，要部署资源，请将标签 main.dev.bicepparam 用于开发，并将标签 main.prod.bicepparam 用于生产。

可以将 Bicep 参数文件编译为 JSON 参数文件，并借助 Bicep 文件进行部署。 有关详细信息，请参阅 build-params。 还可以将 JSON 参数文件反编译为Bicep参数文件。 有关详细信息，请参阅 decompile-params。

Warning

参数文件将参数值保存为纯文本。 出于安全原因，请勿将此方法与密码等敏感值一起使用。 如果需要传递具有敏感值的参数，请将该值保留在密钥保管库中。 请使用 getSecret 函数检索敏感值，而不是将其添加到参数文件。 有关详细信息，请参阅在 Bicep 部署期间使用 Azure 密钥保管库传递作为参数的机密。

定义参数文件

参数文件使用以下格式：

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

type <user-defined-data-type-name> = <type-expression>

var <variable-name> <data-type> = <variable-value>

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

若要确定如何定义参数名称和值，请打开 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 文件关联起来。 可以将多个参数文件与单个Bicep文件相关联。 每个参数文件通常通过使用 using 语句 关联到特定的 Bicep 文件。

如果不想将参数文件链接到特定Bicep文件，请使用 using none。 Bicep CLI 版本 0.31.0 或更高版本支持 using none 功能。

有关更多信息，请参阅 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'

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

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 语法声明对象和数组。

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

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
}

可以定义用户定义的数据类型。 例如：

using './main.bicep'

// Define a reusable type for tags with optional properties
type TagValues = {
  environment: 'dev' | 'test' | 'production'
  project: string
}

var tagsExample TagValues = {
  environment: 'dev'
  project: 'bicep-sample'
}

param tags = tagsExample

生成和构建参数文件

可以通过两种方式创建参数文件：使用 Visual Studio Code 或 Bicep CLI。 这两种工具都支持使用 Bicep 文件生成参数文件。 请参阅生成参数文件以了解 Visual Studio Code 方法，以及生成参数文件以了解 Bicep CLI 方法。

在 Bicep CLI 中，可以将 Bicep 参数文件转换为 JSON 参数文件。 有关更多信息，请参阅生成参数文件。

使用参数文件部署 Bicep 文件

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

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

以下示例演示了使用外部 JSON 参数文件的Azure CLI示例：

az deployment group create \
  --resource-group my-rg \
  --template-file main.bicep \
  --parameters https://storageaccount.blob.core.chinacloudapi.cn/templates/main.parameters.json

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

相关内容

  • Last updated on