了解 Bicep 文件的结构和语法Understand the structure and syntax of Bicep files

本文介绍 Bicep 文件的结构。This article describes the structure of a Bicep file. 本文演示了文件的不同部分,以及可在相应部分使用的属性。It presents the different sections of the file and the properties that are available in those sections.

本文适用对象为对 Bicep 文件有一定了解的用户。This article is intended for users who have some familiarity with Bicep files. 其中提供了有关模板结构的详细信息。It provides detailed information about the structure of the template. 若要通过分步教程来了解创建 Bicep 文件的过程,请参阅《教程:创建和部署第一个 Azure 资源管理器 Bicep 文件》。For a step-by-step tutorial that guides you through the process of creating a Bicep file, see Tutorial: Create and deploy first Azure Resource Manager Bicep file.

模板格式Template format

Bicep 文件具有以下元素。A Bicep file has the following elements. 这些元素可按任意顺序显示。The elements can appear in any order.

targetScope = '<scope>'

@<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>
}

// conditional deployment
resource <resource-symbolic-name> '<resource-type>@<api-version>' = if (<condition-to-deploy>) {
  <resource-properties>
}

// iterative deployment
@<decorator>(<argument>)
resource <resource-symbolic-name> '<resource-type>@<api-version>' = [for <item> in <collection>: {
  <resource-properties>
}]

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

// conditional deployment
module <module-symbolic-name> '<path-to-file>' = if (<condition-to-deploy>) {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

// iterative deployment
module <module-symbolic-name> '<path-to-file>' = [for <item> in <collection>: {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}]

output <output-name> <output-data-type> = <output-value>

以下示例演示了这些元素的实现。The following example shows an implementation of these elements.

@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@2019-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
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

目标作用域Target scope

默认情况下,目标作用域设置为 resourceGroupBy default, the target scope is set to resourceGroup. 如果要在资源组级别进行部署,则无需在 Bicep 文件中设置目标作用域。If you're deploying at the resource group level, you don't need to set the target scope in your Bicep file.

允许的值为:The allowed values are:

参数Parameters

将参数用于需要随不同部署而变化的值。Use parameters for values that need to vary for different deployments. 如果在部署过程中未提供任何值,则可以为所使用的参数定义默认值。You can define a default value for the parameter that is used if no value is provided during deployment.

例如,可以添加 SKU 参数以指定资源的不同大小。For example, you might add a SKU parameter to specify different sizes for a resource. 可以使用模板函数来创建默认值,例如获取资源组位置。You can use template functions for creating the default value, such as getting the resource group location.

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

有关可用的数据类型,请参阅模板中的数据类型For the available data types, see Data types in templates.

有关详细信息,请参阅模板中的参数For more information, see Parameters in templates.

参数修饰器Parameter decorators

可以为每个参数添加一个或多个修饰器。You can add one or more decorators for each parameter. 这些修饰器定义参数所允许的值。These decorators define the values that are allowed for the parameter. 以下示例指定可以通过 Bicep 文件部署的 SKU。The following example specifies the SKUs that can be deployed through the Bicep file.

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

下表介绍了可用的修饰器及其使用方式。The following table describes the available decorators and how to use them.

修饰器Decorator 应用于Apply to 参数Argument 说明Description
允许allowed allall arrayarray 参数允许的值。Allowed values for the parameter. 使用此修饰器以确保用户提供正确的值。Use this decorator to make sure the user provides correct values.
descriptiondescription allall stringstring 解释如何使用参数的文本。Text that explains how to use the parameter. 通过门户向用户显示该说明。The description is displayed to users through the portal.
maxLengthmaxLength 数组、字符串array, string intint 字符串和数组参数的最大长度。The maximum length for string and array parameters. 最大值包含在内。The value is inclusive.
maxValuemaxValue intint intint 整数参数的最大值。The maximum value for the integer parameter. 最大值包含在内。This value is inclusive.
metadatametadata allall objectobject 应用于参数的自定义属性。Custom properties to apply to the parameter. 可以包含与说明修饰器等效的说明属性。Can include a description property that is equivalent to the description decorator.
minLengthminLength 数组、字符串array, string intint 字符串和数组参数的最小长度。The minimum length for string and array parameters. 最小值包含在内。The value is inclusive.
minValueminValue intint intint 整数参数的最小值。The minimum value for the integer parameter. 最小值包含在内。This value is inclusive.
securesecure 字符串、对象string, object none 将参数标记为安全。Marks the parameter as secure. 安全参数的值不会保存到部署历史记录中,也不会被记录下来。The value for a secure parameter isn't saved to the deployment history and isn't logged. 有关详细信息,请参阅保护字符串和对象For more information, see Secure strings and objects.

变量Variables

将变量用于在 Bicep 文件中重复的复杂表达式。Use variables for complex expressions that are repeated in a Bicep file. 例如,可以为资源名称添加一个变量,该名称通过将多个值连接在一起构造而成。For example, you might add a variable for a resource name that is constructed by concatenating several values together.

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

不能为变量指定数据类型You don't specify a data type for a variable. 而是从值中推断数据类型。Instead, the data type is inferred from the value.

有关详细信息,请参阅模板中的变量For more information, see Variables in templates.

资源Resource

使用关键字 resource 定义要部署的资源。Use the resource keyword to define a resource to deploy. 资源声明中包含资源的符号名称。Your resource declaration includes a symbolic name for the resource. 如果需要从资源中获取值,请在 Bicep 文件的其他部分中使用此符号名称。You'll use this symbolic name in other parts of the Bicep file if you need to get a value from the resource.

资源声明中还包含资源类型和 API 版本。The resource declaration also includes the resource type and API version.

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

在资源声明中,需加入资源类型的属性。In your resource declaration, you include properties for the resource type. 这些属性对于每个资源类型而言皆具有唯一性。These properties are unique to each resource type.

有关详细信息,请参阅模板中的资源声明For more information, see Resource declaration in templates.

若要有条件地部署资源,请添加 if 表达式。To conditionally deploy a resource, add an if expression.

resource sa 'Microsoft.Storage/storageAccounts@2019-06-01' = if (newOrExisting == 'new') {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

若要部署一个资源类型的多个实例,请添加 for 表达式。To deploy more than one instance of a resource type, add a for expression. 此表达式可以循环访问数组的成员。The expression can iterate over members of an array.

resource sa 'Microsoft.Storage/storageAccounts@2019-06-01' = [for storageName in storageAccounts: {
  name: storageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}]

模块Modules

如果你想要重用某些代码,请使用模块链接到包含这些代码的其他 Bicep 文件。Use modules to link to other Bicep files that contain code you want to reuse. 该模块包含一个或多个要部署的资源。The module contains one or more resources to deploy. 这些资源与 Bicep 文件中的所有其他资源一起部署。Those resources are deployed along with any other resources in your Bicep file.

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

借助符号名称,你可以从文件中的其他位置引用模块。The symbolic name enables you to reference the module from somewhere else in the file. 例如,可以通过使用符号名称和输出值的名称来获取模块的输出值。For example, you can get an output value from a module by using the symbolic name and the name of the output value.

与资源类似,可以有条件地或以迭代方式部署模块。Like resources, you can conditionally or iteratively deploy a module. 模块与资源拥有相同的语法。The syntax is the same for modules as resources.

有关详细信息,请参阅使用 Bicep 模块For more information, see Use Bicep modules.

资源和模块修饰器Resource and module decorators

可以向资源或模块定义中添加修饰器。You can add a decorator to a resource or module definition. 唯一受支持的修饰器是 batchSize(int)The only supported decorator is batchSize(int). 只能将该修饰器应用于使用 for 表达式的资源或模块定义。You can only apply it to a resource or module definition that uses a for expression.

默认情况下,将并行部署资源。By default, resources are deployed in parallel. 你并不知道它们的完成顺序。You don't know the order in which they finish. 添加 batchSize 修饰器时,将串行部署实例。When you add the batchSize decorator, you deploy instances serially. 使用整数参数指定要并行部署的实例数。Use the integer argument to specify the number of instances to deploy in parallel.

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

有关详细信息,请参阅串行或并行For more information, see Serial or Parallel.

输出Outputs

使用输出,以从部署中返回值。Use outputs to return value from the deployment. 通常,当需要将某值重新用于其他操作时,可以从已部署的资源中返回该值。Typically, you return a value from a deployed resource when you need to reuse that value for another operation.

output storageEndpoint object = stg.properties.primaryEndpoints

指定输出值的数据类型Specify a data type for the output value.

有关详细信息,请参阅模板中的输出For more information, see Outputs in templates.

注释Comments

// 用于单行注释或将 /* ... */ 用于多行注释Use // for single-line comments or /* ... */ for multi-line comments

以下示例演示单行注释。The following example shows a single-line comment.

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

以下示例演示多行注释。The following example shows a multi-line comment.

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

多行字符串Multi-line strings

可将一个字符串分成多个行。You can break a string into multiple lines. 使用三个单引号字符 ''' 来开始和结束多行字符串。Use three single quote characters ''' to start and end the multi-line string.

多行字符串中的字符按原样处理。Characters within the multi-line string are handled as-is. 不需要转义字符。Escape characters are unnecessary. 多行字符串中不能包含 '''You can't include ''' in the multi-line string. 当前不支持字符串内插。String interpolation isn't currently supported.

可以在开头的 ''' 之后立即开始字符串,也可以加入新行。You can either start your string right after the opening ''' or include a new line. 无论哪种情况,生成的字符串都不包含新行。In either case, the resulting string doesn't include a new line. 根据 Bicep 文件中的行尾,会将新行解释为 \r\n\nDepending on the line endings in your Bicep file, new lines are interpreted as \r\n or \n.

以下示例演示多行字符串。The following example shows a multi-line string.

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

前面的示例与以下 JSON 等效。The preceding example is equivalent to the following JSON.

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

后续步骤Next steps

有关 Bicep 的简介,请参阅 Bicep 是什么?For an introduction to Bicep, see What is Bicep?.