改进参数和名称

8 分钟

参数是你的同事与模板交互的最常见方法。部署模板时，他们需要指定参数的值。创建资源后，资源名称将为查看 Azure 环境的所有人员提供与资源用途相关的重要信息。

本单元将介绍在规划 Bicep 文件的参数以及为资源提供的名称时需要注意的一些重要事项。

参数的易懂程度如何？

参数有助于让 Bicep 文件可以重复使用并变得灵活。为使用参数的人员清楚说明每个参数的用途非常重要。当同事使用模板时，他们将使用参数自定义其部署行为。

例如，假设你需要使用 Bicep 文件部署存储帐户。存储帐户的一个必需属性是库存单位 (SKU)，它用于定义数据冗余级别。 SKU 具有多个属性，最重要的当属 name。创建用于设置存储帐户 SKU 值的参数时，请使用明确定义的名称，如 storageAccountSkuName。使用此值而不是泛型名称（如 sku 或 skuName）有助于其他人理解参数的用途以及设置其值的影响。

默认值是让模板可供他人使用的重要方式。在合适的情况下使用默认值非常重要。它们对模板用户的帮助体现在以下两个方面：

默认值简化了模板的部署过程。如果参数具有合适的默认值，且适用于大多数模板用户，用户就可以在每次部署模板时忽略参数值，而不用指定它们。
对于你所期望的参数值内容，默认值提供了一个示例。如果模板用户需要选择其他值，默认值可以提供有用的提示来指导用户应选择什么样的值。

Bicep 还有助于验证用户通过参数修饰器提供的输入。这些修饰器可用于提供参数说明或声明允许哪些类型的值。 Bicep 提供了几种类型的参数修饰器：

说明提供了有关参数用途及设置其值的影响的可读信息。
值约束强制限制用户可输入哪些参数值。使用 @allowed() 修饰器可指定特定的允许值的列表。可以使用 @minValue() 和 @maxValue() 修饰器来强制实施数值参数的最小值和最大值，并且可以使用 @minLength() 和 @maxLength() 修饰器来强制实施字符串和数组参数的长度。

提示

使用 @allowed() 参数修饰器指定 SKU 时需谨慎。 Azure 服务经常添加新的 SKU，你不希望模板对其使用进行不必要的阻止。请考虑使用 Azure Policy 来强制使用特定的 SKU，并且仅当有功能原因导致模板用户不该选择特定的 SKU 时，才将 @allowed() 装饰器与 SKU 一起使用。例如，模板所需的功能可能在该 SKU 中不可用。使用 @description() 修饰器或注释进行说明，可以让后面的人员更加清楚相关原因。
虽然不常使用元数据，但可以应用元数据来提供有关参数的其他自定义元数据。

Bicep 文件的灵活性应当如何？

定义基础结构即代码的目标之一是使模板可以重复使用并变得灵活。你不想创建具有硬编码配置的单一用途模板。另一方面，将所有资源属性公开为参数并没有意义。创建适用于特定业务问题或解决方案的模板，而不是创建需要适合每种情况的通用模板。你也不想拥有太多参数，以免在部署模板前需要耗费很长时间来输入值。在配置资源的 SKU 和实例计数时，这一点尤其重要。

规划模板时，请考虑如何平衡灵活性和简便性。可使用两种常见方法在模板中提供参数：

提供自由格式的配置选项
使用预定义的配置集

我们考虑通过部署存储帐户的示例 Bicep 文件和一个 Azure 应用服务计划来使用这两种服务方法。

提供自由格式的配置选项

应用服务计划和存储帐户都需要你指定其 SKU。可考虑创建一组参数来控制资源的每个 SKU 和实例计数：

控制应用服务计划和存储帐户的参数示意图。

下面是 Bicep 中的显示效果：

param appServicePlanSkuName string
param appServicePlanSkuCapacity int
param storageAccountSkuName string

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

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  name: storageAccountSkuName
  location: location
  sku: {
    name: storageAccountSkuName
  }
}

这种格式提供了极大的灵活性，因为使用模板的任何人员都可以指定参数值的任意组合。但随着添加的资源越来越多，需要的参数也越多。因此，模板变得愈加复杂。此外，可能需要限制某些参数组合；或者确保在使用一个 SKU 部署特定资源时，使用另一个 SKU 部署另一项资源。如果提供太多单独的参数，则很难强制实施这些规则。

提示

考虑将要使用模板的人员。他们看到几十个参数可能会不知所措，因而放弃使用你的模板。

按参数对象的形式对相关参数进行分组，可以减少参数数量，如下所示：

param appServicePlanSku object = {
  name: 'S1'
  capacity: 2
}

但此方法会降低你验证参数值的能力，而且并不总是那么容易让模板用户理解如何定义对象。

使用预定义的配置集

或者，也可提供一个配置集：单个参数，其值为允许的值的受限列表，例如环境类型列表。用户部署模板时，只需为此参数选择一个值。当他们选择参数值时，该部署会自动继承一组配置：

控制应用服务计划和存储帐户的配置集示意图。

参数定义如下：

@allowed([
  'Production'
  'Test'
])
param environmentType string = 'Test'

配置组提供的灵活性较低，因为部署模板的人无法为单个资源指定大小，但你可以验证每组配置并确保它们符合你的要求。使用配置集可以减少模板用户了解对每项资源可用的所有不同选项的需求，并且更易于支持、测试和排查模板问题。

使用配置集时，请根据参数值创建映射变量，以定义要对各种资源设置的特定属性：

var environmentConfigurationMap = {
  Production: {
    appServicePlan: {
      sku: {
        name: 'P2V3'
        capacity: 3
      }
    }
    storageAccount: {
      sku: {
        name: 'ZRS'
      }
    }
  }
  Test: {
    appServicePlan: {
      sku: {
        name: 'S2'
        capacity: 1
      }
    }
    storageAccount: {
      sku: {
        name: 'LRS'
      }
    }
  }
}

然后，资源定义使用配置映射来定义资源属性：

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  sku: environmentConfigurationMap[environmentType].appServicePlan.sku
}

配置集可帮助你更轻松地访问复杂的模板。它们还有助于强制实施你自己的规则，并鼓励使用预先验证的配置值。

注意

此方法有时称为 T 恤尺寸法。购买 T 恤时，在长度、宽度、衣袖等方面没有太多选择。而是直接从小码、中码、大码中进行选择，T 恤设计师根据这些尺寸预先定义了相应的三围。

资源是如何命名的？

在 Bicep 中，必须为资源提供有意义的名称。 Bicep 中的资源有两个名称：

符号名称只能在 Bicep 文件中使用，并且不会显示在 Azure 资源中。符号名称可帮助读取或修改模板的用户了解参数、变量或资源定义的用途，并帮助用户就是否更改模板做出明智的决策。
资源名称是在 Azure 中创建的资源的名称。许多资源的名称都有约束，大多都要求使用唯一名称。

符号名称

思考要应用于资源的符号名称非常重要。假设你的同事需要修改模板。他们是否了解每项资源的用途？

例如，假设要定义一个存储帐户，该帐户将包含供用户从网站下载的产品手册。你可以为资源提供符号名称，例如 storageAccount；但如果它是在包含大量其他资源（甚至其他存储帐户）的 Bicep 文件中，则该名称描述得就不够详细。可以改为为其指定一个包含某些相关用途信息的符号名称，例如 productManualStorageAccount。

在 Bicep 中，通常对参数名称、变量名称和资源符号名称使用驼峰命名法大写样式。也就是说第一个单词的第一个字母小写，其他单词的第一个字母大写（如前面的示例中所示 productManualStorageAccount）。你无需使用驼峰命名法。如果选择使用不同的样式，则必须与团队达成统一的标准，然后使用一致的样式。

资源名称

每项 Azure 资源都有一个名称。名称是资源标识符的一部分。在许多情况下，它们还表示为用于访问资源的主机名。例如，创建名为 myapp 的应用服务应用时，用于访问应用的主机名将为 myapp.azurewebsites.net。部署资源后，无法重命名资源。

必须考虑如何命名 Azure 资源。许多组织都会定义其自己的资源命名约定。适用于 Azure 的云采用框架具有特定的指南，可帮助你定义自己的命名约定。资源命名约定的目的是帮助组织中的每个人了解每项资源的用途。

此外，每项 Azure 资源都有特定的命名规则和限制。例如，关于名称长度、可包含的字符以及名称是必须全局唯一还是仅在资源组中唯一，都存在相关限制。

遵循组织的所有命名约定以及 Azure 的命名要求可能非常复杂。编写良好的 Bicep 模板应向用户隐藏这种复杂性，并自动确定资源的名称。下面是要遵循的一种方法的示例：

添加用于创建唯一后缀的参数。这有助于确保资源具有唯一的名称。使用 uniqueString() 函数生成默认值是个好办法。如果部署模板的人员希望名称有意义，则可以使用特定值替代此模板。请务必使用 @maxLength() 修饰器来限制此后缀的长度，以免资源名称超过其最大长度。

提示

最好使用唯一后缀而不是前缀。利用此方法，可更轻松地对资源名称进行排序和快速扫描。此外，某些 Azure 资源对名称的第一个字符存在限制，随机生成的名称有时可能会违反这些限制。
使用变量动态构造资源名称。 Bicep 代码可确保它生成的名称遵循组织的命名约定和 Azure 要求。在资源名称中添加唯一后缀。

注意

并非每项资源都需要全局唯一名称。请考虑是在每项资源的名称中添加唯一后缀，还是仅在需要唯一后缀的资源名称中添加。