通过

快速入门：排查 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 识别到了一个语法错误。 第一个参数声明标有红色波浪线，以指示错误。

Visual Studio Code 的屏幕截图，其中红色波浪线突出显示了 Bicep 文件中的语法错误。

标有错误的行是：

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

将鼠标悬停在 parameter 上时，会看到一条错误消息。

将鼠标悬停在 Bicep 文件中的语法错误上时，Visual Studio Code 中显示的详细错误消息的屏幕截图。

该消息指出：“无法识别此声明类型。请指定参数、变量、资源或输出声明。”如果你尝试部署此文件，部署命令将返回相同的错误消息。

如果查看参数声明的文档，你将看到关键字实际上是 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 个字符，并且只能使用数字和小写字母。 提供的前缀不符合该要求。 有关此错误代码的详细信息，请参阅解决存储帐户名称错误。

由于该错误是在预检中捕获的，因此历史记录中不会显示部署。

Azure 门户的部署历史记录部分的屏幕截图，它显示没有部署 Bicep 文件。

但是，活动日志中显示了失败的部署。

Azure 门户活动日志的屏幕截图，它显示了 Bicep 文件部署的预检验证错误。

可以打开日志条目的详细信息以查看错误消息。

修复部署错误

再次部署该文件，并为名称前缀参数提供允许的值。

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

部署将会开始，但会失败并显示一条消息，指出未找到虚拟网络。 通常，可以通过更改对资源的引用来修复此错误。 在本快速入门中，你将删除引用。 有关此错误代码的详细信息，请参阅解决找不到资源错误。

请注意门户中的历史记录中显示了部署。

Azure 门户的部署历史记录部分的屏幕截图，它显示 Bicep 文件部署失败。

可以打开部署历史记录中的条目以获取有关错误的详细信息。 活动日志中也包含了该错误。

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 文件部署错误。

排查常见的 Azure 部署错误