Bicep 文件结构和语法

本文介绍 Bicep 文件的结构和语法。 本文演示了文件的不同部分，以及可在相应部分使用的属性。

有关指导你完成 Bicep 文件创建过程的分步教程，请参阅快速入门：使用 Visual Studio Code 创建 Bicep 文件。

已知限制

• Bicep 语言不支持 apiProfile 这一概念。 此概念将单个 apiProfile 映射到每个资源类型的集 apiVersion 。
• 目前不支持用户定义的函数。 目前可访问试验性功能。 有关详细信息，请参阅 Bicep 中的用户定义函数。
• 有些 Bicep 功能需要对中间语言（Azure 资源管理器 JSON 模板）进行相应更改。 产品团队在将所有必需的更新部署到全球 Azure 后，将宣布这些功能可用。 如果使用其他环境（如 Azure Stack），则该功能的可用性可能会延迟。 只有在中间语言也更新后，Bicep 功能才可在该环境中使用。

Bicep 格式

Bicep 是一种声明性语言，这意味着元素可以按任何顺序显示。 元素的顺序不会影响处理部署的方式，这与命令性语言不同。

Bicep 文件具有以下元素：

#<directive-name> <argument> [<argument> ...]

@<decorator>(<argument>)
metadata <metadata-name> = ANY

targetScope = '<scope>'

@<decorator>(<argument>)
type <user-defined-data-type-name> = <type-expression>

@<decorator>(<argument>)
func <user-defined-function-name> (<argument-name> <data-type>, <argument-name> <data-type>, ...) <function-data-type> => <expression>

@<decorator>(<argument>)
param <parameter-name> <parameter-data-type> = <default-value>

@<decorator>(<argument>)
var <variable-name> = <variable-value>

@<decorator>(<argument>)
resource <resource-symbolic-name> '<resource-type>@<api-version>' = {
  <resource-properties>
}

@<decorator>(<argument>)
module <module-symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

@<decorator>(<argument>)
output <output-name> <output-data-type> = <output-value>

以下示例演示了这些元素的实现：

metadata description = 'Creates a storage account and a web app'

@description('The prefix to use for the storage account name.')
@minLength(3)
@maxLength(11)
param storagePrefix string

param storageSKU string = 'Standard_LRS'
param location string = resourceGroup().location

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

module webModule './webApp.bicep' = {
  name: 'webDeploy'
  params: {
    skuName: 'S1'
    location: location
  }
}

元数据

Bicep 中的元数据是一种非类型化值，可以将其包含在 Bicep 文件中。 元数据提供有关 Bicep 文件的补充信息，例如名称、说明、作者和创建日期。

目标范围

默认目标范围为 resourceGroup. 如果在资源组级别部署，则无需在 Bicep 文件中设置目标范围。

允许的值为：

• resourceGroup：用于 资源组部署的默认值。
• subscription：用于订阅部署。
• managementGroup：用于管理组部署。
• tenant：用于租户部署。

在模块中，您可以指定与 Bicep 文件其他部分不同的范围。 有关详细信息，请参阅配置模块范围。

参数

将参数用于需要随不同部署而变化的值。 可以为部署期间未提供值时使用的参数定义默认值。

例如，可以添加 SKU 参数以指定资源的不同大小。 你可以根据部署环境的不同（测试或生产）传递不同的值。

param storageSKU string = 'Standard_LRS'

可在 Bicep 文件中使用该参数。

sku: {
  name: storageSKU
}

可以为每个参数添加一个或多个修饰器。 有关详细信息，请参阅使用修饰器。

有关详细信息，请参阅 Bicep 中的参数。

变量

要使 Bicep 文件更具可读性，可以通过将复杂的表达式封装在一个变量中。 例如，可以通过将多个值连接在一起来创建的资源名称添加变量。

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

在需要复杂表达式的任何位置使用此变量。

resource stg 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: uniqueStorageName

可以为每个变量添加一个或多个修饰器。 有关详细信息，请参阅使用修饰器。

有关详细信息，请参阅 Bicep 中的变量。

资源

使用关键字 resource 定义要部署的资源。 资源声明中包含资源的符号名称。 在 Bicep 文件的其他部分中使用此符号名称从资源获取值。

资源声明中包含资源类型和 API 版本。 在资源声明的正文中，包括特定于资源类型的属性。

resource stg 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

可以为每个资源添加一个或多个修饰器。 有关详细信息，请参阅使用修饰器。

有关详细信息，请参阅 Bicep 中的资源声明。

某些资源存在父/子关系。 可以在父资源内部或外部定义子资源。

以下示例演示如何在父资源内部定义子资源。 其中包含一个存储帐户，该存储帐户中定义了一个子资源（文件服务）。 该文件服务中也定义了一个子资源（共享）。

resource storage 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: 'examplestorage'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }

  resource service 'fileServices' = {
    name: 'default'

    resource share 'shares' = {
      name: 'exampleshare'
    }
  }
}

以下示例演示如何在父资源外部定义子资源。 使用 parent 属性来标识父/子关系。 定义了相同的三个资源。

resource storage 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: 'examplestorage'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

resource service 'Microsoft.Storage/storageAccounts/fileServices@2025-06-01' = {
  name: 'default'
  parent: storage
}

resource share 'Microsoft.Storage/storageAccounts/fileServices/shares@2025-06-01' = {
  name: 'exampleshare'
  parent: service
}

有关详细信息，请参阅在 Bicep 中设置子资源的名称和类型。

模块

借助模块，你可以在其他 Bicep 文件中重用来自 Bicep 文件的代码。 在模块声明中，链接到要重用的文件。 部署 Bicep 文件时，还会在模块中部署资源。

module webModule './webApp.bicep' = {
  name: 'webDeploy'
  params: {
    skuName: 'S1'
    location: location
  }
}

借助符号名称，你可以从文件中的其他位置引用模块。 例如，可以通过使用符号名称和输出值的名称来获取模块的输出值。

可以为每个模块添加一个或多个修饰器。 有关详细信息，请参阅使用修饰器。

有关详细信息，请参阅使用 Bicep 模块。

输出

使用输出，以从部署中返回值。 通常，当需要将某值重新用于其他操作时，可以从已部署的资源中返回该值。

output storageEndpoint object = stg.properties.primaryEndpoints

可以为每个输出添加一个或多个修饰器。 有关详细信息，请参阅使用修饰器。

有关详细信息，请参阅 Bicep 中的输出。

类型

使用 type 语句定义用户定义的数据类型。

param location string = resourceGroup().location

type storageAccountSkuType = 'Standard_LRS' | 'Standard_GRS'

type storageAccountConfigType = {
  name: string
  sku: storageAccountSkuType
}

param storageAccountConfig storageAccountConfigType = {
  name: 'storage${uniqueString(resourceGroup().id)}'
  sku: 'Standard_LRS'
}

resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

可以为每个用户定义数据类型添加一个或多个修饰器。 有关详细信息，请参阅使用修饰器。

有关详细信息，请参阅 Bicep 中的用户定义的数据类型。

Functions

在 Bicep 文件中，除了使用 Bicep 文件中自动提供的标准 Bicep 函数之外，也可以创建自己的函数。 如果具有在 Bicep 文件中重复使用的复杂表达式，请创建自己的函数。

func buildUrl(https bool, hostname string, path string) string => '${https ? 'https' : 'http'}://${hostname}${empty(path) ? '' : '/${path}'}'

output azureUrl string = buildUrl(true, 'microsoft.com', 'azure')

有关详细信息，请参阅 Bicep 中的用户定义函数。

装饰器

将一个或多个修饰器添加到以下每个元素：

• param
• var
• 资源
• module
• 输出
• func
• 类型

下表列出了装饰器：

指令

Bicep 支持使用指令（编译指令）来控制文件中的某些行为，例如抑制代码检查工具的警告或其他诊断警告信息。 指令以 # 字符为前缀。

#<directive-name> <argument1> [<argument2> ... ]

必须在指令之后指定至少一个标识符。 如果未提供任何标识符，编译器将报告错误。 你在指令后指定的标识符可以引用：

• Bicep 编译器诊断，例如 BCP138
• Bicep linter 规则，例如 no-unused-params

使用空格分隔参数。 linter 规则和诊断代码区分大小写。

Bicep 目前支持三种指令类型：

• #disable-next-line — 仅禁用下一行的一项或多项诊断功能
• #disable-diagnostics — 对整个文件禁用一个或多个诊断，直到重新启用为止
• #restore-diagnostics — 重新启用以前禁用的诊断

以下示例取消多个诊断和规则：

#disable-diagnostics no-unused-vars BCP335 

var location = 'eastus'

param storageCount int

resource accounts 'Microsoft.Storage/storageAccounts@2025-06-01' = [for i in range(0, storageCount): if (i % 2 == 0) {
  name: 'sa0820${i}'
  location: resourceGroup().location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
}]

请谨慎使用指令，仅在你审核并有意抑制诊断或 linter 规则时使用。 过度使用可以减少模板可读性和可维护性。 添加注释，说明规则或诊断代码为何不适用于此行。

循环

将迭代循环添加到 Bicep 文件中，以定义多个副本：

• 资源
• 模块
• 变量
• 属性
• 输出

使用 for 表达式定义循环。

param moduleCount int = 2

module stgModule './example.bicep' = [for i in range(0, moduleCount): {
  name: '${i}deployModule'
  params: {
  }
}]

可以循环访问数组、对象或整数索引。

有关详细信息，请参阅 Bicep 中的迭代循环。

条件部署

可以将资源或模块添加到 Bicep 文件中，以便进行条件部署。 在部署期间，将评估条件，并根据结果确定是部署了资源还是模块。 使用 if 表达式定义条件部署。

param deployZone bool

resource dnsZone 'Microsoft.Network/dnsZones@2023-07-01-preview' = if (deployZone) {
  name: 'myZone'
  location: 'global'
}

有关详细信息，请参阅 Bicep 中的条件部署以及 if 表达式。

空格

Bicep 文件忽略空格和选项卡。

Bicep 对换行符很敏感。 例如：

resource sa 'Microsoft.Storage/storageAccounts@2025-06-01' = if (newOrExisting == 'new') {
  ...
}

无法将其写成：

resource sa 'Microsoft.Storage/storageAccounts@2025-06-01' =
    if (newOrExisting == 'new') {
      ...
    }

可以跨多行定义 对象 和 数组 。

注释

将 // 用于单行注释或将 /* ... */ 用于多行注释。

以下例子演示单行注释。

// This is your primary NIC.
resource nic1 'Microsoft.Network/networkInterfaces@2025-01-01' = {
  ...
}

以下示例演示了多行注释。

/*
  This Bicep file assumes the key vault already exists and
  is in same subscription and resource group as the deployment.
*/
param existingKeyVaultName string

多行声明

现在可以在函数、数组和对象声明中使用多行。 此功能需要 Bicep CLI 0.7.X 或更高版本。

在以下示例中，resourceGroup() 定义分为多行。

var foo = resourceGroup(
  mySubscription,
  myRgName)

有关多行声明示例，请参阅数组和对象。

相关内容

• 有关 Bicep 简介，请参阅 什么是 Bicep？
• 有关 Bicep 数据类型，请参阅数据类型。