Bicep 中的参数

项目
09/30/2024

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

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

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

Bicep 最多允许 256 个参数。有关详细信息，请参阅模板限制。

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

培训资源

如果希望通过分步指导了解参数，请参阅使用参数构建可重复使用的 Bicep 模板。

定义参数

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

@<decorator>(<argument>)
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 格式，并放置在参数的声明上方。下表显示了参数的可用修饰器。

修饰器	应用于	参数	说明
允许	all	array	使用此修饰器以确保用户提供正确的值。此修饰器仅在 `param` 语句上受允许。要声明某个属性必须是 `type` 或 `output` 语句中一组预定义值之一，请使用联合类型语法。联合类型语法也可以在 `param` 语句中使用。
说明	all	string	解释如何使用参数的文本。通过门户向用户显示该说明。
鉴别器	object	string	使用此修饰器来确保标识和管理正确的子类。有关详细信息，请参阅自定义标记的联合数据类型。
maxLength	数组、字符串	int	字符串和数组参数的最大长度。最大值包含在内。
maxValue	int	int	整数参数的最大值。最大值包含在内。
metadata	all	object	应用于参数的自定义属性。可以包含与说明修饰器等效的说明属性。
minLength	数组、字符串	int	字符串和数组参数的最小长度。最小值包含在内。
minValue	int	int	整数参数的最小值。最小值包含在内。
sealed	object	无	如果 use-define 数据类型的属性名称可能存在拼写错误，则将 BCP089 从警告提升为错误。有关详细信息，请参阅提升错误级别。
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

允许的值

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

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

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

说明

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

@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 上时，会看到格式化文本：

在 VSCode 中使用 Markdown 格式的文本

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

鉴别器

请参阅自定义标记联合数据类型。

整数约束

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

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

长度约束

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

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

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

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

元数据

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

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

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

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

已密封

请参阅提升错误级别。

安全参数

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

@secure()
param demoPassword string

@secure()
param demoSecretObject object

存在多个与此修饰器相关的 linter 规则：安全参数默认值、嵌套部署中的安全参数、参数中的安全机密。

使用参数

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

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@2023-11-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 参数文件。
若要了解如何在部署时提供参数值，请参阅使用 Azure CLI 进行部署和使用 Azure PowerShell 进行部署。

通过