Bicep 대한 리소스 함수

이 문서에서는 리소스 값을 가져오기 위한 Bicep 함수에 대해 설명합니다.

현재 배포에서 값을 가져오려면 배포 값 함수를 참조하세요.

네임스페이스 this

네임스페이스는 this 리소스 정의 내에서 런타임 자원 상태 탐색을 위한 함수를 제공합니다. 이 기능들은 템플릿이 환경에 이미 리소스가 존재하는지 여부에 따라 구성을 조정할 수 있게 해줍니다.

  • this.exists(): 자원이 현재 존재하는지 나타내는 불 값을 반환합니다.
  • this.existingResource(): 자원이 존재하면 객체 표현을 반환하고, 존재하지 않으면 null을 반환합니다.

존재하다

this.exists()

자원이 현재 Azure에 존재하는지 나타내는 불 값을 반환합니다. 이 기능은 배포 중에 평가되며, 별도의 기존 자원 선언 없이 조건부 논리를 처리하기 위해 리소스 속성 할당 내에서 사용하도록 설계되었습니다.

네임스페이스: 이

예시

resource stg 'Microsoft.Storage/storageAccounts@2026-04-01' = {
  name: 'mystorageaccount'
  location: 'eastus'
  sku: {
    name: 'Standard_LRS'
  }
  kind:  'StorageV2'
  properties:{
    accessTier: this.exists() ? this.existingResource()!.properties.accessTier : 'Cold'
  }
}

existingResource

this.existingResource()

자원이 존재하는지, null 없으면 객체 표현을 반환합니다. 이 함수는 와 this.exists()짝을 이룹니다. 간단한 불리언을 반환하는 반면 exists() , 실제 existingResource() 리소스 객체를 반환합니다. null-forgiving operator(!)나 safe navigation operator(.?)를 사용하면 중첩된 속성에 안전하게 접근할 수 있습니다.

네임스페이스: 이

예시

resource stg 'Microsoft.Storage/storageAccounts@2026-04-01' = {
  name: 'mystorageaccount'
  location: 'eastus'
  sku: {
    name: 'Standard_LRS'  }
  kind:  'StorageV2'
  properties:{
    accessTier: this.existingResource().?properties.accessTier ?? 'Cold'
  }
}

extensionResourceId

extensionResourceId(resourceId, resourceType, resourceName1, [resourceName2], ...)

확장 리소스에 대한 리소스 ID를 반환합니다. 확장 리소스는 다른 리소스의 기능을 추가하기 위해 적용하는 리소스 유형입니다.

네임스페이스: az.

첫 번째 인자는 확장 자원이 적용되는 리소스의 완전 자격 있는 자원 ID여야 합니다. 이 요구사항은 구독이나 리소스 그룹과 같은 하위 범위에서 테넌트 레벨 자원을 배포할 때 특히 중요합니다. 테넌트 범위에서 해결된 값이 배포가 하위 범위에서 시작될 때 실패할 수 있습니다.

Bicep 파일에서 이 extensionResourceId 기능을 사용할 수 있지만, 보통은 꼭 필요하지 않습니다. 대신 리소스에 대한 기호 이름을 사용하고 id 속성에 액세스합니다. 속성은 id 완전 자격을 갖춘 자원 ID를 반환합니다.

이 함수에서 반환되는 리소스 ID의 기본 형식은 다음과 같습니다.

{scope}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

범위 세그먼트는 확장되는 리소스에 따라 달라집니다.

확장 리소스를 리소스에 적용하면, 리소스 ID는 다음과 같은 형식으로 반환됩니다:

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{baseResourceProviderNamespace}/{baseResourceType}/{baseResourceName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

확장 리소스를 리소스 그룹에 적용할 때 형식은 다음과 같습니다:

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

확장 자원을 구독에 적용할 때 형식은 다음과 같습니다:

/subscriptions/{subscriptionId}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

확장 자원을 관리 그룹에 적용할 때 형식은 다음과 같습니다:

/providers/Microsoft.Management/managementGroups/{managementGroupName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

관리 그룹에 배포된 사용자 지정 정책은 확장 리소스로 구현됩니다. 정책을 만들고 할당하려면 다음 Bicep 파일을 관리 그룹에 배포합니다.

targetScope = 'managementGroup'

@description('An array of the allowed locations, all other locations will be denied by the created policy.')
param allowedLocations array = [
  'australiaeast'
  'australiasoutheast'
  'australiacentral'
]

resource policyDefinition 'Microsoft.Authorization/policyDefinitions@2025-03-01' = {
  name: 'locationRestriction'
  properties: {
    policyType: 'Custom'
    mode: 'All'
    parameters: {}
    policyRule: {
      if: {
        not: {
          field: 'location'
          in: allowedLocations
        }
      }
      then: {
        effect: 'deny'
      }
    }
  }
}

resource policyAssignment 'Microsoft.Authorization/policyAssignments@2025-03-01' = {
  name: 'locationAssignment'
  properties: {
    policyDefinitionId: policyDefinition.id
  }
}

기본 제공 정책 정의는 테넌트 수준 리소스입니다. 기본 제공 정책 정의 배포에 대한 예제는 tenantResourceId를 참조하세요.

getSecret

keyVaultName.getSecret(secretName)

Azure Key Vault 비밀을 반환합니다. 이 함수를 사용하여 Bicep 모듈의 보안 문자열 매개 변수에 비밀을 전달합니다.

참고 항목

파일 내 az.getSecret(subscriptionId, resourceGroupName, keyVaultName, secretName, secretVersion) 기능을 사용 .bicepparam 해 키 금고 비밀을 가져오세요. 자세한 내용은 getSecret을 참조하세요.

모듈의 getSecret 섹션 내에서만 params 함수를 사용할 수 있습니다. Microsoft.KeyVault/vaults 리소스에서만 사용할 수 있습니다.

module sql './sql.bicep' = {
  name: 'deploySQL'
  params: {
    adminPassword: keyVault.getSecret('vmAdminPassword')
  }
}

Bicep 파일의 다른 부분에서 이 함수를 사용하려고 하면 오류가 발생합니다. 매개 변수 섹션에서 사용되는 경우에도 문자열 보간과 함께 이 함수를 사용하는 경우에도 오류가 발생합니다.

이 함수는 데코레이터가 포함된 @secure() 모듈 파라미터에만 사용하세요.

Key Vault에는 enabledForTemplateDeployment로 설정된 true가 있어야 합니다. Bicep 파일을 배포하는 사용자는 비밀에 액세스할 수 있어야 합니다. 자세한 내용은 Azure Key Vault 사용하여 Bicep 배포 중 보안 매개 변수 값 전달 참조하세요.

함수가 리소스 종류와 함께 사용되기 때문에 네임스페이스 한정자가 필요하지 않습니다.

매개 변수

매개 변수 필수 유형 설명
비밀 이름 예 문자열 키 자격 증명 모음에 저장된 비밀의 이름입니다.

반환 값

비밀 이름의 비밀 값입니다.

예시

다음 Bicep 파일이 모듈로 사용됩니다. adminPassword 데코레이터로 정의된 @secure() 매개 변수가 있습니다.

param sqlServerName string
param adminLogin string

@secure()
param adminPassword string

resource sqlServer 'Microsoft.Sql/servers@2024-11-01-preview' = {
  ...
}

다음 Bicep 파일은 이전 Bicep 파일을 모듈로 사용합니다. Bicep 파일은 기존 키 자격 증명 모음을 참조하고 getSecret 함수를 호출하여 키 자격 증명 모음 비밀을 검색한 다음 이 값을 매개 변수로 모듈에 전달합니다.

param sqlServerName string
param adminLogin string

param subscriptionId string
param kvResourceGroup string
param kvName string

resource keyVault 'Microsoft.KeyVault/vaults@2025-05-01' existing = {
  name: kvName
  scope: resourceGroup(subscriptionId, kvResourceGroup )
}

module sql './sql.bicep' = {
  name: 'deploySQL'
  params: {
    sqlServerName: sqlServerName
    adminLogin: adminLogin
    adminPassword: keyVault.getSecret('vmAdminPassword')
  }
}

목록*

resourceName.list([apiVersion], [functionValues])

list로 시작하는 작업을 통해 모든 리소스 종류에 대한 목록 함수를 호출할 수 있습니다. 일반적으로 사용되는 일부 함수는 list, listKeys, listKeyValue 및 listSecrets입니다.

이 함수의 구문은 목록 작업의 이름에 따라 다릅니다. 또한 반환된 값은 연산에 따라 달라집니다. Bicep 현재 list* 함수에 대한 완료 및 유효성 검사를 지원하지 않습니다.

Bicep CLI 버전 0.4.X 이상에서는 accessor 연산자 사용하여 목록 함수를 호출합니다. 예: storageAccount.listKeys().

함수가 리소스 종류와 함께 사용되기 때문에 네임스페이스 한정자가 필요하지 않습니다.

매개 변수

매개 변수 필수 유형 설명
API버전 아니요 문자열 이 매개 변수를 제공하지 않으면 리소스에 대한 API 버전이 사용됩니다. 함수를 특정 버전으로 실행해야 하는 경우에만 사용자 지정 API 버전을 제공합니다. yyyy-mm-dd 형식을 사용합니다.
functionValues 아니요 개체 함수에 대한 값이 있는 개체입니다. 스토리지 계정에서 listAccountSas와 같이 매개 변수 값이 있는 개체 수신을 지원하는 함수에 대해서만 이 개체를 제공합니다. 함수 값을 전달하는 예제가 이 문서에 나와 있습니다.

올바른 용도

리소스 정의의 속성에 있는 함수들을 list 사용하세요. Bicep 파일의 섹션에서 list 민감한 정보를 노출하는 함수는 사용하지 outputs 마세요. 출력 값은 배포 기록에 저장되며, 악의적인 사용자가 이를 가져올 수 있습니다.

list가 있는 함수를 사용할 때, 표현식이 리소스 속성에 할당되어 있기 때문에 사용할 input 수 있습니다. 함수를 해결하기 전에 count 카운트를 결정해야 하므로 사용할 수 없습니다list.

조건부로 배포된 리소스에서 list 함수를 사용하는 경우 리소스가 배포되지 않은 경우에도 함수가 평가됩니다. list 함수가 존재하지 않는 리소스를 참조하면 오류가 발생합니다. 조건식 ?: 연산자를 사용하여 리소스가 배포될 때만 함수가 평가되도록 합니다.

린터 규칙은 use-recognized-resource-type 인식되지 않거나 유효하지 않은 리소스 유형을 사용하는 참조된 리소스를 플래그합니다.

반환 값

반환된 개체는 사용하는 list 함수에 따라 다릅니다. 예를 들어, 스토리지 계정의 함수는 listKeys 다음과 같은 형식을 반환합니다:

{
  "keys": [
    {
      "keyName": "key1",
      "permissions": "Full",
      "value": "{value}"
    },
    {
      "keyName": "key2",
      "permissions": "Full",
      "value": "{value}"
    }
  ]
}

다른 list 함수는 반환 형식이 다릅니다. 함수의 형식을 보려면 예시 Bicep 파일에 표시된 섹션에 outputs 포함하세요.

목록 예제

다음 예에서는 스토리지 계정을 배포한 다음 해당 스토리지 계정에서 listKeys를 호출합니다. 키는 배포 스크립트 값을 설정할 때 사용됩니다.

resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: 'dscript${uniqueString(resourceGroup().id)}'
  location: location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

resource dScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'scriptWithStorage'
  location: location
  ...
  properties: {
    azCliVersion: '2.0.80'
    storageAccountSettings: {
      storageAccountName: storageAccount.name
      storageAccountKey: storageAccount.listKeys().keys[0].value
    }
    ...
  }
}

다음 예는 매개 변수를 사용하는 list 함수를 보여 줍니다. 이 경우 함수는 listAccountSas입니다. 만료 시간 동안 개체를 전달합니다. 만료 시간은 미래 시간이어야 합니다.

param accountSasProperties object {
  default: {
    signedServices: 'b'
    signedPermission: 'r'
    signedExpiry: '2020-08-20T11:00:00Z'
    signedResourceTypes: 's'
  }
}
...
sasToken: storageAccount.listAccountSas('2021-04-01', accountSasProperties).accountSasToken

구현

다음 표는 함수의 list* 가능한 활용 방식을 보여줍니다.

리소스 종류 함수 이름
Microsoft. Addons/supportProviders listsupportplaninfo
Microsoft. AnalysisServices/servers listGatewayStatus
Microsoft. ApiManagement/service/authorizationServers listSecrets
Microsoft. ApiManagement/service/gateways listKeys
Microsoft. ApiManagement/service/identityProviders listSecrets
Microsoft. ApiManagement/service/namedValues listValue
Microsoft. ApiManagement/service/openidConnectProviders listSecrets
Microsoft. ApiManagement/service/subscriptions listSecrets
Microsoft. AppConfiguration/configurationStores ListKeys
Microsoft. AppPlatform/Spring listTestKeys
Microsoft. Automation/automationAccounts listKeys
Microsoft. Batch/batchAccounts listkeys
Microsoft. BatchAI/작업 영역/실험/작업 listoutputfiles
Microsoft. BotService/botServices/channels listChannelWithKeys
Microsoft. Cache/redis listKeys
Microsoft. CognitiveServices/accounts listKeys
Microsoft. ContainerRegistry/registries listCredentials
Microsoft. ContainerRegistry/registries listUsages
Microsoft. ContainerRegistry/registries/agentpools listQueueStatus
Microsoft. ContainerRegistry/registries/buildTasks listSourceRepositoryProperties
Microsoft. ContainerRegistry/registries/buildTasks/steps listBuildArguments
Microsoft. ContainerRegistry/registries/taskruns listDetails
Microsoft. ContainerRegistry/registries/webhook listEvents
Microsoft. ContainerRegistry/registries/runs listLogSasUrl
Microsoft. ContainerRegistry/registries/tasks listDetails
Microsoft. ContainerService/managedClusters listClusterAdminCredential
Microsoft. ContainerService/managedClusters listClusterMonitoringUserCredential
Microsoft. ContainerService/managedClusters listClusterUserCredential
Microsoft. ContainerService/managedClusters/accessProfiles listCredential
Microsoft. DataBox/jobs listCredentials
Microsoft. DataFactory/datafactories/게이트웨이 listauthkeys
Microsoft. DataFactory/팩터리/integrationruntimes listauthkeys
Microsoft. DataLakeAnalytics/accounts/storageAccounts/Containers listSasTokens
Microsoft. DataShare/accounts/shares listSynchronizations
Microsoft. DataShare/accounts/shareSubscriptions listSourceShareSynchronizationSettings
Microsoft. DataShare/accounts/shareSubscriptions listSynchronizationDetails
Microsoft. DataShare/accounts/shareSubscriptions listSynchronizations
Microsoft. Devices/iotHubs listkeys
Microsoft. Devices/iotHubs/iotHubKeys listkeys
Microsoft. Devices/provisioningServices/keys listkeys
Microsoft. Devices/provisioningServices listkeys
Microsoft. DevTestLab/labs ListVhds
Microsoft. DevTestLab/labs/schedules ListApplicable
Microsoft. DevTestLab/labs/users/serviceFabrics ListApplicableSchedules
Microsoft. DevTestLab/labs/virtualMachines ListApplicableSchedules
Microsoft. DocumentDB/databaseAccounts listKeys
Microsoft. DocumentDB/databaseAccounts/notebookWorkspaces listConnectionInfo
Microsoft. DomainRegistration listDomainRecommendations
Microsoft. DomainRegistration/topLevelDomains listAgreements
Microsoft. EventGrid/domains listKeys
Microsoft. EventGrid/topics listKeys
Microsoft. EventHub/namespaces/authorizationRules listkeys
Microsoft. EventHub/namespaces/disasterRecoveryConfigs/authorizationRules listkeys
Microsoft. EventHub/namespaces/eventhubs/authorizationRules listkeys
Microsoft. ImportExport/jobs listBitLockerKeys
Microsoft. Kusto/클러스터/데이터베이스 ListPrincipals
Microsoft. LabServices/labs/users 목록
Microsoft. LabServices/labs/virtualMachines 목록
Microsoft. Logic/integrationAccounts/agreements listContentCallbackUrl
Microsoft. Logic/integrationAccounts/assemblies listContentCallbackUrl
Microsoft. Logic/integrationAccounts listCallbackUrl
Microsoft. Logic/integrationAccounts listKeyVaultKeys
Microsoft. Logic/integrationAccounts/maps listContentCallbackUrl
Microsoft. Logic/integrationAccounts/partners listContentCallbackUrl
Microsoft. Logic/integrationAccounts/schemas listContentCallbackUrl
Microsoft. 논리/워크플로 listCallbackUrl
Microsoft. 논리/워크플로 listSwagger
Microsoft. 논리/워크플로/실행/작업 listExpressionTraces
Microsoft. 논리/워크플로/실행/작업/반복 listExpressionTraces
Microsoft. 논리/워크플로/트리거 listCallbackUrl
Microsoft. 논리/워크플로/버전/트리거 listCallbackUrl
Microsoft. MachineLearning/webServices listkeys
Microsoft. MachineLearning/Workspaces listworkspacekeys
Microsoft. MachineLearningServices/workspaces/computes listKeys
Microsoft. MachineLearningServices/workspaces/computes listNodes
Microsoft. MachineLearningServices/workspaces listKeys
Microsoft. 지도/계정 listKeys
Microsoft. 미디어/미디어 서비스/자산 listContainerSas
Microsoft. 미디어/미디어 서비스/자산 listStreamingLocators
Microsoft. Media/mediaservices/streamingLocators listContentKeys
Microsoft. Media/mediaservices/streamingLocators listPaths
Microsoft. Network/applicationSecurityGroups listIpConfigurations
Microsoft. NotificationHubs/Namespaces/authorizationRules listkeys
Microsoft. NotificationHubs/Namespaces/NotificationHubs/authorizationRules listkeys
Microsoft. OperationalInsights/workspaces 목록
Microsoft. OperationalInsights/workspaces listKeys
Microsoft. PolicyInsights/수정 listDeployments
Microsoft. RedHatOpenShift/openShiftClusters listCredentials
Microsoft. Relay/namespaces/disasterRecoveryConfigs/authorizationRules listkeys
Microsoft. Search/searchServices listAdminKeys
Microsoft. Search/searchServices listQueryKeys
Microsoft. SignalRService/SignalR listkeys
Microsoft. Storage/storageAccounts listAccountSas
Microsoft. Storage/storageAccounts listkeys
Microsoft. Storage/storageAccounts listServiceSas
Microsoft. StorSimple/관리자/디바이스 listFailoverSets
Microsoft. StorSimple/관리자/디바이스 listFailoverTargets
Microsoft. StorSimple/관리자 listActivationKey
Microsoft. StorSimple/관리자 listPublicEncryptionKey
Microsoft. Synapse/workspaces/integrationRuntimes listAuthKeys
Microsoft. Web/connectionGateways ListStatus
microsoft.web/connections listconsentlinks
Microsoft. Web/customApis listWsdlInterfaces
microsoft.web/locations listwsdlinterfaces
microsoft.web/apimanagementaccounts/api/connections listconnectionkeys
microsoft.web/apimanagementaccounts/api/connections listsecrets
microsoft.web/sites/backups 목록
Microsoft. 웹/사이트/구성 목록
microsoft.web/sites/functions listkeys
microsoft.web/sites/functions listsecrets
microsoft.web/sites/hybridconnectionnamespaces/relays listkeys
microsoft.web/sites listsyncfunctiontriggerstatus
microsoft.web/sites/slots/functions listsecrets
microsoft.web/sites/slots/backups 목록
Microsoft. 웹/사이트/슬롯/구성 목록
microsoft.web/sites/slots/functions listsecrets

어떤 자원 유형이 리스트 연산을 가지고 있는지 결정하려면 다음 옵션을 사용하세요:

  • 리소스 공급자에 대한 REST API 작업을 보고 list 작업을 찾습니다. 예를 들어 스토리지 계정에는 listKeys 작업이 있습니다.

  • Get-AzProviderOperation PowerShell cmdlet을 사용합니다. 다음 예제에서는 스토리지 계정에 대한 모든 list 작업을 가져옵니다.

    Get-AzProviderOperation -OperationSearchString "Microsoft.Storage/*" | where {$_.Operation -like "*list*"} | FT Operation

  • 다음 Azure CLI 명령을 사용하여 목록 작업만 필터링합니다.

    az provider operation show --namespace Microsoft.Storage --query "resourceTypes[?name=='storageAccounts'].operations[].name | [?contains(@, 'list')]"

managementGroupResourceId

managementGroupResourceId(resourceType, resourceName1, [resourceName2], ...)

관리 그룹 수준에서 배포된 리소스의 고유 식별자를 반환합니다.

네임스페이스: az.

managementGroupResourceId 이 기능은 Bicep 파일에서 제공되지만, 보통은 필요하지 않습니다. 대신 리소스에 대한 기호 이름을 사용하고 id 속성에 액세스합니다.

식별자는 다음 형식으로 반환됩니다.

/providers/Microsoft.Management/managementGroups/{managementGroupName}/providers/{resourceType}/{resourceName}

설명

이 함수를 사용하여 자원 그룹이 아닌 관리 그룹에 배포 된 자원의 자원 ID를 얻으세요. 반환된 ID는 구독 ID 및 리소스 그룹 값을 포함하지 않는다는 점에서 resourceId 함수에서 반환된 값과 다릅니다.

managementGroupResourceID 예

다음 템플릿은 정책 정의를 만들고 할당합니다. managementGroupResourceId 함수를 사용하여 정책 정의를 위한 리소스 ID를 가져옵니다.

targetScope = 'managementGroup'

@description('Target Management Group')
param targetMG string

@description('An array of the allowed locations, all other locations will be denied by the created policy.')
param allowedLocations array = [
  'australiaeast'
  'australiasoutheast'
  'australiacentral'
]

var mgScope = tenantResourceId('Microsoft.Management/managementGroups', targetMG)
var policyDefinitionName = 'LocationRestriction'

resource policyDefinition 'Microsoft.Authorization/policyDefinitions@2025-03-01' = {
  name: policyDefinitionName
  properties: {
    policyType: 'Custom'
    mode: 'All'
    parameters: {}
    policyRule: {
      if: {
        not: {
          field: 'location'
          in: allowedLocations
        }
      }
      then: {
        effect: 'deny'
      }
    }
  }
}

resource location_lock 'Microsoft.Authorization/policyAssignments@2025-03-01' = {
  name: 'location-lock'
  properties: {
    scope: mgScope
    policyDefinitionId: managementGroupResourceId('Microsoft.Authorization/policyDefinitions', policyDefinitionName)
  }
  dependsOn: [
    policyDefinition
  ]
}

pickZones

pickZones(providerNamespace, resourceType, location, [numberOfZones], [offset])

리소스 종류가 지역에 대한 영역을 지원하는지 여부를 결정합니다. 이 함수는 영역 리소스만 지원합니다. 영역 중복 서비스는 빈 배열을 반환합니다. 자세한 내용은 가용성 영역을 지원하는 Azure 서비스 참조하세요.

네임스페이스: az.

매개 변수

매개 변수 필수 유형 설명
provider네임스페이스 예 문자열 영역 지원을 확인할 리소스 종류에 대한 리소스 공급자 네임스페이스입니다.
리소스 유형 예 문자열 영역 지원을 확인할 리소스 종류입니다.
위치 예 문자열 영역 지원을 확인할 지역입니다.
numberOfZones 아니요 정수 반환할 논리적 영역의 수입니다. 기본값은 1입니다. 숫자는 1~3 사이의 양수여야 합니다. 단일 영역 리소스에 대해 1을 사용합니다. 다중 영역 리소스의 경우 값은 지원되는 영역 수보다 적거나 같아야 합니다.
상쇄 아니요 정수 시작 논리적 영역의 오프셋입니다. offset과 numberOfZones의 합이 지원되는 영역의 수를 초과하는 경우 함수에서 오류를 반환합니다.

반환 값

지원되는 영역이 있는 배열입니다. 기본 값 offsetnumberOfZones과 를 사용할 때, 존을 지원하는 자원 유형과 영역은 다음과 같은 배열을 반환합니다:

[
  "1"
]

매개변수를 numberOfZones 3으로 설정하면 다음과 같은 결과가 나옵니다:

[
  "1",
  "2",
  "3"
]

자원 유형이나 영역이 존을 지원하지 않을 경우, 함수는 빈 배열을 반환합니다.

[
]

설명

Azure 가용성 영역 두 가지 범주로 나뉩니다 - 존 중복과 구역 중복. 해당 기능을 사용하여 pickZones 존 자원의 가용성 구역을 반환하세요. ZRS(영역 중복 서비스)의 경우 함수는 빈 배열을 반환합니다. 영역 리소스에는 일반적으로 리소스 정의의 최상위 수준에 zones 속성이 있습니다. 가용성 영역에 대한 지원 범주를 확인하려면 가용성 영역을 지원하는 Azure 서비스 참조하세요.

지정된 Azure 지역 또는 위치가 가용성 영역을 지원하는지 확인하려면 pickZones 같은 영역 리소스 유형을 사용하여 Microsoft.Network/publicIPAddresses 함수를 호출합니다. 응답이 비어 있지 않은 경우 해당 지역은 가용성 영역을 지원합니다.

pickZones 예제

다음 Bicep 파일은 pickZones 함수를 사용하기 위한 세 가지 결과를 보여줍니다.

output supported array = pickZones('Microsoft.Compute', 'virtualMachines', 'westus2')
output notSupportedRegion array = pickZones('Microsoft.Compute', 'virtualMachines', 'westus')
output notSupportedType array = pickZones('Microsoft.Cdn', 'profiles', 'westus2')

이전 예제의 출력은 3개의 배열을 반환합니다.

이름 유형 값
지원 배열 [ "1" ]
notSupportedRegion 배열 []
notSupportedType 배열 []

응답을 pickZones 통해 존에 null을 제공할지 아니면 가상 머신을 다른 존에 할당할지 결정하세요.

제공자

Bicep에서는 제공자 기능이 더 이상 사용되지 않습니다. 사용하지 마세요. 이 함수를 사용해 리소스 제공자의 API 버전을 얻었다면, Bicep 파일에 특정 API 버전을 제공하세요. 버전 간에 속성이 변경된 경우 동적으로 반환된 API 버전을 사용하면 템플릿이 손상될 수 있습니다.

공급자 작업은 REST API를 통해 계속 사용할 수 있습니다. Bicep 파일 외부에서도 리소스 제공자에 대한 정보를 얻을 수 있습니다.

네임스페이스: az.

참조

reference(resourceName or resourceIdentifier, [apiVersion], ['Full'])

리소스의 런타임 상태를 나타내는 객체를 반환합니다. 함수의 reference 출력과 동작은 각 리소스 제공자(RP)가 PUT 및 GET 응답을 어떻게 구현하는지에 크게 의존합니다.

네임스페이스: az.

Bicep 파일은 참조 기능에 접근할 수 있게 해주지만, 보통은 꼭 필요하지 않습니다. 대신 자원의 상징 이름을 사용하세요. 참조 함수는 리소스의 객체 내 properties 에서만 사용할 수 있습니다. 최상위 속성 namelocation인 나 . 같은 경우에는 사용할 수 없습니다. 같은 규칙은 일반적으로 상징 이름을 사용하는 참조에도 적용됩니다. 하지만 와 같은 name속성의 경우, 참조 함수를 사용하지 않고도 템플릿을 생성할 수 있습니다. 자원 이름에 대해 충분히 알고 있어서 직접 이름을 발산할 수 있습니다. 이들은 컴파일 타임 속성입니다. Bicep 유효성 검사는 기호 이름의 잘못된 사용을 식별할 수 있습니다.

다음 예제에서는 저장소 계정을 배포합니다. 처음 두 개의 출력은 동일한 결과를 제공합니다.

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

resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: storageAccountName
  location: location
  kind: 'Storage'
  sku: {
    name: 'Standard_LRS'
  }
}

output storageObjectSymbolic object = storageAccount.properties
output storageObjectReference object = reference('storageAccount')
output storageName string = storageAccount.name
output storageLocation string = storageAccount.location

템플릿에 배포하지 않은 기존 리소스에서 속성을 얻으려면, 키워드를 existing 사용하세요:

param storageAccountName string

resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' existing = {
  name: storageAccountName
}

// use later in template as often as needed
output blobAddress string = storageAccount.properties.primaryEndpoints.blob

부모 리소스 내에 중첩된 리소스를 참조하려면 중첩된 액세스 서 (::)를 사용하세요. 부모 리소스 외부에서 중첩된 리소스에 액세스하는 경우에만 이 구문을 사용합니다.

vNet1::subnet1.properties.addressPrefix

존재하지 않는 리소스를 참조하려고 하면 NotFound 오류가 발생하고 배포에 실패합니다. 린터 규칙은 use-recognized-resource-type 인식되지 않거나 유효하지 않은 리소스 유형을 사용하는 참조된 리소스를 플래그합니다.

리소스ID

resourceId([subscriptionId], [resourceGroupName], resourceType, resourceName1, [resourceName2], ...)

리소스의 고유 식별자를 반환합니다.

네임스페이스: az.

resourceId 이 기능은 Bicep 파일에서 제공되지만, 보통은 필요하지 않습니다. 대신 리소스에 대한 기호 이름을 사용하고 id 속성에 액세스합니다.

자원 이름이 모호하거나 동일한 Bicep 파일 내에 프로비저빙되지 않을 때 이 기능을 사용하세요. 반환된 식별자의 형식은 리소스 그룹, 구독, 관리 그룹 또는 테넌트 중에서 테넌트가 어떤 범위에서 발생하는지에 따라 달라집니다.

예시:

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

resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' = {
  name: storageAccountName
  location: location
  kind: 'Storage'
  sku: {
    name: 'Standard_LRS'
  }
}

output storageID string = storageAccount.id

Bicep 파일에 배포되지 않은 리소스의 리소스 ID를 가져오려면 기존 키워드를 사용합니다.

param storageAccountName string

resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' existing = {
  name: storageAccountName
}

output storageID string = storageAccount.id

자세한 내용은 JSON 템플릿 resourceId 함수를 참조하세요.

역할 정의

roleDefinitions(roleName)

지정된 역할 정의에 대한 정보(포함 id 및 .)를 반환합니다 roleDefinitionId. RBAC 역할 할당을 Azure 이름 기반 도우미입니다. 커스텀 또는 내장 역할 정의(예: Contributor, Reader 등)의 GUID를 하드코딩할 필요 없이, 커스텀 또는 내장 역할의 표시 이름을 제공하고, 해당 함수가 배포 시점에 해당 역할 정의 정보를 해결해 줍니다.

네임스페이스: az.

매개 변수

매개 변수 필수 유형 설명
roleName 예 문자열 역할 정의의 표시 이름입니다.

반환 값

역할 정의를 나타내는 개체입니다(포함 id 및 roleDefinitionId.).

예시

다음 Bicep 코드는 배포 범위에서 역할 정의를 이름으로 해석하여 지정된 주체에게 Storage Blob Data Reader 내장 역할을 부여하는 결정론적 Azure RBAC 역할 할당을 생성합니다.

@description('Specifies the role definition ID used in the role assignment.')
param roleDefinitionName string = 'Storage Blob Data Reader'

@description('Specifies the principal ID assigned to the role.')
param principalId string

var roleAssignmentName= guid(principalId, roleDefinitionName, resourceGroup().id)
resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: roleAssignmentName
  properties: {
    roleDefinitionId: roleDefinitions(roleDefinitionName).id
    principalId: principalId
  }
}

자세한 내용은 JSON 템플릿 resourceId 함수를 참조하세요.

subscriptionResourceId

subscriptionResourceId([subscriptionId], resourceType, resourceName1, [resourceName2], ...)

구독 수준에서 배포된 리소스의 고유 식별자를 반환합니다.

네임스페이스: az.

subscriptionResourceId 함수는 Bicep 파일에서 사용할 수 있지만 일반적으로 필요하지 않습니다. 대신 리소스에 대한 기호 이름을 사용하고 id 속성에 액세스합니다.

식별자는 다음 형식으로 반환됩니다.

/subscriptions/{subscriptionId}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}

설명

이 기능을 사용해 자원 그룹이 아닌 구독에 배포 된 리소스의 자원 ID를 얻으세요. 반환되는 ID는 리소스 그룹 값을 포함하지 않으므로 resourceId 함수에서 반환하는 값과 다릅니다.

subscriptionResourceId 예제

다음 Bicep 파일은 기본 제공 역할을 할당합니다. 리소스 그룹 또는 구독에 배포할 수 있습니다. subscriptionResourceId 함수를 사용하여 기본 제공 역할의 리소스 ID를 가져옵니다.

@description('Principal Id')
param principalId string

@allowed([
  'Owner'
  'Contributor'
  'Reader'
])
@description('Built-in role to assign')
param builtInRoleType string

var roleDefinitionId = {
  Owner: {
    id: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8e3af657-a8ff-443c-a75c-2fe8c4bcb635')
  }
  Contributor: {
    id: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b24988ac-6180-42a0-ab88-20f7382dd24c')
  }
  Reader: {
    id: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'acdd72a7-3385-48ef-bd42-f606fba81ae7')
  }
}

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(resourceGroup().id, principalId, roleDefinitionId[builtInRoleType].id)
  properties: {
    roleDefinitionId: roleDefinitionId[builtInRoleType].id
    principalId: principalId
  }
}

tenantResourceId

tenantResourceId(resourceType, resourceName1, [resourceName2], ...)

테넌트 수준에서 배포된 리소스의 고유 식별자를 반환합니다.

네임스페이스: az.

tenantResourceId 함수는 Bicep 파일에서 사용할 수 있지만 일반적으로 필요하지 않습니다. 대신 리소스에 대한 기호 이름을 사용하고 id 속성에 액세스합니다.

식별자는 다음 형식으로 반환됩니다.

/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}

기본 제공 정책 정의는 테넌트 수준 리소스입니다. 기본 제공 정책 정의를 참조하는 정책 할당을 배포하려면 tenantResourceId 함수를 사용합니다.

@description('Specifies the ID of the policy definition or policy set definition being assigned.')
param policyDefinitionID string = '0a914e76-4921-4c19-b460-a2d36003525a'

@description('Specifies the name of the policy assignment, can be used defined or an idempotent name as the defaultValue provides.')
param policyAssignmentName string = guid(policyDefinitionID, resourceGroup().name)

resource policyAssignment 'Microsoft.Authorization/policyAssignments@2025-03-01' = {
  name: policyAssignmentName
  properties: {
    scope: subscriptionResourceId('Microsoft.Resources/resourceGroups', resourceGroup().name)
    policyDefinitionId: tenantResourceId('Microsoft.Authorization/policyDefinitions', policyDefinitionID)
  }
}

toLogicalZone

toLogicalZone(subscriptionId, location, physicalZone)

특정 Azure 지역 내 지정된 구독에 해당하는 논리적 가용성 존(예: 1, 2, , 또는 3)을 반환합니다.

네임스페이스: az

매개 변수

매개 변수 필수 유형 설명
구독ID 예 문자열 Azure 구독의 ID는 .과 같습니다12345678-1234-1234-1234-1234567890ab.
위치 예 문자열 가용성 존을 지원하는 Azure 지역, 예를 들어 westus2.
physicalZone 예 문자열 물리적 가용성 영역 식별자(예: 데이터 센터별 식별자) westus2-az1입니다.

반환 값

지정된 지역 및 구독의 지정된 물리적 영역에 해당하는 논리 가용성 영역(예 1: , 2또는 3)을 나타내는 문자열입니다. 물리적 영역이 유효하지 않거나 지원되지 않을 경우, 함수는 빈 문자열('')을 반환합니다.

설명

  • 이 함수는 toLogicalZone 지정된 지역의 구독 영역 구성에 따라 논리 영역 매핑을 검색합니다.
  • 논리 영역은 Azure 서비스에서 일관된 영역 할당을 보장하기 위해 리소스 구성에 사용되는 표준화된 식별자(예: 1, 2, 3)입니다.
  • 물리적 존 식별자는 지역별로 다르며 구독마다 다를 수 있습니다. 이 매핑을 toPhysicalZone 되돌리려면 함수를 사용합니다.
  • 이 함수를 사용하려면 지역에서 가용성 영역을 지원해야 합니다. 지원되는 지역 목록은 가용성 영역을 지원하는 Azure 서비스 참조하세요.
  • 실제 영역이 없거나 구독에 대해 매핑되지 않은 경우 함수는 빈 문자열을 반환합니다.
  • 이 함수는 템플릿의 논리 영역 구성과 물리적 영역 배포를 정렬하는 데 유용하며, 특히 구독 간 또는 다중 지역 시나리오에 유용합니다.

예시

다음 예제에서는 특정 구독에 대한 미국 서부 2의 물리적 영역에 대한 논리 영역을 검색합니다.

param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param physicalZone string = 'westus2-az1'

output logicalZone string = toLogicalZone(subscriptionId, 'westus2', physicalZone)

예상 출력:

이름 유형 값
논리 영역 문자열 1

다음 예제에서는 올바른 논리 영역을 사용하여 가상 머신을 구성하는 데 사용합니다 toLogicalZone .

param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param physicalZone string = 'westus2-az1'
param location string = 'westus2'

var logicalZone = toLogicalZone(subscriptionId, location, physicalZone)

resource vm 'Microsoft.Compute/virtualMachines@2025-04-01' = {
  name: 'myVM'
  location: location
  zones: logicalZone != '' ? [logicalZone] : []
  properties: {
    // VM properties
  }
}

output logicalZone string = logicalZone

예상 출력:

이름 유형 값
논리 영역 문자열 1

toLogicalZones

toLogicalZones(subscriptionId, location, physicalZones)

지정된 Azure 지역의 지정된 구독에 대한 물리적 가용성 영역에 해당하는 논리 가용성 영역(예: 1, 2 또는 3)을 반환합니다. 단일 물리적 영역을 변환하려면 함수를 toLogicalZone 사용합니다.

네임스페이스: az

매개 변수

매개 변수 필수 유형 설명
구독ID 예 문자열 Azure 구독의 ID는 .과 같습니다12345678-1234-1234-1234-1234567890ab.
위치 예 문자열 가용성 존을 지원하는 Azure 지역, 예를 들어 westus2.
physicalZones 예 배열 논리 영역으로 변환할 물리적 영역 이름의 배열입니다(예: 데이터 센터별 식별자(예: westus2-az1, westus2-az2...).

반환 값

제공된 물리적 영역(예 1: , 2또는 3)에 해당하는 논리 영역 이름의 배열입니다. 물리적 영역이 유효하지 않거나 지원되지 않을 경우, 함수는 빈 문자열()''을 반환합니다.

설명

toLogicalZones 함수는 지정된 Azure 구독 및 지역에 해당하는 논리 영역에 물리적 영역 이름을 매핑합니다. 이 매핑은 Azure 지역 내 논리 존을 기반으로 자원을 구성하거나 쿼리할 때 유용합니다. 함수에는 유효한 구독 ID, 지원되는 Azure 위치 및 물리적 영역 이름 배열이 필요합니다. 지정된 위치에 물리적 존이 유효하지 않거나 사용 가능하지 않으면, 해당 존에 대해 빈 문자열을 반환하거나 상황에 따라 오류를 생성할 수 있습니다.

예시

다음 예제에서는 특정 구독에 대한 미국 서부 2의 물리적 영역 목록에 대한 논리 영역을 검색합니다.

param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param physicalZones array = ['westus2-az1', 'westus2-az2', 'westus2-az3']

output logicalZones array = toLogicalZones(subscriptionId, 'westus2', physicalZones)

예상 출력:

이름 유형 값
논리 영역 배열 ["1","2","3"]

toPhysicalZone

toPhysicalZone(subscriptionId, location, logicalZone)

특정 Azure 지역 내 특정 구독에 대한 논리적 가용성 존에 해당하는 데이터 센터별 식별자(예: westus2-az1)를 반환합니다.

네임스페이스: az

매개 변수

매개 변수 필수 유형 설명
구독ID 예 문자열 Azure 구독의 ID는 .과 같습니다12345678-1234-1234-1234-1234567890ab.
위치 예 문자열 가용성 존을 지원하는 Azure 지역, 예를 들어 westus2.
논리 영역 예 문자열 논리적 가용성 구역, 예를 들어 1, 2, 또는 3.

반환 값

물리적 가용성 존 식별자를 나타내는 문자열로, 예: westus2-az1, 해당 지역 및 구독 내에서 지정된 논리 존에 해당합니다. 논리 존이 유효하지 않거나 지원되지 않으면, 함수는 빈 문자열()''을 반환합니다.

설명

  • 이 함수는 toPhysicalZone 지정된 지역의 구독 영역 구성에 따라 실제 영역 매핑을 검색합니다.
  • 물리적 존은 구독마다 다를 수 있는 데이터 센터별 식별자이며, 논리 존(예: 1, 2, 3)은 자원 구성에 따라 표준화되어 있습니다.
  • 함수를 toLogicalZone 사용해 이 매핑을 역전시키고 물리적 영역을 논리적 동등한 영역으로 변환하세요.
  • 이 함수를 사용하려면 지역에서 가용성 영역을 지원해야 합니다. 지원되는 지역 목록은 가용성 영역을 지원하는 Azure 서비스 참조하세요.
  • 논리 영역이 없거나 구독에 매핑되지 않은 경우 함수는 빈 문자열을 반환합니다.
  • 이 기능은 로깅, 감사, 다중 지역 배포에서의 교차 구독 존 정렬과 같이 물리적 존 식별자가 필요한 시나리오에 유용합니다.

예시

다음 예제에서는 특정 구독에 대한 미국 서부 2의 논리 영역에 대한 물리적 영역을 검색합니다.

param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param logicalZone string = '1'

output physicalZone string = toPhysicalZone(subscriptionId, 'westus2', logicalZone)

예상 출력(논리 영역 1 이 다음으로 매핑된 것으로 westus2-az1가정):

이름 유형 값
physicalZone 문자열 westus2-az1

다음 예제에서는 가상 머신 배포에 대한 물리적 영역을 기록하는 데 사용합니다 toPhysicalZone .

param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param logicalZone string = '1'
param location string = 'westus2'

var physicalZone = toPhysicalZone(subscriptionId, location, logicalZone)

resource vm 'Microsoft.Compute/virtualMachines@2025-04-01' = {
  name: 'myVM'
  location: location
  zones: [logicalZone]
  properties: {
    // VM properties
  }
}

output physicalZone string = physicalZone

예상 출력:

이름 유형 값
physicalZone 문자열 westus2-az1

toPhysicalZones

toPhysicalZones(subscriptionId, location, logicalZones)

지정된 Azure 지역의 지정된 구독에 대한 논리적 가용성 영역에 해당하는 물리적 가용성 영역 식별자(예: westus2-az1 같은 데이터 센터별 식별자)를 반환합니다. 단일 논리 영역을 변환하려면 함수를 toPhysicalZone 사용합니다.

네임스페이스: az

매개 변수

매개 변수 필수 유형 설명
구독ID 예 문자열 Azure 구독의 ID는 .과 같습니다12345678-1234-1234-1234-1234567890ab.
위치 예 문자열 가용성 존을 지원하는 Azure 지역, 예를 들어 westus2.
논리 영역 예 문자열[] 물리적 영역으로 변환할 논리 가용성 영역(예1: 또는23)입니다.

반환 값

제공된 논리 영역에 해당하는 물리적 영역 이름(예 westus2-az1: , westus2-az2 )의 배열입니다. 논리 존이 유효하지 않거나 지원되지 않을 경우, 함수는 빈 문자열('')을 반환합니다.

설명

toPhysicalZones 함수는 지정된 Azure 구독 및 지역에 해당하는 물리적 영역에 논리 영역 이름을 매핑합니다. 이 매핑은 Azure 지역 내 특정 물리적 영역에 자원을 배포하거나 구성할 때 유용합니다. 함수에는 유효한 구독 ID, 지원되는 Azure 위치 및 논리 영역 이름 배열이 필요합니다. 지정된 위치에서 논리 존이 유효하지 않거나 사용 불가능하면, 해당 존에 대해 빈 문자열을 반환하거나 상황에 따라 오류를 던질 수 있습니다.

예시

다음 예제에서는 특정 구독에 대한 미국 서부 2의 논리 영역 목록에 대한 물리적 영역을 검색합니다.

param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param logicalZones array = ['1', '2', '3']

output physicalZones array = toPhysicalZones(subscriptionId, 'westus2', logicalZones)

예상 출력(논리 영역이 매핑되고 논리 영역 1 이 매핑되고 논리 영역 westus2-az11 이 다음으로 westus2-az1매핑됩니다3westus2-az3.)

이름 유형 값
physicalZone 배열 ["westus2-az1","westus2-az2","westus2-az3"]

다음 단계

  • 현재 배포에서 값을 가져오려면 배포 값 함수를 참조하세요.
  • 리소스 유형을 만들 때 지정된 횟수를 반복하려면 Bicep 반복 루프를 참조하세요.
  • Last updated on