Bicep 文件结构和语法

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

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

Bicep 格式

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

Bicep 文件具有以下元素：

@<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 文件其他部分不同的作用域。 有关详细信息，请参阅 “配置模块范围”。

修饰器

可以为以下每个元素添加一个或多个修饰器：

• param
• var
• 资源
• module
• output
• func
• type

下表列出了修饰器：

参数

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

例如，可以添加参数 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 中的变量。

类型

可以使用 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 中的用户定义函数。

资源

使用关键字 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 中的输出。

循环

将迭代循环添加到 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 文件中的行尾，会将新行解释为 \r\n 或 \n。

以下示例演示多行字符串。

var stringVar = '''
this is multi-line
  string with formatting
  preserved.
'''

前面的示例等效于以下 JSON：

"variables": {
  "stringVar": "this is multi-line\r\n  string with formatting\r\n  preserved.\r\n"
}

多行声明

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

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

var foo = resourceGroup(
  mySubscription,
  myRgName)

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

已知的限制

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

相关内容

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