Прочитать на английском

Поделиться через

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

  • Статья

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

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

Формат Bicep

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>

В следующем примере показана реализация этих элементов.

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

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

В модуле можно указать область, которая будет отличаться от области остальной части файла Bicep. Дополнительные сведения см. в разделе Настройка области модуля.

Декораторы

Вы можете добавить один или несколько декораторов для каждого из следующих элементов:

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

Декоратор Применение к элементу Применение к типу данных Аргумент 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 для указания различных размеров ресурса. В зависимости от того, в какую среду — тестовую или производственную — выполняется развертывание, можно передавать разные значения.

Bicep 
param storageSKU string = 'Standard_LRS'

Параметр доступен для использования в файле Bicep.

Bicep 
sku: {
  name: storageSKU
}

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

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

Переменные

Чтобы сделать файл Bicep более удобочитаемым, можно инкапсулировать сложные выражения в переменной. Например, можно добавить переменную для имени ресурса, созданного путем соединения нескольких значений.

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

Применяйте эту переменную везде, где требуется сложное выражение.

Bicep 
resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: uniqueStorageName

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

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

Типы

Инструкцию type можно использовать для определения определяемых пользователем типов данных.

Bicep 
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')

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

Ресурсы

Используйте ключевое слово resource, чтобы определить развертываемый ресурс. Объявление ресурса содержит его символическое имя. Это символьное имя используется в других частях файла Bicep, чтобы получить значение из ресурса.

Объявление ресурса содержит тип ресурса и версию API. В тексте объявления ресурса укажите свойства, относящиеся к типу ресурса.

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

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

Дополнительные сведения см. в разделе Объявление ресурса в Bicep.

Некоторые ресурсы имеют связь "родители-потомки". Дочерний ресурс можно определить внутри родительского ресурса или за его пределами.

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

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

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

Bicep 
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 также развертываются ресурсы в модуле.

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

Символическое имя позволяет ссылаться на модуль из другого места в файле. Например, можно получить выходное значение из модуля, используя символическое имя и имя выходного значения.

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

Дополнительные сведения см. в статье Использование модулей Bicep.

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

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

Bicep 
output storageEndpoint object = stg.properties.primaryEndpoints

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

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

Циклы

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

  • resource
  • модуль
  • переменная
  • свойство
  • output

Для определения цикла следует использовать выражение for.

Bicep 
param moduleCount int = 2

module stgModule './example.bicep' = [for i in range(0, moduleCount): {
  name: '${i}deployModule'
  params: {
  }
}]

Можно выполнить итерацию по массиву, объекту или целочисленному индексу.

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

Условное развертывание

В файл Bicep, который развертывается условно, можно добавить ресурс или модуль. Условие оценивается во время развертывания, и в результате определяется, развернут ли ресурс или модуль. Для определения условного развертывания используйте выражение if.

Bicep 
param deployZone bool

resource dnsZone 'Microsoft.Network/dnsZones@2023-07-01-preview' = if (deployZone) {
  name: 'myZone'
  location: 'global'
}

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

Пробел

При создании файлов Bicep пробелы и символы табуляции игнорируются.

В файлах Bicep учитываются символы новой строки. Например:

Bicep 
resource sa 'Microsoft.Storage/storageAccounts@2023-04-01' = if (newOrExisting == 'new') {
  ...
}

Нельзя записать как:

Bicep 
resource sa 'Microsoft.Storage/storageAccounts@2023-04-01' =
    if (newOrExisting == 'new') {
      ...
    }

Объекты и массивы следует определять в нескольких строках.

Комментарии

Укажите // для однострочных комментариев или /* ... */ для многострочных комментариев.

В следующем примере показан однострочный комментарий.

Bicep 
// This is your primary NIC.
resource nic1 'Microsoft.Network/networkInterfaces@2023-11-01' = {
  ...
}

В следующем примере показан многострочный комментарий.

Bicep 
/*
  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.

В следующем примере показана многострочная строка.

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

Предыдущий пример эквивалентен следующему JSON.

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

Объявления с несколькими строками

Теперь можно использовать несколько строк в объявлениях функций, массивов и объектов. Для этой функции требуется интерфейс командной строки Bicep версии 0.7.X или более поздней.

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

Bicep 
var foo = resourceGroup(
  mySubscription,
  myRgName)

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

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

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

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

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