Сведения о параметрах

  • 8 мин

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

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

В этом уроке описано, как использовать параметры и декораторы.

Объявление декоратора

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

Вот как объявляется параметр:

param environmentName string

Давайте посмотрим, как все работает:

  • param информирует Bicep о том, что вы объявляете параметр.

  • environmentName означает имя параметра. Хотя имя параметра может быть любым, оно должно быть понятным для пользователей шаблона. В одном и том же шаблоне можно также ссылаться на параметр, используя его имя. Имена параметров должны быть уникальными. Параметр не может иметь то же имя, что и переменная или ресурс в одном и том же файле Bicep.

    Совет

    Используйте соглашения об именовании для объявлений параметров. Так шаблоны будет проще читать и распознавать. Убедитесь, что используете понятные описательные и согласованные имена.

  • string означает тип параметра.

    Совет

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

Добавление значения по умолчанию

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

Вот как добавить значение по умолчанию:

param environmentName string = 'dev'

Параметру environmentName присваивается значение по умолчанию dev.

Вы можете использовать выражения как значения по умолчанию. Вот пример строкового параметра с именем location и значением по умолчанию, которое соответствует расположению текущей группы ресурсов:

param location string = resourceGroup().location

Совет

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

Общие сведения о типах параметров

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

Параметры в Bicep могут принадлежать к одному из следующих типов:

  • string — позволяет вводить произвольный текст;
  • int — позволяет вводить числа;
  • bool — представляет логическое значение (true или false);
  • object и array — представляют структурированные данные и списки.

Объект

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

param appServicePlanSku object = {
  name: 'F1'
  tier: 'Free'
  capacity: 1
}

Этот параметр является объектом с двумя строковыми свойствами, name и tier, а также целочисленным свойством capacity. Обратите внимание, что каждое из свойств находится в отдельной строке.

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

resource appServicePlan 'Microsoft.Web/serverfarms@2024-04-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku.name
    tier: appServicePlanSku.tier
    capacity: appServicePlanSku.capacity
  }
}

Внимание

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

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

Теги удобно использовать для отслеживания, когда вам нужно узнать, какая группа владеет ресурсом, или когда ресурс относится к рабочей или нерабочей среде. В большинстве случаев вы будете использовать разные теги для каждой среды, однако вам потребуется повторно использовать одни и те же значения тегов для всех ресурсов в шаблоне. Именно поэтому теги ресурсов — хороший вариант для параметра объекта, например, как указано в этом примере:

param resourceTags object = {
  EnvironmentName: 'Test'
  CostCenter: '1000100'
  Team: 'Human Resources'
}

Определив ресурс в файле Bicep, вы сможете использовать его повторно в любом месте, где определяете свойство tags:

resource appServicePlan 'Microsoft.Web/serverfarms@2024-04-01' = {
  name: appServicePlanName
  location: location
  tags: resourceTags
  sku: {
    name: 'S1'
  }
}

resource appServiceApp 'Microsoft.Web/sites@' = {
  name: appServiceAppName
  location: location
  tags: resourceTags
  kind: 'app'
  properties: {
    serverFarmId: appServicePlan.id
  }
}

Массивы

Массив — это список элементов. Например, вы можете использовать массив строковых значений для объявления списка адресов электронной почты для группы действий Azure Monitor. Или же использовать массив объектов для представления списка подсетей для виртуальной сети.

Примечание.

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

Рассмотрим пример. Azure Cosmos DB позволяет создавать учетные записи баз данных, охватывающие несколько регионов, и автоматически обрабатывать репликацию данных. В процессе развертывания новой учетной записи базы данных вам потребуется указать список регионов Azure, в которые вы хотите развернуть учетную запись. Зачастую для работы с разными средами требуются разные списки расположений. Например, чтобы сэкономить средства, работая в тестовой среде, вы можете использовать только одно или два расположения. Однако в рабочей среде вам, возможно, понадобится использовать несколько расположений.

Вы можете создать параметр массива, указывающий список расположений:

param cosmosDBAccountLocations array = [
  {
    locationName: 'australiaeast'
  }
  {
    locationName: 'southcentralus'
  }
  {
    locationName: 'westeurope'
  }
]

Совет

В предыдущем примере показан массив объектов. Каждый объект имеет свойство locationName, которое ожидает Azure Cosmos DB. Работая с определением ресурса в Visual Studio Code, вы можете начать вводить свойства ресурсов, чтобы получить IntelliSense из инструментов Bicep. С помощью этого подхода можно создать несколько примеров значений. Завершив конфигурацию, переместите этот раздел кода Bicep в параметр. Так вы сможете заменить жестко заданное в коде свойство параметром, который можно изменять во время каждого развертывания, обеспечивая правильную настройку ресурса.

При объявлении ресурса Azure Cosmos DB теперь можно ссылаться на параметр массива:

resource account 'Microsoft.DocumentDB/databaseAccounts@2024-11-15' = {
  name: accountName
  location: location
  properties: {
    locations: cosmosDBAccountLocations
  }
}

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

Указание набора разрешенных значений

В некоторых случаях важно знать, имеет ли параметр определенные значения. Например, команда может решить, что производственные планы службы приложений следует развертывать с использованием SKU уровня "Премиум" (версии 3). Чтобы применить это правило, можно использовать декоратор параметров @allowed. Декоратор параметров — это способ предоставления Bicep сведений о том, каким объектом должно быть значение параметра. Ниже представлены сведения о том, как ограничить строковый параметр с именем appServicePlanSkuName, чтобы назначать можно было только несколько конкретных значений:

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
param appServicePlanSkuName string

Совет

Однако декоратор @allowed нужно использовать относительно редко. Поскольку, используя декоратор слишком часто и не заботясь об актуальности списка, можно заблокировать допустимые развертывания. В предыдущем примере в рабочей среде допускается только использование SKU уровня "Премиум" (версии 3). Если вам нужно использовать один и тот же шаблон для развертывания некоторых более дешевых нерабочих сред, то наличие списка допустимых значений может стать препятствием для использования других номеров SKU, необходимых в определенный момент.

Ограничение длины и значений параметров

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

В приведенном ниже примере объявляется строковый параметр с именем storageAccountName, длина которого может составлять от 5 до 24 символов:

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

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

Примечание.

Декораторы @minLength и @maxLength можно также применять к параметрам массива, чтобы управлять тем, сколько элементов можно размещать в массиве.

Работая с числовыми параметрами, вам может понадобиться, чтобы значения находились в определенном диапазоне. Например, ваша компания по производству игрушек может решить, что при каждом развертывании плана службы приложений необходимо развернуть минимум один экземпляр и максимум 10 экземпляров плана. Чтобы обеспечить соответствие требованиям, используйте декораторы @minValue и @maxValue для указания минимально и максимально допустимых значений. В следующем примере объявляется целочисленный параметр appServicePlanInstanceCount, значение которого может находиться только в диапазоне от 1 до 10 (включительно):

@minValue(1)
@maxValue(10)
param appServicePlanInstanceCount int

Добавление описаний к параметрам

Параметры — это отличный способ сделать шаблоны пригодными для повторного использования другими пользователями. При использовании шаблонов пользователям нужно понять, какое действие выполняет каждый параметр, поскольку так они смогут предоставить правильные значения. Bicep предоставляет декоратор @description, который позволяет документировать назначение параметров в удобочитаемом виде.

@description('The locations into which this Cosmos DB account should be configured. This parameter needs to be a list of objects, each of which has a locationName property.')
param cosmosDBAccountLocations array

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

Примечание.

Иногда шаблоны Bicep могут быть доступны для развертывания пользователями на портале Azure, например, при использовании спецификаций шаблонов. Используемые на портале описания и другие декораторы параметров помогают пользователям понять, какое значение следует задавать в качестве значения параметра.