Параметры в Bicep

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

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

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

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

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

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

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

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

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

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

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

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

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

param demoParam string = 'Contoso'

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

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 и помещаются перед объявлением параметра. В следующей таблице показаны доступные декораторы для параметров:

Декораторы находятся в пространстве имен 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

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

Описание

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

@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 can only contain numbers and lowercase letters.
- 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 в Visual Studio 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() избыточным и подлежащим замене. Дополнительные сведения см. в правиле Linter — не конфликтующие метаданные.

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

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

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

Можно пометить параметры типа "строка" или "объект" как защищенные. Когда параметр отмечен @secure(), диспетчер ресурсов Azure обрабатывает значение параметра как конфиденциальное, предотвращая его запись в журнал или отображение в истории развертываний, на портале Azure или в выводах командной строки.

@secure()
param demoPassword string

@secure()
param demoSecretObject object

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

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

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

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

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

Декоратор @secure() действителен только для параметров строки или объекта типа, так как они соответствуют типам secureString и secureObject в шаблонах ARM. Чтобы безопасно передать массивы или числа, заключите их в secureObject или сериализируйте их как secureString.

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

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

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

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@2025-01-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".
• Дополнительные сведения о предоставлении значений параметров во время развертывания см. в статье "Развертывание файлов Bicep" с помощью Azure CLI и Azure PowerShell.