你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

了解 Bicep 文件的结构和语法

项目
11/03/2023

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

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

Bicep 格式

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

Bicep 文件具有以下元素。

metadata <metadata-name> = ANY

targetScope = '<scope>'

type <user-defined-data-type-name> = <type-expression>

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>

var <variable-name> = <variable-value>

resource <resource-symbolic-name> '<resource-type>@<api-version>' = {
  <resource-properties>
}

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

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@2022-09-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 文件其余部分的范围。有关详细信息，请参阅配置模块范围

类型

可以使用 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@2022-09-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

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

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

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

参数

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

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

param storageSKU string = 'Standard_LRS'

参数可用于 Bicep 文件。

sku: {
  name: storageSKU
}

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

参数修饰器

可以为每个参数添加一个或多个修饰器。这些修饰器描述参数并为传入的值定义约束。以下示例显示了一个修饰器，但还可使用许多其他修饰器。

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageSKU string = 'Standard_LRS'

有关详细信息，包括所有可用修饰器的说明，请参阅修饰器。

变量

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

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

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

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

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

资源

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

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

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

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

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

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

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

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

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

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

模块

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

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

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

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

资源和模块修饰器

可以向资源或模块定义中添加修饰器。支持的修饰器为 batchSize(int) 和 description。只能将该修饰器应用于使用 for 表达式的资源或模块定义。

默认情况下，将并行部署资源。添加 batchSize(int) 修饰器时，将串行部署实例。

@batchSize(3)
resource storageAccountResources 'Microsoft.Storage/storageAccounts@2019-06-01' = [for storageName in storageAccounts: {
  ...
}]

有关详细信息，请参阅批量部署。

输出

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

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@2018-05-01' = if (deployZone) {
  name: 'myZone'
  location: 'global'
}

有关详细信息，请参阅 Bicep 中的条件部署。

空格

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

Bicep 对换行敏感。例如：

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

不能写作：

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

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

注释

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

以下示例演示单行注释。

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