快速入门：排查 ARM 模板 JSON 部署问题

项目
07/31/2023

本快速入门介绍如何排查 Azure 资源管理器模板（ARM 模板）JSON 部署错误。你将设置一个存在错误的模板，并了解如何修复错误。

资源管理器模板是定义项目基础结构和配置的 JavaScript 对象表示法 (JSON) 文件。模板使用声明性语法。在声明性语法中，你可以在不编写创建部署的编程命令序列的情况下，描述预期部署。

有三种类型的错误与部署相关：

验证错误发生在部署开始之前，由文件中的语法错误造成。像 Visual Studio Code 这样的代码编辑器可以识别这些错误。
当运行部署命令但未部署资源时，将发生预检验证错误。这些错误是部署未开始的情况下出现的。例如，如果某个参数值不正确，则会在预检验证中发现错误。
部署错误发生在部署过程中，只能通过评估 Azure 环境中的部署进度来发现。

所有类型的错误都会返回用于排查部署问题的错误代码。验证错误和预检错误会显示在活动日志中，但不会显示在部署历史记录中。

先决条件

若要完成本快速入门，需要准备好以下各项：

如果没有 Azure 订阅，请在开始前创建试用版订阅。
包含最新 Azure 资源管理器工具扩展的 Visual Studio Code。
安装最新版本的 Azure PowerShell 或 Azure CLI。

创建包含错误的模板

复制以下模板并将其保存在本地。你将使用此文件来排查验证错误、预检错误和部署错误。本快速入门假设你已将文件命名为 troubleshoot.json，但可以使用任意名称。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameterss": {
    "storageAccountType": {
      "type": "string",
      "defaultValue": "Standard_LRS",
      "allowedValues": [
        "Standard_LRS",
        "Standard_GRS",
        "Standard_ZRS",
        "Premium_LRS"
      ]
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "prefixName": {
      "type": "string"
    }
  },
  "variables": {
    "storageAccountName": "[concat(parameters('prefixName'), uniquestring(resourceGroup().id))]"
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2021-04-01",
      "name": "[variables('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "[parameters('storageAccountType')]"
      },
      "kind": "StorageV2",
      "properties": {}
    }
  ],
  "outputs": {
    "storageAccountName": {
      "type": "string",
      "value": "[variables('storageAccountName')]"
    },
    "vnetResult": {
      "type": "object",
      "value": "[reference(resourceId('Microsoft.Network/virtualNetworks', 'doesnotexist'), '2021-03-01', 'Full')]"
    }
  }
}

修复验证错误

在 Visual Studio Code 中打开该文件。 parameterss: 下的波浪线表示错误。将鼠标指针悬停在错误上可查看验证错误。

Visual Studio Code 的屏幕截图，突出显示了模板验证错误，并用红色波浪线标记了代码中拼写错误的“parameterss:”。

你会注意到，variables 和 resources 存在错误，原因是“未定义参数引用”。若要显示模板的验证错误，请选择“视图”>“问题” 。

Visual Studio Code 的屏幕截图，显示了“问题”选项卡，其中列出了“变量”和“资源”部分的未定义参数引用错误。

所有错误都由元素名称拼写不正确导致。

"parameterss": {

错误消息指出：“模板验证失败：在类型为“模板”的对象上找不到成员“parameterss”。路径为“parameterss”，第 4 行，第 16 位。”

参数的 ARM 模板语法显示 parameters 是正确的元素名称。

要修复验证错误和“未定义参数引用”错误，请更正拼写并保存文件。

"parameters": {

修复预检错误

要生成预检验证错误，需要对 prefixName 参数使用不正确的值。

本快速入门使用作为 troubleshootRG 资源组名称，但可以使用任意名称。

Azure CLI
PowerShell

az group create --name troubleshootRG --location chinanorth
az deployment group create \
  --resource-group troubleshootRG \
  --template-file troubleshoot.json \
  --parameters prefixName=long!!StoragePrefix

New-AzResourceGroup -Name troubleshootRG -Location chinanorth
New-AzResourceGroupDeployment `
  -ResourceGroupName troubleshootRG `
  -TemplateFile troubleshoot.json `
  -prefixName long!!StoragePrefix

模板未通过预检验证，部署不会运行。 prefixName 超过 11 个字符，并且包含特殊字符和大写字母。

存储名称的长度必须介于 3 到 24 个字符之间，并且只能使用小写字母和数字。前缀值创建了无效的存储名称。有关详细信息，请参阅解决存储帐户名称错误。要修复预检错误，请使用长度在 11 个字符以内且仅包含小写字母或数字的前缀。

由于部署未运行，因此没有部署历史记录。

Azure 资源组概述页面的屏幕截图，显示了由于预检错误而导致部署历史记录部分为空。

活动日志显示预检错误。选择日志可查看错误的详细信息。

Azure 资源组活动日志的屏幕截图，显示了带有红色感叹号图标的预检错误条目。

修复部署错误

使用有效的前缀值（例如 storage）运行部署。

Azure CLI
PowerShell

az group create --name troubleshootRG --location chinanorth
az deployment group create \
  --resource-group troubleshootRG \
  --template-file troubleshoot.json \
  --parameters prefixName=storage

New-AzResourceGroup -Name troubleshootRG -Location chinanorth
New-AzResourceGroupDeployment `
  -ResourceGroupName troubleshootRG `
  -TemplateFile troubleshoot.json `
  -prefixName storage

系统将开始部署，并在部署历史记录中显示部署详细信息。部署失败，因为 outputs 引用资源组中不存在的虚拟网络。但是，存储帐户没有错误，因此部署了资源。部署历史记录显示部署失败。

Azure 资源组概述页面的屏幕截图，显示了失败的部署，部署历史记录部分中带有红色感叹号图标。

若要修复部署错误，请更改引用函数以使用有效资源。有关详细信息，请参阅解决“找不到资源”错误。对于本快速入门，请删除 vnetResult 之前的逗号和所有 vnetResult。保存文件，并重新运行部署。

"vnetResult": {
  "type": "object",
  "value": "[reference(resourceId('Microsoft.Network/virtualNetworks', 'doesnotexist'), '2021-03-01', 'Full')]"
}

修复验证错误、预检错误和部署错误后，以下模板将部署存储帐户。部署历史记录和活动日志将显示部署成功。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageAccountType": {
      "type": "string",
      "defaultValue": "Standard_LRS",
      "allowedValues": [
        "Standard_LRS",
        "Standard_GRS",
        "Standard_ZRS",
        "Premium_LRS"
      ]
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "prefixName": {
      "type": "string"
    }
  },
  "variables": {
    "storageAccountName": "[concat(parameters('prefixName'), uniquestring(resourceGroup().id))]"
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2021-04-01",
      "name": "[variables('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "[parameters('storageAccountType')]"
      },
      "kind": "StorageV2",
      "properties": {}
    }
  ],
  "outputs": {
    "storageAccountName": {
      "type": "string",
      "value": "[variables('storageAccountName')]"
    }
  }
}

清理资源

不再需要 Azure 资源时，请删除资源组。

Azure CLI
PowerShell

az group delete --name troubleshootRG

Remove-AzResourceGroup -Name troubleshootRG

若要从门户中删除资源组，请执行以下步骤：

在 Azure 门户中的搜索框内输入“资源组”。
在“按名称筛选”字段中输入资源组名称。
选择资源组名称。
选择“删除资源组”。
若要确认删除，请输入资源组名称，然后选择“删除”。

后续步骤

在本快速入门中，你已了解如何排查 ARM 模板部署错误。

排查常见的 Azure 部署错误