Описание структуры и синтаксиса файлов Bicep

В этой статье описываются структура и синтаксис файла Bicep. Статья содержит информацию о разных разделах файла и свойствах, которые доступны в этих разделах.

Пошаговые инструкции по созданию файла Bicep см. в разделе Краткое руководство. Создание файлов Bicep с помощью Visual Studio Code.

Формат 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
• resource
• module
• выходные данные
• func
• type

Декораторы включают:

Декоратор	Применение к элементу	Применение к типу данных	Аргумент	Description
allowed	param	all	array	Используйте этот декоратор, чтобы убедиться, что пользователь предоставляет правильные значения. Этот декоратор разрешен только для param инструкций. Чтобы объявить, что свойство должно быть одним из наборов предопределенных значений в инструкции type или output операторе, используйте синтаксис типа объединения. Синтаксис типа объединения также можно использовать в param инструкциях.
batchSize	модуль, ресурс	Н/П	integer	Настройте экземпляры для последовательного развертывания.
описание	func, param, module, output, resource, type, var	all	строка	Укажите описания элементов. Текст в формате Markdown можно использовать для текста описания.
дискриминатор	param, type, output	объект	строка	Используйте этот декоратор, чтобы убедиться, что правильный подкласс определен и управляется. Дополнительные сведения см. в разделе "Тип данных с пользовательским тегом объединения".
экспорт	func, type, var	all	ничего	Указывает, что элемент можно импортировать другим файлом Bicep.
maxLength	param, output, type	Массив, строка	INT	Максимальная длина элементов строки и массива. Значение является инклюзивным.
maxValue	param, output, type	INT	INT	Максимальное значение для целых элементов. Это значение является инклюзивным.
metadata	func, output, param, type	all	объект	Настраиваемые свойства для применения к элементам. Может включать свойство "Описание", которое эквивалентно декоратору "Описание".
minLength	param, output, type	Массив, строка	INT	Минимальная длина элементов строки и массива. Значение является инклюзивным.
minValue	param, output, type	INT	INT	Минимальное значение для целых элементов. Это значение является инклюзивным.
sealed	param, type, output	объект	ничего	Повышение уровня 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'
    }
  }
}

В следующем примере показано, как определить дочерний ресурс за пределами родительского ресурса. Свойство родительского ресурса используется для определения связи "родители-потомки". Определены те же три ресурса.

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.

Выходные данные

Выходные данные можно использовать для возврата значений из развертывания. Как правило, значение возвращается из развернутого ресурса, когда необходимо повторно использовать его для другой операции.

output storageEndpoint object = stg.properties.primaryEndpoints

Для каждого вывода можно добавить один или несколько декораторов. Дополнительные сведения см. в разделе "Использование декораторов".

Дополнительные сведения см. в разделе Выходные данные в Bicep.

Циклы

В файл Bicep можно добавить итеративные циклы, чтобы определить несколько копий следующих объектов:

• resource
• модуль
• переменная
• свойство
• 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

Многострочные строки

Строку можно разбить на несколько строк. В качестве начала и окончания многострочной строки используйте три символа одинарной кавычки '''.

Символы в многострочной строке обрабатываются как есть. 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.X или более поздней.

В следующем примере определение resourceGroup() разбивается на несколько строк.

var foo = resourceGroup(
  mySubscription,
  myRgName)

Примеры объявлений с несколькими строками см. в разделах Массивы и Объекты.

Известные ограничения

• Не поддерживает концепцию apiProfile, которая используется для сопоставления одного apiProfile с набором apiVersion для каждого типа ресурсов.
• Определяемые пользователем функции сейчас не поддерживаются. Однако экспериментальная функция в настоящее время доступна. Дополнительные сведения см. в разделе "Определяемые пользователем функции" в Bicep.
• Для некоторых функций Bicep требуется соответствующее изменение промежуточного языка (шаблоны JSON Azure Resource Manager). О доступности этих функций будет объявлено после развертывания всех необходимых обновлений в глобальной среде Azure. Если вы используете другую среду, например Azure Stack, функция может быть доступна немного позже. Функция Bicep доступна только в том случае, если в этой среде также был обновлен промежуточный язык.

Следующие шаги

Общие сведения о Bicep см. в статье Что такое Bicep? Сведения о типах данных Bicep см. в разделе Типы данных.