Bicep의 매개 변수

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

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

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

Bicep 파일의 매개 변수는 256개로 제한됩니다. 자세한 내용은 템플릿 제한을 참조하세요.

매개 변수 모범 사례는 매개 변수를 참조하세요.

학습 리소스

단계별 지침을 통해 매개 변수에 대해 알아보려면 매개 변수를 사용하여 재사용 가능한 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 키워드는 .bicepparam 파일에서도 사용됩니다. .bicepparam 파일에서는 Bicep 파일에 정의된 대로 데이터 형식을 지정할 필요가 없습니다.

param <parameter-name> = <value>

자세한 내용은 매개 변수 파일을 참조하세요.

사용자 정의 형식 식은 param 문의 형식 절로 사용될 수 있습니다. 예시:

param storageAccountConfig {
  name: string
  sku: string
}

자세한 내용은 사용자 정의 데이터 형식을 참조하세요.

기본값

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

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'

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

데코레이터	적용 대상	인수	설명
allowed	all	배열	매개 변수에 허용되는 값입니다. 해당 데코레이터를 사용하여 사용자가 올바른 값을 제공하는지 확인합니다.
description	all	string	매개 변수를 사용하는 방법을 설명하는 텍스트입니다. 포털을 통해 사용자에게 설명이 표시됩니다.
maxLength	배열, 문자열	int	문자열 및 배열 매개 변수의 최대 길이입니다. 해당 값이 포함되어 있습니다.
maxValue	int	int	정수 매개 변수의 최댓값입니다. 해당 값이 포함되어 있습니다.
metadata	all	개체	매개 변수에 적용할 사용자 지정 속성입니다. 설명 데코레이터와 동일한 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('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

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

텍스트가 적절한 Markdown 서식을 따르는지 확인합니다. 그렇지 않으면 렌더링 시 올바르게 표시되지 않을 수 있습니다.

메타데이터

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

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

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

다른 데코레이터와 충돌하는 속성이 있는 @metadata() 데코레이터를 제공하면 해당 데코레이터는 항상 @metadata() 데코레이터의 모든 항목보다 우선합니다. 따라서 @metadata() 값 내에서 충돌하는 속성은 중복되며 바뀝니다. 자세한 내용은 충돌하는 메타데이터 없음을 참조하세요.

매개 변수 사용

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

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
        }
      }
    ]
  }
}

다음 단계

• 매개 변수에 사용할 수 있는 속성에 대한 자세한 내용은 Bicep 파일의 구조 및 구문 이해를 참조하세요.
• 매개 변수 값을 파일로 전달하는 방법에 대한 자세한 내용은 Bicep 매개 변수 파일 만들기를 참조하세요.
• 배포 시 매개 변수 값을 제공하는 방법에 대한 자세한 내용은 Azure CLI 배포 및 Azure PowerShell 배포를 참조하세요.