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

  • Статья

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

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

Формат 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 не нужно задавать целевую область.

Допустимые значения:

В модуле можно указать область, которая будет отличаться от области остальной части файла 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'
}

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

Функции (предварительная версия)

Примечание.

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

В 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'
    }
  }
}

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

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

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

var foo = resourceGroup(
  mySubscription,
  myRgName)

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

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

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

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

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