Параметры в Bicep

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

Resource Manager разрешает значения параметров перед началом операций развертывания. Когда используется параметр, Resource Manager заменяет его разрешенным значением.

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

Bicep разрешает не более 256 параметров. Дополнительные сведения см. в разделе Ограничения шаблона.

Рекомендации по настройке параметров см. в разделе Параметры.

Обучающие материалы

Дополнительные сведения о параметрах и практические инструкции см. в схеме обучения Создание повторно используемых шаблонов Bicep с помощью параметров.

Определить параметры

Каждый параметр имеет имя и тип данных. При желании вы можете предоставить для параметра значение по умолчанию.

@<decorator>(<argument>)
param <parameter-name> <parameter-data-type> = <default-value>

Имя параметра не может совпадать с именем переменной, ресурса, выходных данных или другого параметра в той же области.

Ниже представлены простые примеры объявления параметров.

param demoString string
param demoInt int
param demoBool bool
param demoObject object
param demoArray array

Ключевое param слово также используется в файлах Bicepparam. В файлах Bicepparam не нужно указывать тип данных, так как он определен в файлах Bicep.

param <parameter-name> = <value>

Дополнительные сведения см. в файле параметров.

Определяемые пользователем выражения типов можно использовать в качестве предложения типа инструкции param . Например:

param storageAccountConfig {
  name: string
  sku: string
}

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

Установка значений по умолчанию

Можно указать значение параметра по умолчанию. Оно используется, если во время развертывания не указано значение.

param demoParam string = 'Contoso'

Выражения можно использовать со значением по умолчанию. Выражения с другими свойствами параметров не допускаются. Нельзя использовать функцию reference или любую из функций list в разделе parameters. Эти функции получают состояние среды выполнения ресурса и не могут быть выполнены перед развертыванием при разрешении параметров.

param location string = resourceGroup().location

Также для создания значения по умолчанию можно использовать значение другого параметра. Следующий шаблон конструирует имя плана узла из имени сайта.

param siteName string = 'site${uniqueString(resourceGroup().id)}'
param hostingPlanName string = '${siteName}-plan'

output siteNameOutput string = siteName
output hostingPlanOutput string = hostingPlanName

Однако нельзя ссылаться на переменную в качестве значения по умолчанию.

Использование декораторов

Параметры используют декораторы для ограничений или метаданных. Декораторы имеют формат @expression и помещаются перед объявлением параметра. В следующей таблице показаны доступные декораторы для параметров.

Декоратор	Как применить	Аргумент	Description
allowed	all	array	Используйте этот декоратор, чтобы убедиться, что пользователь предоставляет правильные значения. Этот декоратор разрешен только для param инструкций. Чтобы объявить, что свойство должно быть одним из наборов предопределенных значений в инструкции type или output операторе, используйте синтаксис типа объединения. Синтаксис типа объединения также можно использовать в param инструкциях.
описание	all	строка	Текст, в котором описано, как использовать этот параметр. Описание параметра, которое пользователь может посмотреть на портале.
дискриминатор	объект	строка	Используйте этот декоратор, чтобы убедиться, что правильный подкласс определен и управляется. Дополнительные сведения см. в разделе "Тип данных с пользовательским тегом объединения".
maxLength	Массив, строка	INT	Максимальная длина для параметров строки и массива. Значение является инклюзивным.
maxValue	INT	INT	Максимальное значение для целочисленного параметра. Это значение является инклюзивным.
metadata	all	объект	Пользовательские свойства, применяемые к параметру. Может включать свойство "Описание", которое эквивалентно декоратору "Описание".
minLength	Массив, строка	INT	Минимальная длина параметров строки и массива. Значение является инклюзивным.
minValue	INT	INT	Минимальное значение для целочисленного параметра. Это значение является инклюзивным.
sealed	объект	ничего	Повышение уровня BCP089 от предупреждения до ошибки, когда имя свойства типа данных, определяемого с использованием, скорее всего, является опечаткой. Дополнительные сведения см. в разделе "Повышение уровня ошибок".
secure	Строка, объект	ничего	Помечает параметр как безопасный. Значение безопасного параметра не сохраняется в журнале развертывания и не записывается в журнал. Дополнительные сведения см. в разделе Защита строк и объектов.

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

@sys.description('The name of the instance.')
param name string
@sys.description('The description of the instance to display.')
param description string

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

Вы можете определить допустимые значения параметра. Допустимые значения задаются в массиве. Развертывание завершается ошибкой во время проверки, если значение передается в качестве параметра, который не является одним из допустимых значений.

@allowed([
  'one'
  'two'
])
param demoEnum string

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

Description

Чтобы пользователи могли понять, какое значение нужно предоставлять, добавьте описание параметра. Когда пользователь развертывает шаблон через портал, текст описания автоматически используется в качестве подсказки для этого параметра. Добавлять описание следует только в том случае, если текст содержит больше информации, чем можно понять из имени параметра.

@description('Must be at least Standard_A3 to support 2 NICs.')
param virtualMachineSize string = 'Standard_DS1_v2'

Для текста описания можно использовать текст в формате Markdown:

@description('''
Storage account name restrictions:
- Storage account names must be between 3 and 24 characters in length and may contain numbers and lowercase letters only.
- Your storage account name must be unique within Azure. No two storage accounts can have the same name.
''')
@minLength(3)
@maxLength(24)
param storageAccountName string

При наведении курсора на storageAccountName в VS Code отображается форматированный текст:

Убедитесь, что текст следует правильному форматированию Markdown; в противном случае он может не отображаться правильно при отрисовки.

Дискриминатор

См . тип данных с пользовательским тегом объединения.

Ограничения для целочисленных параметров

Для целочисленных параметров можно задать минимальное и максимальное значения. Вы можете установить один или оба этих предела.

@minValue(1)
@maxValue(12)
param month int

Ограничения длины

Для параметров типов “строка” и “массив” можно указать минимальную и максимальную длину. Вы можете установить один или оба этих предела. Для строк длина указывает количество символов. Для массивов она указывает количество элементов.

В приведенном ниже примере объявляются два параметра. Один из них — имя учетной записи хранения, которое должно содержать 3–24 символа. Другой параметр — это массив, который должен содержать от 1 до 5 элементов.

@minLength(3)
@maxLength(24)
param storageAccountName string

@minLength(1)
@maxLength(5)
param appNames array

Метаданные

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

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

@description('Configuration values that are applied when the application starts.')
@metadata({
  source: 'database'
  contact: 'Web team'
})
param settings object

Когда вы предоставляете декоратор с свойством @metadata() , который конфликтует с другим декоратором, этот декоратор всегда имеет приоритет над всем в декораторе @metadata() . Таким образом, конфликтующее свойство в значении @metadata() является избыточным и будет заменено. Дополнительные сведения см. в разделе "Нет конфликтующих метаданных".

Запечатанный

См. сведения об уровне ошибок с повышенными привилегиями.

Защищенные параметры

Можно пометить параметры типа "строка" или "объект" как защищенные. Значение защищенного параметра не сохраняется в журнале развертывания и не заносится в журнал.

@secure()
param demoPassword string

@secure()
param demoSecretObject object

Существует несколько правил linter, связанных с этим декоратором: безопасный параметр по умолчанию, безопасные параметры в вложенных развертываниях, безопасные секреты в параметрах.

Использование параметров

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

param vaultName string = 'keyVault${uniqueString(resourceGroup().id)}'

resource keyvault 'Microsoft.KeyVault/vaults@2019-09-01' = {
  name: vaultName
  ...
}

Использование объектов в качестве параметров

Чтобы структурировать связанные друг с другом значения, их можно передать в виде объекта. Что не менее важно, этот подход сокращает число параметров в шаблоне.

В приведенном ниже примере показан параметр, который является объектом. Значение по умолчанию отражает ожидаемые свойства объекта. Эти свойства используются при определении развертываемого ресурса.

param vNetSettings object = {
  name: 'VNet1'
  location: 'eastus'
  addressPrefixes: [
    {
      name: 'firstPrefix'
      addressPrefix: '10.0.0.0/22'
    }
  ]
  subnets: [
    {
      name: 'firstSubnet'
      addressPrefix: '10.0.0.0/24'
    }
    {
      name: 'secondSubnet'
      addressPrefix: '10.0.1.0/24'
    }
  ]
}

resource vnet 'Microsoft.Network/virtualNetworks@2023-11-01' = {
  name: vNetSettings.name
  location: vNetSettings.location
  properties: {
    addressSpace: {
      addressPrefixes: [
        vNetSettings.addressPrefixes[0].addressPrefix
      ]
    }
    subnets: [
      {
        name: vNetSettings.subnets[0].name
        properties: {
          addressPrefix: vNetSettings.subnets[0].addressPrefix
        }
      }
      {
        name: vNetSettings.subnets[1].name
        properties: {
          addressPrefix: vNetSettings.subnets[1].addressPrefix
        }
      }
    ]
  }
}

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

• Дополнительные сведения о доступных свойствах для параметров см. в статье Общие сведения о структуре и синтаксисе файлов Bicep.
• Дополнительные сведения о передаче значений параметров в виде файла см. в статье Создание файла параметров Bicep.
• Дополнительные сведения о предоставлении значений параметров во время развертывания см. в статье "Развертывание с помощью Azure CLI" и "Развертывание с помощью Azure PowerShell".