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

Статья
10/29/2024

Узнайте, как создать определяемые пользователем типы данных в Bicep. Сведения о системных типах данных см. в разделе "Типы данных". Использование определяемых пользователем типов данных автоматически включает создание кода версии 2.0 .

Для использования этой функции требуется интерфейс командной строки Bicep версии 0.12.X или более поздней .

Определение типов

Инструкцию type можно использовать для создания определяемых пользователем типов данных. Выражения типов также можно использовать в некоторых местах для определения пользовательских типов.

@<decorator>(<argument>)
type <user-defined-data-type-name> = <type-expression>

Декоратор @allowed разрешен только для param инструкций. Чтобы объявить тип с набором предопределенных значений в typeсинтаксисе типа объединения.

Допустимые выражения типов включают:

Символьные ссылки — это идентификаторы, ссылающиеся на внешний тип (напримерstring, илиint) или символ определяемого пользователем типа, объявленный в инструкцииtype:
```
// Bicep data type reference
type myStringType = string

// user-defined type reference
type myOtherStringType = myStringType
```

Примитивные литералы, включая строки, целые числа и логические выражения, являются допустимыми выражениями типов. Например:

// a string type with three allowed values.
type myStringLiteralType = 'bicep' | 'arm' | 'azure'

// an integer type with one allowed value
type myIntLiteralType = 10

// an boolean type with one allowed value
type myBoolLiteralType = true

Можно объявить типы массивов, добавляя к любому допустимому выражению [] типа:

// A string type array
type myStrStringsType1 = string[]
// A string type array with three allowed values
type myStrStringsType2 = ('a' | 'b' | 'c')[]

type myIntArrayOfArraysType = int[][]

// A mixed-type array with four allowed values
type myMixedTypeArrayType = ('fizz' | 42 | {an: 'object'} | null)[]

Типы объектов содержат ноль или больше свойств между фигурными скобками:
```
type storageAccountConfigType = {
  name: string
  sku: string
}
```
Каждое свойство в объекте состоит из ключа и значения, разделенного двоеточием :. Ключ может быть любой строкой, с неидентификаторными значениями, заключенными в кавычки. Значение может быть любым типом выражения.

Свойства требуются, если они не имеют маркера необязательности ? после значения свойства. Например, sku свойство в следующем примере является необязательным:
```
type storageAccountConfigType = {
  name: string
  sku: string?
}
```
Вы можете использовать декораторы для свойств. Звездочка (*) можно использовать для выполнения всех значений, требующих ограничения. Вы можете определить дополнительные свойства с помощью *. В этом примере создается объект, требующий ключа типа int с именем id. Все остальные записи в объекте должны быть строковым значением не менее 10 символов.
```
type obj = {
  @description('The object ID')
  id: int

  @description('Additional properties')
  @minLength(10)
  *: string
}
```
В следующем примере показано, как использовать синтаксис типа объединения для перечисления набора предопределенных значений:
```
type directions = 'east' | 'south' | 'west' | 'north'

type obj = {
  level: 'bronze' | 'silver' | 'gold'
}
```
Типы объектов могут использовать прямую или непрямую рекурсию, если по крайней мере путь к точке рекурсии является необязательным. Например, определение в следующем примере допустимо, myObjectType так как непосредственно рекурсивное свойство является необязательным recursiveProp :
```
type myObjectType = {
  stringProp: string
  recursiveProp: myObjectType?
}
```
Следующее определение типа не будет допустимым, так как ни один из level1, level2или level3level4level5 необязательный.
```
type invalidRecursiveObjectType = {
  level1: {
    level2: {
      level3: {
        level4: {
          level5: invalidRecursiveObjectType
        }
      }
    }
  }
}
```
Можно использовать унарные операторы Bicep с целыми числами и логическими литералами или ссылками на целые или логические символы, типизированные литералами:
```
type negativeIntLiteral = -10
type negatedIntReference = -negativeIntLiteral

type negatedBoolLiteral = !true
type negatedBoolReference = !negatedBoolLiteral
```
Профсоюзы могут включать любое количество литеральных выражений. Типы объединения превратятся в ограничение разрешенного значения в Bicep, поэтому только литералы разрешены в качестве членов.
```
type oneOfSeveralObjects = {foo: 'bar'} | {fizz: 'buzz'} | {snap: 'crackle'}
type mixedTypeArray = ('fizz' | 42 | {an: 'object'} | null)[]
```

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

В качестве предложения типа инструкции param . Например:
```
param storageAccountConfig {
  name: string
  sku: string
}
```

: После свойства типа объекта. Например:

param storageAccountConfig {
 name: string
  properties: {
    sku: string
  }
} = {
  name: 'store$(uniqueString(resourceGroup().id)))'
  properties: {
    sku: 'Standard_LRS'
  }
}

Перед выражением [] типа массива. Например:
```
param mixedTypeArray ('fizz' | 42 | {an: 'object'} | null)[]
```

Типичный Bicep-файл для создания учетной записи хранения выглядит следующим образом:

param location string = resourceGroup().location
param storageAccountName string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
])
param storageAccountSKU string = 'Standard_LRS'

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: storageAccountSKU
  }
  kind: 'StorageV2'
}

Определяемые пользователем типы данных могут выглядеть следующим образом:

param location string = resourceGroup().location

type storageAccountSkuType = 'Standard_LRS' | 'Standard_GRS'

type storageAccountConfigType = {
  name: string
  sku: storageAccountSkuType
}

param storageAccountConfig storageAccountConfigType

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: storageAccountConfig.name
  location: location
  sku: {
    name: storageAccountConfig.sku
  }
  kind: 'StorageV2'
}

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

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

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

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

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

См . раздел "Тип данных объединения с тегами".

Description

Добавьте описание в определяемый пользователем тип данных. Вы можете использовать декораторы для свойств. Например:

@description('Define a new object type.')
type obj = {
  @description('The object ID')
  id: int

  @description('Additional properties')
  @minLength(10)
  *: string
}

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

Экспорт (Export)

Используется @export() для совместного использования определяемого пользователем типа данных с другими файлами Bicep. Дополнительные сведения см. в разделе "Экспорт переменных", "типы" и "Функции".

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

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

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

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

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

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

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

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

Метаданные

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

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

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

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

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

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

Безопасные типы

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

@secure()
type demoPassword string

@secure()
type demoSecretObject object

Повышение уровня ошибок

По умолчанию объявление типа объекта в Bicep позволяет принимать больше свойств любого типа. Например, следующий Bicep действителен, но вызывает предупреждение [BCP089]: The property "otionalProperty" is not allowed on objects of type "{ property: string, optionalProperty: null | string }". Did you mean "optionalProperty"?

type anObject = {
  property: string
  optionalProperty: string?
}
 
param aParameter anObject = {
  property: 'value'
  otionalProperty: 'value'
}

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

Чтобы передать эти предупреждения в ошибки, примените @sealed() декоратор к типу объекта:

@sealed() 
type anObject = {
  property: string
  optionalProperty?: string
}

Вы получаете те же результаты, применяя @sealed() декоратор к param объявлению:

type anObject = {
  property: string
  optionalProperty: string?
}
 
@sealed() 
param aParameter anObject = {
  property: 'value'
  otionalProperty: 'value'
}

Модуль развертывания Azure Resource Manager также проверяет запечатанные типы для других свойств. Предоставление дополнительных свойств для запечатанных параметров приводит к ошибке проверки, что приводит к сбою развертывания. Например:

@sealed()
type anObject = {
  property: string
}

param aParameter anObject = {
  property: 'value'
  optionalProperty: 'value'
}

Тип данных объединения с тегами

Чтобы объявить настраиваемый тип данных объединения тегами в файле Bicep, можно разместить discriminator декоратор над объявлением определяемого пользователем типа. Для использования этого декоратора требуется интерфейс командной строки Bicep версии 0.21.X или более поздней . В следующем примере показано, как объявить тип данных объединения с тегами:

type FooConfig = {
  type: 'foo'
  value: int
}

type BarConfig = {
  type: 'bar'
  value: bool
}

@discriminator('type')
type ServiceConfig = FooConfig | BarConfig | { type: 'baz', *: string }

param serviceConfig ServiceConfig = { type: 'bar', value: true }

output config object = serviceConfig

Дополнительные сведения см. в разделе "Пользовательский тип данных объединения с тегами".

Список типов данных Bicep см. в разделе "Типы данных".

Поделиться через

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

Определение типов

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

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

Description

Экспорт (Export)

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

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

Метаданные

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

Безопасные типы

Повышение уровня ошибок

Тип данных объединения с тегами

Обратная связь

Дополнительные ресурсы

Поделиться через

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

Определение типов

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

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

Description

Экспорт (Export)

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

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

Метаданные

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

Безопасные типы

Повышение уровня ошибок

Тип данных объединения с тегами

Связанный контент

Обратная связь

Дополнительные ресурсы