快速入門：針對 Bicep 檔案部署進行疑難排解

  • 發行項

此快速入門會說營如何針對 Bicep 檔案部署錯誤進行疑難排解。 您將會建立含有錯誤的檔案，並了解如何修正這些錯誤。

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

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

所有錯誤類型都會傳回錯誤碼，以供您針對部署進行疑難排解之用。 驗證與預檢錯誤會顯示在活動記錄中，但不會出現在部署歷程記錄中。 含有語法錯誤的 Bicep 檔案不會編譯成 JSON，也不會顯示在活動記錄中。

必要條件

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

建立含有錯誤的 Bicep 檔案

複製下列 Bicep 檔案，並將其儲存在本機。 您將使用此檔案，針對驗證錯誤、預檢錯誤與部署錯誤進行疑難排解。 此快速入門假設您將檔案命名為 troubleshoot.bicep，但您可為其指定任何名稱。

@description('SKU for the storage account')
@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
parameter storageAccountType string = 'Standard_LRS'

@description('Prefix for storage name.')
param prefixName string

var storageAccountName = '${prefixName}${uniqueString(resourceGroup().id)}'

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: storageAccountName
  location: resourceGroup().location
  sku: {
    name: storageAccountType
  }
  kind: 'StorageV2'
  properties: {}
}

resource existingVNet 'Microsoft.Network/virtualNetworks@2021-03-01' existing = {
  name: 'doesnotexist'
}

output storageAccountName string = storageAccountName
output vnetResult object = existingVNet

修正驗證錯誤

在 Visual Studio Code 中開啟檔案。 您會發現 Visual Studio Code 識別出語法錯誤。 第一個參數宣告以紅色波浪線標示，表示發生錯誤。

Screenshot of Visual Studio Code with red squiggles highlighting a syntax error in a Bicep file.

標示錯誤的程式碼行是：

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
parameter storageAccountType string = 'Standard_LRS'

當您將滑鼠停留在上方 parameter 時，您會看到錯誤訊息。

Screenshot of a detailed error message displayed in Visual Studio Code when hovering over a syntax error in a Bicep file.

訊息狀態：「無法辨識此宣告類型。請指定參數、變數、資源或輸出宣告。」若您嘗試部署此檔案，則會收到來自部署命令的相同錯誤訊息。

若您查看參數宣告的文件，則會看到關鍵字實際上是 param。 當變更該語法時，驗證錯誤就會消失。 @allowed 裝飾項目也會標記為錯誤，但也能藉由變更參數宣告來解決該錯誤。 裝飾項目標記為錯誤，因為裝飾項目之後需要參數宣告。 當宣告不正確時，此條件不成立。

修正過的程式碼行是：

param storageAccountType string = 'Standard_LRS'

修正預檢錯誤

現在您已修正驗證錯誤，是部署檔案的時候了。 不過，您會提供錯誤的參數值來查看預檢錯誤。

az group create --name troubleshootRG --location westus
az deployment group create \
  --resource-group troubleshootRG \
  --template-file troubleshoot.bicep \
  --parameters prefixName=longNamewith!!Charactersthatarenotallowed

Azure Resource Manager 會判斷儲存體帳戶的名稱是否包括不允許的字元。 Azure Resource Manager 不會嘗試部署。

您會看到錯誤訊息，指出預檢驗證失敗。 您也會看到另一則訊息，說明儲存體帳戶名稱長度必須介於 3 到 24 個字元，而且只能使用數字與小寫字母。 您提供的前置詞不符合該需求。 如需此錯誤碼的詳細資訊，請參閱解決儲存體帳戶名稱的錯誤。

因為此錯誤是在預檢中發現，所以歷程記錄中不會有任何部署。

Screenshot of Azure portal's deployment history section showing no deployments for a Bicep file.

但是，失敗的部署會存在於活動記錄中。

Screenshot of Azure portal's activity log displaying a preflight validation error for a Bicep file deployment.

您可以開啟記錄項目的詳細資料，以查看錯誤訊息。

修正部署錯誤

您將重新部署檔案，並為名稱前置詞參數提供允許的值。

az group create --name troubleshootRG --location westus
az deployment group create \
  --resource-group troubleshootRG \
  --template-file troubleshoot.bicep \
  --parameters prefixName=stg

該部署啟動後失敗，並顯示找不到虛擬網路的訊息。 一般來說，您可以藉由變更資源的參考來修正此錯誤。 在此快速入門中，您將會刪除參考。 如需此錯誤碼的詳細資訊，請參閱解決找不到資源的錯誤。

請注意，在入口網站中可以看到部署出現在歷程記錄中。

Screenshot of Azure portal's deployment history section showing a failed deployment for a Bicep file.

您可以開啟部署歷程記錄中的項目，以取得錯誤的詳細資料。 該錯誤也存在於活動記錄中。

Bicep 檔案嘗試參考不存在於資源群組中的虛擬網路。 刪除對現有虛擬網路的參考，以修正錯誤。

@description('SKU for the storage account')
@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

@description('Prefix for storage name.')
param prefixName string

var storageAccountName = '${prefixName}${uniqueString(resourceGroup().id)}'

resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: storageAccountName
  location: resourceGroup().location
  sku: {
    name: storageAccountType
  }
  kind: 'StorageV2'
  properties: {}
}

output storageAccountName string = storageAccountName

您可以部署該 Bicep 檔案，而不會發生任何錯誤。

清除資源

不再需要 Azure 資源時，請刪除資源群組。 您可以從 Cloud Shell 或入口網站刪除資源群組。

az group delete --name troubleshootRG

若要從入口網站刪除資源群組，請遵循下列步驟：

  1. 在 Azure 入口網站的搜尋方塊中，輸入 [資源群組]。
  2. 在 [依名稱篩選] 欄位中，輸入資源群組名稱。
  3. 選取資源群組名稱。
  4. 選取 [刪除資源群組]。
  5. 若要確認刪除，請輸入資源群組名稱，然後選取 [刪除]。

下一步

在此快速入門中，您會了解如何針對 Bicep 檔案部署錯誤進行疑難排解。

針對常見 Azure 部署錯誤進行疑難排解