Структура и синтаксис файла 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
• ресурс
• module
• выходные данные
• func
• тип

В следующей таблице перечислены декораторы:

Декоратор	Применение к элементу	Применить к типу данных	Аргумент	Описание
разрешено	param	все	массив	Используйте этот декоратор, чтобы убедиться, что пользователь предоставляет правильные значения. Этот декоратор разрешен только для утверждений param. Чтобы объявить, что свойство должно быть одним из заданного набора предопределенных значений в инструкции type или output, используйте синтаксис типа объединения. Вы также можете использовать синтаксис объединённого типа в операторах param.
размер партии	модуль, ресурс	Н/П	целое число	Настройте экземпляры для последовательного развертывания.
описание	func, param, module, output, resource, type, var	все	строка	Укажите описания элементов. Используйте форматированный текст Markdown для текста описания.
дискриминатор	param, type, output	объект	строка	Используйте этот декоратор, чтобы убедиться, что правильный подкласс определен и управляется. Для получения дополнительной информации см. тип данных объединения с пользовательской меткой.
экспорт	func, type, var	все	ничего	Указывает, что другой файл Bicep может импортировать элемент.
максимальная длина (maxLength)	param, output, type	Массив, строка	INT	Максимальная длина элементов строки и массива. Значение является инклюзивным.
максимальное значение	param, output, type	INT	INT	Максимальное значение для целых элементов. Это значение является инклюзивным.
метаданные	func, output, param, type	все	объект	Настраиваемые свойства для применения к элементам. Может включать свойство «Описание», которое эквивалентно декоратору «Описание».
минимальная_длина	param, output, type	Массив, строка	INT	Минимальная длина элементов строки и массива. Значение является включительным.
минимальное значение	param, output, type	INT	INT	Минимальное значение для целых элементов. Это значение является инклюзивным.
запечатанный	param, type, output	объект	ничего	Повысить BCP089 из предупреждения до ошибки, если имя свойства пользовательского типа данных, скорее всего, является опечаткой. Дополнительные сведения см. в разделе "Повышение уровня ошибок".
безопасный	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. Создайте собственные функции при наличии сложных выражений, которые многократно используются в файлах 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')

Дополнительные сведения см. в разделе "Определяемые пользователем функции" в Bicep.

Ресурсы

Используйте ключевое слово 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, чтобы создать несколько копий:

• Ресурс
• Модуль
• Переменная
• Свойство
• Результат

Для определения цикла следует использовать выражение 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 с использованием оператора if.

Пробел

Пробелы и вкладки игнорируются при создании файлов 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 см. в разделе Типы данных.