Bicep의 사용자 정의 데이터 형식

Bicep에서 사용자 정의 데이터 형식을 만드는 방법을 알아봅니다. 시스템 정의 데이터 형식에 대해서는 데이터 형식을 참조하세요.

이 기능을 사용하려면 Bicep CLI 버전 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)[]
  

• 개체 형식은 중괄호 사이에 0개 이상의 속성을 포함합니다.

  type storageAccountConfigType = {
    name: string
    sku: string
  }
  

  개체의 각 속성은 : 콜론으로 구분된 키와 값으로 구성됩니다. 키는 따옴표로 묶인 비식별자 값이 있는 모든 문자열일 수 있으며 값은 식의 모든 형식일 수 있습니다.

  속성 값 다음에 선택적 표식 ?이 없는 한 속성이 필요합니다. 예를 들어 다음 예제의 sku 속성은 선택 사항입니다.

  type storageAccountConfigType = {
    name: string
    sku: string?
  }
  

  데코레이터는 속성에 사용할 수 있습니다. *는 모든 값에 상수가 필요하도록 할 때 사용할 수 있습니다. *를 사용하는 경우에도 추가 속성을 정의할 수 있습니다. 이 예제에서는 id라는 int 형식의 키가 필요하고 개체의 다른 모든 항목은 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'
  }
  

  재귀

  개체 유형은 재귀 지점에 대한 경로의 레그가 선택 사항인 한 직접 또는 간접 재귀를 사용할 수 있습니다. 예를 들어 직접 재귀 recursiveProp 속성은 선택 사항이므로 다음 예제의 myObjectType 정의는 유효합니다.

  type myObjectType = {
    stringProp: string
    recursiveProp: myObjectType?
  }
  

  그러나 level1, level2, level3, level4 또는 level5 중 어느 것도 선택 사항이 아니므로 다음 형식 정의는 유효하지 않습니다.

  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 형식으로 작성되며 사용자 정의 데이터 형식의 선언 위에 배치됩니다. 다음 표에서는 사용자 정의 데이터 형식에 사용할 수 있는 데코레이터를 보여 줍니다.

데코레이터는 sys namespace에 있습니다. 같은 이름의 다른 항목과 데코레이터를 구별해야 하는 경우 데코레이터 앞에 sys를 추가합니다. 예를 들어 Bicep 파일에 description이라는 변수가 포함된 경우 설명 데코레이터를 사용할 때 sys 네임스페이스를 추가해야 합니다.

판별자

태그가 지정된 공용 구조체 데이터 형식을 참조하세요.

설명

사용자 정의 데이터 형식에 설명을 추가합니다. 데코레이터는 속성에 사용할 수 있습니다. 예시:

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

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

설명 텍스트에 Markdown 형식의 텍스트를 사용할 수 있습니다.

내보내기

@export()를 사용하여 사용자 정의 데이터 형식을 다른 Bicep 파일과 공유합니다. 자세한 내용은 변수, 형식 및 함수 내보내기를 참조하세요.

정수 제약 조건

정수 형식의 최솟값과 최댓값을 설정할 수 있습니다. 하나 또는 두 개의 제약 조건을 설정할 수 있습니다.

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

길이 제약 조건

문자열 및 배열 형식의 최소 길이와 최대 길이를 지정할 수 있습니다. 하나 또는 두 개의 제약 조건을 설정할 수 있습니다. 문자열의 경우 길이는 문자 수를 나타냅니다. 배열의 경우 길이는 배열의 항목 수를 나타냅니다.

다음 예제에서는 두 개의 형식을 선언합니다. 한 형식은 스토리지 계정 이름에 대한 것이며, 3~24자여야 합니다. 다른 형식은 배열이며, 1~5개의 항목이 있어야 합니다.

@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를 사용하려고 했지만 철자를 잘못 입력함)하고 불일치에 대해 경고합니다.

이러한 경고를 오류로 에스컬레이션하려면 @sealed() 데코레이터를 개체 유형에 적용합니다.

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

param 선언에 @sealed() 데코레이터를 적용하면 동일한 결과가 나타납니다.

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

ARM 배포 엔진은 또한 봉인된 형식에서 추가 속성을 확인합니다. 봉인된 매개 변수에 대한 추가 속성을 제공하면 유효성 검사 오류가 발생하여 배포에 실패합니다. 예시:

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

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

태그가 지정된 공용 구조체 데이터 형식

Bicep 파일 내에서 사용자 지정 태그가 지정된 공용 구조체 데이터 형식을 선언하려면 사용자 정의 형식 선언 위에 discriminator 데코레이터를 배치할 수 있습니다. 이 데코레이터를 사용하려면 Bicep CLI 버전 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 데이터 형식 목록은 데이터 형식을 참조하세요.