Параметры в Bicep

  • Статья

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

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

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

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

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

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

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

Объявление

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

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
}

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

Default value

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

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

Следующий пример демонстрирует два распространенных сценария применения для декораторов.

@secure()
param demoPassword string

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

В следующей таблице указаны доступные декораторы и способы их использования.

Декоратор Как применить Аргумент Description
allowed all array Допустимые значения для параметра. Используйте этот декоратор, чтобы убедиться, что пользователь предоставляет правильные значения.
описание all строка Текст, в котором описано, как использовать этот параметр. Описание параметра, которое пользователь может посмотреть на портале.
maxLength Массив, строка INT Максимальная длина для параметров строки и массива. Значение является инклюзивным.
maxValue INT INT Максимальное значение для целочисленного параметра. Это значение является инклюзивным.
metadata all объект Пользовательские свойства, применяемые к параметру. Может включать свойство "Описание", которое эквивалентно декоратору "Описание".
minLength Массив, строка INT Минимальная длина параметров строки и массива. Значение является инклюзивным.
minValue INT INT Минимальное значение для целочисленного параметра. Это значение является инклюзивным.
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

Доступные декораторы описаны в следующих разделах.

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

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

@secure()
param demoPassword string

@secure()
param demoSecretObject object

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

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

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

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

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

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

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

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

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

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

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

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

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 в VSCode

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

Метаданные

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

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

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

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

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

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

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@2020-06-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
        }
      }
    ]
  }
}

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