Bicep 中的参数

项目
01/08/2024

本文介绍如何定义和使用 Bicep 文件中的参数。为参数提供不同的值即可针对不同环境重复使用 Bicep 文件。

资源管理器会在启动部署操作之前解析参数值。只要使用参数，资源管理器就会将其替换为解析的值。

每个参数都必需设置为数据类型之一。

一个 Bicep 文件中最多可以有 256 个参数。有关详细信息，请参阅模板限制。

有关参数最佳做法，请参阅参数。

声明

每个参数都具有名称和数据类型。（可选）为参数提供默认值。

param <parameter-name> <parameter-data-type> = <default-value>

参数不能与同一范围内的变量、资源、输出或其他参数同名。

下面的示例演示参数的基本声明。

param demoString string
param demoInt int
param demoBool bool
param demoObject object
param demoArray array

param 关键字也用于 .bicepparam 文件。在 .bicepparam 文件中，无需指定数据类型，因为它已在 Bicep 文件中定义。

param <parameter-name> = <value>

有关详细信息，请查看参数文件。

用户定义的类型表达式可以用作 param 语句的类型子句。例如：

param storageAccountConfig {
  name: string
  sku: string
}

有关详细信息，请参阅用户定义的数据类型。

默认值

可以为参数指定默认值。如果在部署过程中未提供值，则使用默认值。

param demoParam string = 'Contoso'

可以使用具有默认值的表达式。表达式不允许有其他参数属性。不能在 parameters 节中使用 reference 函数或任何 list 函数。在解析参数时，这些函数获取资源的运行时状态，并且不能在部署之前执行。

param location string = resourceGroup().location

可以使用另一个参数值来生成默认值。以下模板基于站点名称构造主机计划名称。

param siteName string = 'site${uniqueString(resourceGroup().id)}'
param hostingPlanName string = '${siteName}-plan'

output siteNameOutput string = siteName
output hostingPlanOutput string = hostingPlanName

修饰符

参数对约束或元数据使用修饰器。修饰器采用 @expression 格式，并放置在参数的声明上方。你可以将参数标记为安全，指定允许的值，为字符串设置最小和最大长度，为整数设置最小值和最大值，并提供参数的说明。

下面的示例演示了修饰器的两个常见用途。

@secure()
param demoPassword string

@description('Must be at least Standard_A3 to support 2 NICs.')
param virtualMachineSize string = 'Standard_DS1_v2'

下表介绍了可用的修饰器及其使用方式。

修饰器	应用于	参数	说明
允许	all	array	参数允许的值。使用此修饰器以确保用户提供正确的值。
description	all	string	解释如何使用参数的文本。通过门户向用户显示该说明。
maxLength	数组、字符串	int	字符串和数组参数的最大长度。最大值包含在内。
maxValue	int	int	整数参数的最大值。最大值包含在内。
metadata	all	object	应用于参数的自定义属性。可以包含与说明修饰器等效的说明属性。
minLength	数组、字符串	int	字符串和数组参数的最小长度。最小值包含在内。
minValue	int	int	整数参数的最小值。最小值包含在内。
secure	字符串、对象	无	将参数标记为安全。安全参数的值不会保存到部署历史记录中，也不会被记录下来。有关详细信息，请参阅保护字符串和对象。

修饰器位于 sys 命名空间中。如果需要将修饰器与具有相同名称的其他项区分开来，请在修饰器前面加上 sys。例如，如果 Bicep 文件包含名为 description 的参数，则必须在使用说明修饰器时添加 sys 命名空间。

@sys.description('The name of the instance.')
param name string
@sys.description('The description of the instance to display.')
param description string

以下部分介绍了可用的修饰器。

安全参数

可以将字符串或对象参数标记为安全。安全参数的值不会保存到部署历史记录中，不会有日志记录。

@secure()
param demoPassword string

@secure()
param demoSecretObject object

允许的值

可以为参数定义允许的值。可在数组中提供允许的值。如果为参数传入的值不是允许的值之一，则部署会在验证过程中失败。

@allowed([
  'one'
  'two'
])
param demoEnum string

如果为数组参数定义允许的值，则实际值可以是允许值的任何子集。

长度约束

可以为字符串和数组参数指定最小和最大长度。可以设置一个或两个约束。对于字符串，长度指示字符数。对于数组，长度指示数组中的项数。

以下示例声明两个参数。一个参数对应于一个必须具有 3-24 个字符的存储帐户名称。另一个参数是一个必须包含 1-5 个项的数组。

@minLength(3)
@maxLength(24)
param storageAccountName string

@minLength(1)
@maxLength(5)
param appNames array

整数约束

可以为整数参数设置最小值和最大值。可以设置一个或两个约束。

@minValue(1)
@maxValue(12)
param month int

说明

若要帮助用户了解要提供的值，请向参数添加说明。当用户通过门户部署模板时，说明文本自动用作该参数的提示。仅当文本提供的信息超过可从参数名称推断出的信息时，才添加说明。

@description('Must be at least Standard_A3 to support 2 NICs.')
param virtualMachineSize string = 'Standard_DS1_v2'

Markdown 格式的文本可用于说明文本：

@description('''
Storage account name restrictions:
- Storage account names must be between 3 and 24 characters in length and may contain numbers and lowercase letters only.
- Your storage account name must be unique within Azure. No two storage accounts can have the same name.
''')
@minLength(3)
@maxLength(24)
param storageAccountName string

将光标悬停在 VS Code 中的 storageAccountName 上时，会看到格式化文本：

Use Markdown-formatted text in VSCode

确保文本遵循正确的 Markdown 格式；否则呈现时可能无法正确显示

元数据

如果你有要应用于参数的自定义属性，请添加元数据修饰器。在元数据中，使用自定义名称和值来定义对象。为元数据定义的对象可以包含任何名称和类型的属性。

可以使用此修饰器跟踪不应添加到 description 中的参数的相关信息。

@description('Configuration values that are applied when the application starts.')
@metadata({
  source: 'database'
  contact: 'Web team'
})
param settings object

当向 @metadata() 修饰器提供与另一个修饰器冲突的属性时，该修饰器始终优先于 @metadata() 修饰器中的任何内容。因此，@metadata() 值中的冲突属性是冗余的，将被替换。有关详细信息，请参阅无冲突元数据。

使用参数

若要引用参数的值，请使用参数名称。以下示例使用参数值表示密钥保管库名称。

param vaultName string = 'keyVault${uniqueString(resourceGroup().id)}'

resource keyvault 'Microsoft.KeyVault/vaults@2019-09-01' = {
  name: vaultName
  ...
}

对象作为参数

通过将相关值作为对象传入，可以更轻松地对这些值进行组织。此方式还可以减少模板中的参数的数量。

以下示例显示的参数是一个对象。默认值显示对象的预期属性。定义要部署的资源时，将使用这些属性。

param vNetSettings object = {
  name: 'VNet1'
  location: 'chinaeast'
  addressPrefixes: [
    {
      name: 'firstPrefix'
      addressPrefix: '10.0.0.0/22'
    }
  ]
  subnets: [
    {
      name: 'firstSubnet'
      addressPrefix: '10.0.0.0/24'
    }
    {
      name: 'secondSubnet'
      addressPrefix: '10.0.1.0/24'
    }
  ]
}

resource vnet 'Microsoft.Network/virtualNetworks@2020-06-01' = {
  name: vNetSettings.name
  location: vNetSettings.location
  properties: {
    addressSpace: {
      addressPrefixes: [
        vNetSettings.addressPrefixes[0].addressPrefix
      ]
    }
    subnets: [
      {
        name: vNetSettings.subnets[0].name
        properties: {
          addressPrefix: vNetSettings.subnets[0].addressPrefix
        }
      }
      {
        name: vNetSettings.subnets[1].name
        properties: {
          addressPrefix: vNetSettings.subnets[1].addressPrefix
        }
      }
    ]
  }
}

后续步骤

若要了解参数的可用属性，请参阅了解 Bicep 文件的结构和语法。
若要了解如何将参数值作为文件传入，请参阅创建 Bicep 参数文件。