快速入门:排查 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'
  '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 chinanorth
az deployment group create \
  --resource-group troubleshootRG \
  --template-file troubleshoot.bicep \
  --parameters prefixName=longNamewith!!Charactersthatarenotallowed

Azure 资源管理器确定存储帐户的名称包含不允许的字符。 它不会尝试进行部署。

你将看到一条错误消息,指出预检验证失败。 你还会收到一条消息,指出存储帐户名称长度必须为 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 chinanorth
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 资源时,请删除资源组。 可以通过本地 Shell 或门户删除资源组。

az group delete --name troubleshootRG

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

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

后续步骤

在本快速入门中,你已了解如何排查 Bicep 文件部署错误。