Описание структуры и синтаксиса файлов Bicep
В этой статье описываются структура и синтаксис файла Bicep. Статья содержит информацию о разных разделах файла и свойствах, которые доступны в этих разделах.
Пошаговые инструкции по созданию файла Bicep см. в разделе Краткое руководство. Создание файлов Bicep с помощью Visual Studio Code.
Формат Bicep
Bicep — это декларативный язык, что означает, что элементы могут располагаться в произвольном порядке. В отличие от императивных языков порядок элементов не влияет на способ обработки развертывания.
Эта Bicep содержит следующие элементы.
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>
}
module <module-symbolic-name> '<path-to-file>' = {
name: '<linked-deployment-name>'
params: {
<parameter-names-and-values>
}
}
output <output-name> <output-data-type> = <output-value>
В следующем примере показана реализация этих элементов.
@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
Целевая область
По умолчанию для целевой области задано значение resourceGroup. При развертывании на уровне группы ресурсов в файле Bicep не нужно задавать целевую область.
Допустимые значения:
- resourceGroup — значение по умолчанию, используемое для развертываний группы ресурсов.
- subscription — используется для развертываний подписок.
- managementGroup — используется для развертываний группы управления.
- tenant — используется для развертываний клиентов.
В модуле можно указать область, которая будет отличаться от области остальной части файла Bicep. Дополнительные сведения см. в разделе Настройка области модуля.
Параметры
Используйте параметры для значений, которые должны отличаться для разных развертываний. Можно определить значение по умолчанию для используемого параметра, если значение не указано во время развертывания.
Например, можно добавить параметр 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@2021-02-01' = {
name: 'examplestorage'
location: resourceGroup().location
kind: 'StorageV2'
sku: {
name: 'Standard_LRS'
}
resource service 'fileServices' = {
name: 'default'
resource share 'shares' = {
name: 'exampleshare'
}
}
}
В следующем примере показано, как определить дочерний ресурс за пределами родительского ресурса. Свойство родительского ресурса используется для определения связи "родители-потомки". Определены те же три ресурса.
resource storage 'Microsoft.Storage/storageAccounts@2021-02-01' = {
name: 'examplestorage'
location: resourceGroup().location
kind: 'StorageV2'
sku: {
name: 'Standard_LRS'
}
}
resource service 'Microsoft.Storage/storageAccounts/fileServices@2021-02-01' = {
name: 'default'
parent: storage
}
resource share 'Microsoft.Storage/storageAccounts/fileServices/shares@2021-02-01' = {
name: 'exampleshare'
parent: service
}
Дополнительные сведения см. в разделе Настройка имени и типа для дочерних ресурсов в Bicep.
Модули
Модули позволяют повторно использовать код из файла Bicep в других файлах Bicep. В объявлении модуля вы ссылаетесь на файл для повторного использования. При развертывании файла Bicep также развертываются ресурсы в модуле.
module webModule './webApp.bicep' = {
name: 'webDeploy'
params: {
skuName: 'S1'
location: location
}
}
Символическое имя позволяет ссылаться на модуль из другого места в файле. Например, можно получить выходное значение из модуля, используя символическое имя и имя выходного значения.
Дополнительные сведения см. в статье Использование модулей Bicep.
Декораторы ресурсов и модулей
Декоратор можно добавить к определению ресурса или модуля. Единственный поддерживаемый декоратор — batchSize(int). Его можно применить только для определения ресурса или модуля, в котором используется выражение for.
По умолчанию ресурсы развертываются параллельно. При добавлении декоратора batchSize экземпляры развертываются последовательно.
@batchSize(3)
resource storageAccountResources 'Microsoft.Storage/storageAccounts@2019-06-01' = [for storageName in storageAccounts: {
...
}]
Дополнительные сведения см. в статье Развертывание в пакетах.
Выходные данные
Выходные данные можно использовать для возврата значений из развертывания. Как правило, значение возвращается из развернутого ресурса, когда необходимо повторно использовать его для другой операции.
output storageEndpoint object = stg.properties.primaryEndpoints
Дополнительные сведения см. в разделе Выходные данные в Bicep.
Циклы
В файл Bicep можно добавить итеративные циклы, чтобы определить несколько копий следующих объектов:
- ресурс
- module
- Переменная
- свойство;
- 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
Многострочные строки
Строку можно разбить на несколько строк. В качестве начала и окончания многострочной строки используйте три символа одинарной кавычки '''.
Символы в многострочной строке обрабатываются как есть. Escape-символы не нужны. Невозможно включить ''' в многострочную строку. В настоящее время интерполяция строк не поддерживается.
Можно либо начать строку сразу после открытия ''', либо добавить новую строку. В любом случае в результирующую строку новая строка не входит. В зависимости от завершения строк в файле 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 версии 0.7.4 или более поздней.
В следующем примере определение resourceGroup() разбивается на несколько строк.
var foo = resourceGroup(
mySubscription,
myRgName)
Примеры объявлений с несколькими строками см. в разделах Массивы и Объекты.
Известные ограничения
- Не поддерживает концепцию apiProfile, которая используется для сопоставления одного apiProfile с набором apiVersion для каждого типа ресурсов.
- Определяемые пользователем функций не поддерживаются.
- Для некоторых функций Bicep требуется соответствующее изменение промежуточного языка (шаблоны JSON Azure Resource Manager). О доступности этих функций будет объявлено после развертывания всех необходимых обновлений в глобальной среде Azure. Если вы используете другую среду, например Azure Stack, функция может быть доступна немного позже. Функция Bicep доступна только в том случае, если в этой среде также был обновлен промежуточный язык.
Дальнейшие действия
Общие сведения о Bicep см. в статье Что такое Bicep? Сведения о типах данных Bicep см. в разделе Типы данных.