Parameters in Bicep

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

Менеджер ресурсов Azure обрабатывает значения параметров перед началом операций развертывания. Когда используется параметр, 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
}

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

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

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

param demoParam string = 'Contoso'

Выражения можно использовать со значением по умолчанию. Выражения с другими свойствами параметров не допускаются. Вы не можете использовать функцию reference или какие-либо list функции в разделе параметров. These functions get the resource's runtime state and can't be executed before deployment when parameters are resolved.

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

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

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

Parameters use decorators for constraints or metadata. Декораторы имеют формат @expression и помещаются перед объявлением параметра. The following table shows the available decorators for parameters:

Decorators are in the sys namespace. If you need to differentiate a decorator from another item with the same name, preface the decorator with sys. For example, if your Bicep file includes a parameter named description, you must add the sys namespace when using the description decorator.

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

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

Вы можете определить допустимые значения параметра. You provide the allowed values in an array. The deployment fails during validation if a value is passed in for the parameter that isn't one of the allowed values.

@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; в противном случае он может не отображаться правильно при отрисовке.

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

See Custom-tagged union data type.

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

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

@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()
param demoPassword string

@secure()
param demoSecretObject object

There are several linter rules related to this decorator: Secure parameter default, Secure parameters in nested deployments, Secure secrets in parameters.

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

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

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