Bicep의 매개 변수

이 문서에서는 Bicep 파일에서 매개 변수를 정의하고 사용하는 방법을 설명합니다. 매개 변수에 다른 값을 제공하여 여러 환경에서 Bicep 파일을 다시 사용할 수 있습니다.

Resource Manager는 배포 작업을 시작하기 전에 매개 변수 값을 확인합니다. 매개 변수가 사용될 때마다 Resource Manager는 매개 변수를 확인된 값으로 바꿉니다.

각 매개 변수는 데이터 형식 중 하나로 설정해야 합니다.

Microsoft Learn

단계별 지침을 통해 매개 변수에 대해 알아보려면 Microsoft Learn에서 매개 변수를 사용하여 재사용 가능한 Bicep 템플릿 빌드를 참조하세요.

선언

각 매개 변수에는 이름과 데이터 형식이 있습니다. 필요에 따라 매개 변수의 기본값을 제공할 수 있습니다.

param <parameter-name> <parameter-data-type> = <default-value>

매개 변수는 동일한 범위에 있는 변수, 리소스, 출력 또는 다른 매개 변수와 동일한 이름을 가질 수 없습니다.

다음 예제에서는 매개 변수의 기본 선언을 보여 줍니다.

param demoString string
param demoInt int
param demoBool bool
param demoObject object
param demoArray array

기본값

매개 변수의 기본값을 지정할 수 있습니다. 기본값은 배포 중에 값이 제공되지 않는 경우에 사용됩니다.

param demoParam string = 'Contoso'

기본값으로 식을 사용할 수 있습니다. 식은 다른 매개 변수 속성에서 허용되지 않습니다. 매개 변수 섹션에서는 reference 함수 또는 list 함수를 사용할 수 없습니다. 이러한 함수는 리소스의 런타임 상태를 가져오며, 매개 변수를 확인할 때 배포 전에 실행할 수 없습니다.

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

데코레이터

매개 변수는 제약 조건 또는 메타데이터에 데코레이터를 사용합니다. 데코레이터는 @expression 형식이며 매개 변수의 선언 위에 배치됩니다. 매개 변수를 안전한 것으로 표시하고, 허용된 값을 지정하고, 문자열의 최소 및 최대 길이를 설정하고, 정수의 최소값 및 최대값을 설정하고, 매개 변수의 설명을 제공할 수 있습니다.

다음 예제에서는 데코레이터의 두 가지 일반적인 용도를 보여 줍니다.

@secure()
param demoPassword string

@description('Must be at least Standard_A3 to support 2 NICs.')
param virtualMachineSize string = 'Standard_DS1_v2'

다음 표에서는 사용할 수 있는 데코레이터와 그 사용 방법에 대해 설명합니다.

데코레이터 적용 대상 인수 설명
허용됨 모두 array 매개 변수에 허용되는 값입니다. 해당 데코레이터를 사용하여 사용자가 올바른 값을 제공하는지 확인합니다.
description 모두 문자열 매개 변수를 사용하는 방법을 설명하는 텍스트입니다. 포털을 통해 사용자에게 설명이 표시됩니다.
maxLength 배열, 문자열 int 문자열 및 배열 매개 변수의 최대 길이입니다. 해당 값이 포함되어 있습니다.
maxValue int int 정수 매개 변수의 최댓값입니다. 해당 값이 포함되어 있습니다.
metadata 모두 개체 매개 변수에 적용할 사용자 지정 속성입니다. 설명 데코레이터와 동일한 Description 속성을 포함할 수 있습니다.
minLength 배열, 문자열 int 문자열 및 배열 매개 변수의 최소 길이입니다. 해당 값이 포함되어 있습니다.
minValue int int 정수 매개 변수의 최솟값입니다. 해당 값이 포함되어 있습니다.
secure 문자열, 개체 없음 매개 변수를 안전하다고 표시합니다. 보안 매개 변수의 값은 배포 기록에 저장되지 않으며 기록되지 않습니다. 자세한 내용은 보안 문자열 및 개체를 참조하세요.

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

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

사용 가능한 데코레이터는 다음 섹션에서 설명합니다.

보안 매개 변수

문자열 또는 개체 매개 변수를 보안으로 표시할 수 있습니다. 보안 매개 변수의 값은 배포 기록에 저장되지 않으며 기록되지도 않습니다.

@secure()
param demoPassword string

@secure()
param demoSecretObject object

허용되는 값

매개 변수에 허용되는 값을 정의할 수 있습니다. 배열에 허용되는 값을 제공합니다. 허용되는 값 중 하나가 아닌 매개 변수에 값이 전달되면 유효성 검사 중에 배포가 실패합니다.

@allowed([
  'one'
  'two'
])
param demoEnum string

길이 제약 조건

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

다음 예제에서는 두 개의 매개 변수를 선언합니다. 한 가지 매개 변수는 3~24자여야 하는 스토리지 계정 이름에 대한 것입니다. 다른 매개 변수는 1~5개 항목이 있어야 하는 배열입니다.

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

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

정수 제약 조건

정수 매개 변수의 최솟값과 최댓값을 설정할 수 있습니다. 제약 조건 중 하나 또는 둘 모두를 설정할 수 있습니다.

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

Description

제공하는 값을 사용자가 이해할 수 있도록 매개 변수에 대한 설명을 추가합니다. 사용자가 포털을 통해 템플릿을 배포할 때 설명의 텍스트는 해당 매개 변수에 대한 팁으로 자동으로 사용됩니다. 텍스트가 매개 변수 이름에서 유추할 수 있는 것보다 더 많은 정보를 제공하는 경우에만 설명을 추가합니다.

@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 may contain numbers and lowercase letters only.
- 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

VSCode에서 storageAccountName을 통해 커서를 마우스로 이동하면 서식이 지정된 텍스트가 표시됩니다.

Use Markdown-formatted text in VSCode

텍스트의 서식이 잘 지정되어 있는지 확인합니다. 그렇지 않으면 텍스트가 올바르게 렌더링되지 않습니다.

메타데이터

매개 변수에 적용할 사용자 지정 속성이 있는 경우 메타데이터 데코레이터를 추가합니다. 메타데이터 내에서 사용자 지정 이름 및 값을 사용하여 개체를 정의합니다. 메타데이터에 대해 정의하는 개체에는 모든 이름과 형식의 속성이 포함될 수 있습니다.

이 데코레이터를 사용하여 설명에 추가하는 데 적합하지 않은 매개 변수에 대한 정보를 추적할 수 있습니다.

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

매개 변수 사용

매개 변수의 값을 참조하려면 매개 변수 이름을 사용합니다. 다음 예제에서는 키 자격 증명 모음 이름에 매개 변수 값을 사용합니다.

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@2020-06-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
        }
      }
    ]
  }
}

다음 단계