了解参数

8 分钟

使用参数，你可以在部署时向 Bicep 模板提供信息。可以通过在模板中声明参数，使 Bicep 模板灵活且可重用。

修饰器提供了一种将约束和元数据附加到参数的方式，可帮助使用模板的任何人员了解他们需要提供的信息。

在本单元中，你将了解参数和修饰器。

声明参数

在 Bicep 模板中，使用 param 关键字声明一个参数。可以将这些声明置于模板文件的任何位置，但通常最好将它们放在文件顶部，这样可以使 Bicep 代码易于读取。

下面是声明参数的方式：

param environmentName string

让我们看看每个部分是如何工作的：

param 向 Bicep 表示你正在声明一个参数。
environmentName 指的是参数名称。虽然参数名称可以是任何内容，但应使名称对模板用户清晰易懂。在同一模板中，还可以使用参数的名称来引用参数。参数名称必须唯一。它们不能与同一个 Bicep 文件中的变量或资源具有相同名称。

提示

将最佳做法命名约定用于参数声明。好的命名约定可以使模板易于阅读和理解。确保使用清晰的描述性名称，并采用一致的命名策略。
string 指的是参数类型。

提示

仔细考虑模板所使用的参数。尝试将参数用于在不同部署之间更改的设置。变量和硬编码值可用于在部署之间不会发生更改的设置。

添加默认值

可以将默认值分配给模板中的参数。通过分配默认值，可以使参数成为可选参数。如果部署模板时没有为该参数指定值，则分配默认值。

下面介绍如何添加默认值：

param environmentName string = 'dev'

为参数 environmentName 分配默认值 dev。

你可以使用表达式作为默认值。下面是一个名为 location 的字符串参数示例，其中默认值设置为当前资源组的位置：

param location string = resourceGroup().location

提示

请注意使用的默认值。请确保用户可以安全地将 Bicep 文件部署为默认值。例如，考虑使用便宜的定价层和 SKU，这样将模板部署到测试环境的用户就不会产生不必要的成本。

了解参数类型

声明参数时，需要告知 Bicep 参数将包含的信息类型。 Bicep 将确保分配给参数的值与参数类型兼容。

Bicep 中的参数可以是以下类型之一：

string，可用于输入任意文本。
int，它允许你输入一个数字。
bool，它表示布尔值（true 或 false）。
object 和 array，它们表示结构化数据和列表。

对象

可以使用对象参数将结构化数据组合在一起。一个对象可以具有多个不同类型的属性。可以在 Bicep 文件中的资源定义、变量内或表达式内使用对象。下面是对象示例：

param appServicePlanSku object = {
  name: 'F1'
  tier: 'Free'
  capacity: 1
}

此参数是一个对象，具有两个字符串属性 name 和 tier，以及一个整数属性 capacity。请注意，每个属性都位于其自己的行中。

在模板中引用参数时，可以使用点后跟属性名称来选择对象的单个属性，如以下示例所示：

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku.name
    tier: appServicePlanSku.tier
    capacity: appServicePlanSku.capacity
  }
}

重要

请记住，不要指定对象中每个属性的类型。但是，使用属性值时，其类型必须与预期匹配。在上一示例中，应用服务计划 SKU 的名称和层都必须是字符串。

使用对象参数的另一个示例是指定资源标记。可以将自定义标记元数据附加到部署的资源，你可以使用这些元数据来标识有关资源的重要信息。

标记可用于跟踪哪个团队拥有资源，或者当资源属于生产环境或非生产环境的情况。通常，你将为每个环境使用不同标记，但需要对模板内的所有资源重用相同标记值。因此，资源标记非常适用于对象参数，如以下示例所示：

param resourceTags object = {
  EnvironmentName: 'Test'
  CostCenter: '1000100'
  Team: 'Human Resources'
}

每当在 Bicep 文件中定义资源时，都可以在定义 tags 属性的位置重用它：

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  tags: resourceTags
  sku: {
    name: 'S1'
  }
}

resource appServiceApp 'Microsoft.Web/sites@' = {
  name: appServiceAppName
  location: location
  tags: resourceTags
  kind: 'app'
  properties: {
    serverFarmId: appServicePlan.id
  }
}

数组

数组是项列表。例如，可以使用字符串值数组来声明 Azure Monitor 操作组的电子邮件地址列表。或者，可以使用对象数组来表示虚拟网络的子网列表。

备注

不能指定数组需要包含的单个项的类型。例如，不能指定数组必须包含字符串。

我们分析一个示例。 Azure Cosmos DB 允许你创建跨多个区域的数据库帐户，并且它自动为你处理数据复制。部署新数据库帐户时，需要指定想要将帐户部署到的 Azure 区域列表。通常，需要为不同环境提供不同的位置列表。例如，若要在测试环境中节省资金，只能使用一个或两个位置。但在生产环境中，可以使用多个位置。

可以创建一个指定位置列表的数组参数：

param cosmosDBAccountLocations array = [
  {
    locationName: 'australiaeast'
  }
  {
    locationName: 'southcentralus'
  }
  {
    locationName: 'westeurope'
  }
]

提示

前面的示例是一个对象数组。每个对象都有一个 locationName 属性，这正是 Azure Cosmos DB 所期望的。在 Visual Studio Code 中使用资源定义时，可以首先输入资源属性，以便从 Bicep 工具获取 IntelliSense。可以通过此方法创建一些示例值。对配置感到满意后，将 Bicep 代码的那一部分移动到参数。这样，就可以将硬编码属性替换为可在每次部署期间更改的参数，同时仍确保正确配置资源。

声明 Azure Cosmos DB 资源时，现在可以引用数组参数：

resource account 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  name: accountName
  location: location
  properties: {
    locations: cosmosDBAccountLocations
  }
}

然后，通过更改参数值，可以轻松为开发环境使用不同的参数值。很快，你将了解如何在不修改原始模板的情况下提供不同的参数值。

指定允许值列表

有时需要确保参数具有特定值。例如，你的团队可能决定使用 Premium v3 SKU 部署生产应用服务计划。若要强制实施此规则，可以使用 @allowed 参数修饰器。参数修饰器是一种向 Bicep 提供有关所需参数值信息的方法。下面介绍了如何限制名为 appServicePlanSkuName 的字符串参数，以便只分配几个特定值：

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
param appServicePlanSkuName string

提示

请尽量少用 @allowed 修饰器。如果过于广泛地使用此修饰器，如果不使列表保持最新，可能会阻止有效部署。前面的示例仅允许在生产环境中使用 Premium v3 SKU。如果需要使用相同的模板来部署一些成本较低的非生产环境，则允许的值列表可能会阻止你使用所需的其他 SKU。

限制参数长度和值

使用字符串参数时，通常需要限制字符串长度。让我们看一下 Azure 资源命名示例。所有 Azure 资源类型的名称长度都有限制。为控制命名的参数指定最小和最大字符长度是一种很好的做法，以避免稍后在部署过程中出错。可以使用 @minLength 和 @maxLength 修饰器来指定你希望允许的参数的最小和最大字符长度。

以下示例声明名为 storageAccountName 的字符串参数，其长度只能在 5 到 24 个字符之间：

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

此参数包括两个修饰器。可以通过将每个修饰器放在它自己的行上，将多个修饰器应用于参数。

备注

还可以将 @minLength 和 @maxLength 修饰器应用于数组参数，以控制数组中允许的项数。

使用数值参数时，可能需要将值设置在特定范围内。例如，玩具公司可能会决定，每当有用户部署应用服务计划时，他们应始终部署至少一个实例，但部署计划实例不能超过 10 个。为了满足要求，可以使用 @minValue 和 @maxValue 修饰器来指定允许的最小值和最大值。以下示例声明整数参数 appServicePlanInstanceCount，其值只能在 1 和 10 之间（含）：

@minValue(1)
@maxValue(10)
param appServicePlanInstanceCount int

向参数添加说明

参数是使其他用户重复使用模板的一种很好的方法。当他们使用模板时，需要了解每个参数有什么用途，这样他们可以提供正确的值。 Bicep 提供 @description 修饰器，以便以可读方式记录参数的用途。

@description('The locations into which this Cosmos DB account should be configured. This parameter needs to be a list of objects, each of which has a locationName property.')
param cosmosDBAccountLocations array

为参数提供说明是一种很好的做法。尽量让这些说明有帮助，并提供有关模板所需参数值的重要信息。

备注

Bicep 模板有时可以在 Azure 门户供用户部署，就像使用模板规格一样。门户使用参数的说明和其他修饰器来帮助用户了解需要的参数值。