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

Bicep에서 사용자 정의 데이터 형식을 만드는 방법을 알아봅니다. 시스템 정의 데이터 형식에 대해서는 데이터 형식을 참조하세요. 사용자 정의 데이터 형식을 사용하면 언어 버전 2.0 코드를 자동으로 생성할 수 있습니다.

이 기능을 사용하려면 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?
  }
  

  속성에 데코레이터를 사용할 수 있습니다. 별표(*)를 사용하여 모든 값에 제약 조건이 필요하도록 할 수 있습니다. 를 사용하여 *더 많은 속성을 정의할 수 있습니다. 이 예제에서는 이름이 지정된 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또는 level2level3level4 선택 사항이 없기 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 스를 추가해야 합니다.

판별자

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

설명

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

@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 하려고 했지만 철자가 틀렸다고 가정합니다. 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 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 데이터 형식 목록은 데이터 형식을 참조하세요.