了解 Bicep 文件的结构和语法

项目
09/30/2024

本文介绍 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@2023-04-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

修饰器包括：

修饰器	应用于元素	应用于数据类型	Argument	说明
允许	param	全部	array	使用此修饰器以确保用户提供正确的值。此修饰器仅在 `param` 语句上受允许。要声明某个属性必须是 `type` 或 `output` 语句中一组预定义值之一，请使用联合类型语法。联合类型语法也可以在 `param` 语句中使用。
batchSize	module, resource	空值	integer	设置实例以按顺序部署。
description	func, param, module, output, resource, type, var	全部	string	提供元素的说明。可将 Markdown 格式的文本用于说明文本。
鉴别器	param, type, output	object	string	使用此修饰器来确保标识和管理正确的子类。有关详细信息，请参阅自定义标记的联合数据类型。
导出	func, type, var	全部	无	指示该元素可由另一个 Bicep 文件导入。
maxLength	param, output, type	数组、字符串	int	字符串和数组元素的最大长度。最大值包含在内。
maxValue	param, output, type	int	int	整数元素的最大值。最大值包含在内。
metadata	func, output, param, type	全部	object	应用于元素的自定义属性。可以包含与说明修饰器等效的说明属性。
minLength	param, output, type	数组、字符串	int	字符串和数组元素的最小长度。最小值包含在内。
minValue	param, output, type	int	int	整数元素的最小值。最小值包含在内。
sealed	param, type, output	object	无	如果 use-define 数据类型的属性名称可能存在拼写错误，则将 BCP089 从警告提升为错误。有关详细信息，请参阅提升错误级别。
secure	param, type	字符串、对象	无	将参数标记为安全。安全参数的值不会保存到部署历史记录中，也不会被记录下来。有关详细信息，请参阅保护字符串和对象。

参数

将参数用于需要随不同部署而变化的值。如果在部署过程中未提供任何值，则可以为所使用的参数定义默认值。

例如，可以添加 SKU 参数以指定资源的不同大小。根据要部署到测试还是生产，可以传递不同的值。

param storageSKU string = 'Standard_LRS'

参数可用于 Bicep 文件。

sku: {
  name: storageSKU
}

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

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

变量

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

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

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

resource stg 'Microsoft.Storage/storageAccounts@2023-04-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@2023-04-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

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

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

函数

在 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')

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

资源

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

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

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

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

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

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

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

resource storage 'Microsoft.Storage/storageAccounts@2023-04-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@2023-04-01' = {
  name: 'examplestorage'
  location: resourceGroup().location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

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

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

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

模块

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

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

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

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

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

Outputs

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

output storageEndpoint object = stg.properties.primaryEndpoints

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

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

循环

可以将迭代循环添加到 Bicep 文件以定义以下内容的多个副本：

resource
name
可变
property
output

使用 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 中的条件部署。

空格

创作 Bicep 文件时将忽略空格和制表符。

Bicep 对换行敏感。例如：

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

不能写作：

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

在多行中定义对象和数组。

注释

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

以下示例演示单行注释。

// This is your primary NIC.
resource nic1 'Microsoft.Network/networkInterfaces@2023-11-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 数据类型，请参阅数据类型。

通过