分享方式:


快速入門:針對 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 檔案部署錯誤進行疑難排解。