快速入門：針對 ARM 範本 JSON 部署進行疑難排解

發行項
06/20/2024

本快速入門說明如何針對 Azure Resource Manager 範本 (ARM 範本) JSON 部署錯誤進行疑難排解。您將會設定有錯誤的範本，並了解如何修正這些錯誤。

Azure Resource Manager 範本是一個 JavaScript 物件標記法 (JSON) 檔案，會定義專案的基礎結構和設定。範本使用宣告式語法。您可以描述預期的部署，而不需要撰寫程式設計命令順序來建立部署。

有三種與部署相關的錯誤類型：

驗證錯誤發生於部署開始之前，並且為檔案中的語法錯誤所造成。 Visual Studio Code 之類的程式碼編輯器可識別這些錯誤。
預檢驗證錯誤發生於執行部署命令但未部署資源時。在不啟動部署的情況下找到這些錯誤。例如，若參數值不正確，則會在預檢驗證中找到錯誤。
部署錯誤發生在部署過程中，且只能藉由評估 Azure 環境中的部署進度將其找出。

所有錯誤類型都會傳回錯誤碼，以供您針對部署進行疑難排解之用。驗證與預檢錯誤會顯示在活動記錄中，但不會出現在部署歷程記錄中。

必要條件

若要完成此快速入門，您需要下列項目：

如尚未擁有 Azure 訂用帳戶，請在開始之前先建立免費帳戶。
Visual Studio Code 搭配最新的 Azure Resource Manager 工具延伸模組。
安裝最新版的 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 的螢幕快照，其中顯示 [問題] 索引卷標，其中列出 'variables' 和 'resources' 區段未定義的參數參考錯誤。

所有錯誤都是因為元素名稱的拼寫不正確所造成。

"parameterss": {

錯誤訊息指出「範本驗證錯誤：'Template' 類型的物件上找不到成員 'parameterss'。路徑 'parameterss'，第 4 行，位置 16」。

參數的 ARM 範本語法會顯示 parameters 是正確的元素名稱。

若要修正驗證錯誤和「未定義參數參考」錯誤，請更正拼寫並儲存檔案。

"parameters": {

修正預檢錯誤

若要建立預檢驗證錯誤，您將針對 prefixName 參數使用不正確的值。

本快速入門會使用 troubleshootRG 做為資源群組名稱，但您可以使用任何名稱。

Azure CLI
PowerShell

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

New-AzResourceGroup -Name troubleshootRG -Location westus
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 westus
az deployment group create \
  --resource-group troubleshootRG \
  --template-file troubleshoot.json \
  --parameters prefixName=storage

New-AzResourceGroup -Name troubleshootRG -Location westus
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 部署錯誤進行疑難排解

共用方式為