教程:将参数添加到 ARM 模板Tutorial: Add parameters to your ARM template

前一篇教程中,你已了解如何将存储帐户添加到模板,然后部署该模板。In the previous tutorial, you learned how to add a storage account to the template and deploy it. 本教程介绍如何通过添加参数来改进 Azure 资源管理器 (ARM) 模板。In this tutorial, you learn how to improve the Azure Resource Manager (ARM) template by adding parameters. 完成本教程大约需要 14 分钟This tutorial takes about 14 minutes to complete.

先决条件Prerequisites

建议完成有关资源的教程,但这不是一项要求。We recommend that you complete the tutorial about resources, but it's not required.

必须已安装带有资源管理器工具扩展的 Visual Studio Code,以及 Azure PowerShell 或 Azure CLI。You must have Visual Studio Code with the Resource Manager Tools extension, and either Azure PowerShell or Azure CLI. 有关详细信息,请参阅模板工具For more information, see template tools.

审阅模板Review template

在上一篇教程的结束时,模板包含以下 JSON:At the end of the previous tutorial, your template had the following JSON:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2019-04-01",
      "name": "{provide-unique-name}",
      "location": "chinaeast",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "StorageV2",
      "properties": {
        "supportsHttpsTrafficOnly": true
      }
    }
  ]
}

可能已注意到此模板有一个问题。You may have noticed that there's a problem with this template. 存储帐户名称已经过硬编码。The storage account name is hard-coded. 每次只能使用此模板部署同一个存储帐户。You can only use this template to deploy the same storage account every time. 若要使用不同的名称部署存储帐户,必须创建新的模板,这显然不是实现自动化部署的实用方法。To deploy a storage account with a different name, you would have to create a new template, which obviously isn't a practical way to automate your deployments.

使模板可重复使用Make template reusable

为了使模板可重复使用,让我们添加一个可用于传入存储帐户名称的参数。To make your template reusable, let's add a parameter that you can use to pass in a storage account name. 以下示例中突出显示的 JSON 演示了模板中发生的更改。The highlighted JSON in the following example shows what changed in your template. storageName 参数已标识为字符串。The storageName parameter is identified as a string. 最大长度设置为 24 个字符,以防止名称过长。The max length is set to 24 characters to prevent any names that are too long.

复制整个文件,将模板替换为该文件的内容。Copy the whole file and replace your template with its contents.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageName": {
      "type": "string",
      "minLength": 3,
      "maxLength": 24
    }
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2019-04-01",
      "name": "[parameters('storageName')]",
      "location": "chinaeast",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "StorageV2",
      "properties": {
        "supportsHttpsTrafficOnly": true
      }
    }
  ]
}

部署模板Deploy template

让我们部署该模板。Let's deploy the template. 以下示例使用 Azure CLI 或 PowerShell 来部署模板。The following example deploys the template with Azure CLI or PowerShell. 请注意,需要为部署命令中的某个值提供存储帐户名称。Notice that you provide the storage account name as one of the values in the deployment command. 对于存储帐户名称,请提供前一篇教程中所用的相同名称。For the storage account name, provide the same name you used in the previous tutorial.

如果尚未创建资源组,请参阅创建资源组If you haven't created the resource group, see Create resource group. 此示例假设已根据第一篇教程中所述,将 templateFile 变量设置为模板文件的路径。The example assumes you've set the templateFile variable to the path to the template file, as shown in the first tutorial.

New-AzResourceGroupDeployment `
  -Name addnameparameter `
  -ResourceGroupName myResourceGroup `
  -TemplateFile $templateFile `
  -storageName "{your-unique-name}"

了解资源更新Understand resource updates

在上一部分,你已使用以前创建的同一名称部署了一个存储帐户。In the previous section, you deployed a storage account with the same name that you had created earlier. 你可能想要知道,重新部署会对该资源造成怎样的影响。You may be wondering how the resource is affected by the redeployment.

如果该资源已存在,并且在属性中未检测到任何更改,则表示未采取任何措施。If the resource already exists and no change is detected in the properties, no action is taken. 如果该资源已存在,并且某个属性已更改,则表示该资源已更新。If the resource already exists and a property has changed, the resource is updated. 如果该资源不存在,将会创建它。If the resource doesn't exist, it's created.

这种处理更新的方式意味着,模板可以包含 Azure 解决方案所需的所有资源。This way of handling updates means your template can include all of the resources you need for an Azure solution. 可以放心地重新部署该模板,并可以知道,只在必要时才会更改或创建资源。You can safely redeploy the template and know that resources are changed or created only when needed. 例如,如果已将文件添加到存储帐户,则可以重新部署存储帐户,而不会丢失这些文件。For example, if you have added files to your storage account, you can redeploy the storage account without losing those files.

按环境进行自定义Customize by environment

可以使用参数提供针对特定环境定制的值,以便自定义部署。Parameters enable you to customize the deployment by providing values that are tailored for a particular environment. 例如,可以根据是否要部署到开发、测试和生产环境,来传递不同的值。For example, you can pass different values based on whether you're deploying to an environment for development, test, and production.

前一个模板始终部署 Standard_LRS 存储帐户。The previous template always deployed a Standard_LRS storage account. 你可能希望能够根据环境灵活部署不同的 SKU。You might want the flexibility to deploy different SKUs depending on the environment. 以下示例演示了为 SKU 添加参数而需要做出的更改。The following example shows the changes to add a parameter for SKU. 复制整个文件并将其粘贴到模板中。Copy the whole file and paste over your template.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageName": {
      "type": "string",
      "minLength": 3,
      "maxLength": 24
    },
    "storageSKU": {
      "type": "string",
      "defaultValue": "Standard_LRS",
      "allowedValues": [
        "Standard_LRS",
        "Standard_GRS",
        "Standard_RAGRS",
        "Premium_LRS"
      ]
    }
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2019-04-01",
      "name": "[parameters('storageName')]",
      "location": "chinaeast",
      "sku": {
        "name": "[parameters('storageSKU')]"
      },
      "kind": "StorageV2",
      "properties": {
        "supportsHttpsTrafficOnly": true
      }
    }
  ]
}

storageSKU 参数有默认值。The storageSKU parameter has a default value. 如果在部署过程中未指定值,将使用此默认值。This value is used when a value isn't specified during the deployment. 它还有允许值列表。It also has a list of allowed values. 这些值与创建存储帐户所需的值相匹配。These values match the values that are needed to create a storage account. 你不希望模板用户传入没有作用的 SKU。You don't want users of your template to pass in SKUs that don't work.

重新部署模板Redeploy template

现在可以重新部署。You're ready to deploy again. 由于默认 SKU 设置为 Standard_LRS,因此不需要提供该参数的值。Because the default SKU is set to Standard_LRS, you don't need to provide a value for that parameter.

New-AzResourceGroupDeployment `
  -Name addskuparameter `
  -ResourceGroupName myResourceGroup `
  -TemplateFile $templateFile `
  -storageName "{your-unique-name}"

备注

如果部署失败,请使用“详细”开关获取有关正在创建的资源的信息。If the deployment failed, use the verbose switch to get information about the resources being created. 使用“调试”开关获取调试的详细信息。Use the debug switch to get more information for debugging.

若要查看模板的灵活性,请重新部署。To see the flexibility of your template, let's deploy again. 这一次,请将 SKU 参数设置为 Standard_GRSThis time set the SKU parameter to Standard_GRS. 可以传入新名称来创建不同的存储帐户,或者使用同一个名称来更新现有的存储帐户。You can either pass in a new name to create a different storage account, or use the same name to update your existing storage account. 这两个选项都是有效的。Both options work.

New-AzResourceGroupDeployment `
  -Name usenondefaultsku `
  -ResourceGroupName myResourceGroup `
  -TemplateFile $templateFile `
  -storageName "{your-unique-name}" `
  -storageSKU Standard_GRS

最后,让我们再次运行测试,以查看在传入一个未包含在允许值中的 SKU 时会发生什么情况。Finally, let's run one more test and see what happens when you pass in a SKU that isn't one of the allowed values. 在本例中,我们将测试模板用户认为 basic 是一个 SKU 时的情景。In this case, we test the scenario where a user of your template thinks basic is one of the SKUs.

New-AzResourceGroupDeployment `
  -Name testskuparameter `
  -ResourceGroupName myResourceGroup `
  -TemplateFile $templateFile `
  -storageName "{your-unique-name}" `
  -storageSKU basic

该命令立即失败并出现一条错误消息,指出哪些值是允许的。The command fails immediately with an error message that states which values are allowed. 在部署开始之前,资源管理器会识别到该错误。Resource Manager identifies the error before the deployment starts.

清理资源Clean up resources

若要继续学习下一篇教程,则不需删除该资源组。If you're moving on to the next tutorial, you don't need to delete the resource group.

如果你不打算继续学习,请删除该资源组以清理部署的资源。If you're stopping now, you might want to clean up the resources you deployed by deleting the resource group.

  1. 在 Azure 门户上的左侧菜单中选择“资源组” 。From the Azure portal, select Resource group from the left menu.
  2. 在“按名称筛选”字段中输入资源组名称。 Enter the resource group name in the Filter by name field.
  3. 选择资源组名称。Select the resource group name.
  4. 在顶部菜单中选择“删除资源组”。 Select Delete resource group from the top menu.

后续步骤Next steps

你已通过添加参数改进了第一篇教程中创建的模板。You improved the template created in the first tutorial by adding parameters. 下一篇教程将介绍模板函数。In the next tutorial, you'll learn about template functions.