Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
This article describes the Bicep functions for getting resource values.
To get values from the current deployment, see Deployment value functions.
extensionResourceId
extensionResourceId(resourceId, resourceType, resourceName1, [resourceName2], ...)
Returns the resource ID for an extension resource. An extension resource is a resource type that you apply to another resource to add to its capabilities.
Namespace: az.
You can use the extensionResourceId function in Bicep files, but you typically don't need it. Instead, use the symbolic name for the resource and access the id property.
The basic format of the resource ID returned by this function is:
{scope}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}
The scope segment varies by the resource being extended.
When you apply the extension resource to a resource, the resource ID is returned in the following format:
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{baseResourceProviderNamespace}/{baseResourceType}/{baseResourceName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}
When you apply the extension resource to a resource group, the format is:
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}
When you apply the extension resource to a subscription, the format is:
/subscriptions/{subscriptionId}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}
When you apply the extension resource to a management group, the format is:
/providers/Microsoft.Management/managementGroups/{managementGroupName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}
A custom policy definition deployed to a management group is implemented as an extension resource. To create and assign a policy, deploy the following Bicep file to a management group.
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
}
}
Built-in policy definitions are tenant level resources. For an example of deploying a built-in policy definition, see tenantResourceId.
getSecret
keyVaultName.getSecret(secretName)
Returns a secret from an Azure Key Vault. Use this function to pass a secret to a secure string parameter of a Bicep module.
Note
Use the az.getSecret(subscriptionId, resourceGroupName, keyVaultName, secretName, secretVersion) function in .bicepparam files to retrieve key vault secrets. For more information, see getSecret.
You can only use the getSecret function from within the params section of a module. You can only use it with a Microsoft.KeyVault/vaults resource.
module sql './sql.bicep' = {
name: 'deploySQL'
params: {
adminPassword: keyVault.getSecret('vmAdminPassword')
}
}
You get an error if you attempt to use this function in any other part of the Bicep file. You also get an error if you use this function with string interpolation, even when used in the params section.
Use the function only with a module parameter that has the @secure() decorator.
The key vault must have enabledForTemplateDeployment set to true. The user deploying the Bicep file must have access to the secret. For more information, see Use Azure Key Vault to pass secure parameter value during Bicep deployment.
A namespace qualifier isn't needed because the function is used with a resource type.
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| secretName | Yes | string | The name of the secret stored in a key vault. |
Return value
The secret value for the secret name.
Example
The following Bicep file is used as a module. It has an adminPassword parameter defined with the @secure() decorator.
param sqlServerName string
param adminLogin string
@secure()
param adminPassword string
resource sqlServer 'Microsoft.Sql/servers@2024-11-01-preview' = {
...
}
The following Bicep file consumes the preceding Bicep file as a module. The Bicep file references an existing key vault, and calls the getSecret function to retrieve the key vault secret, and then passes the value as a parameter to the module.
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')
}
}
list*
resourceName.list([apiVersion], [functionValues])
You can call a list function for any resource type with an operation that starts with list. Some common usages are list, listKeys, listKeyValue, and listSecrets.
The syntax for this function varies by the name of the list operation. The returned values also vary by operation. Bicep doesn't currently support completions and validation for list* functions.
With Bicep CLI version 0.4.X or higher, you call the list function by using the accessor operator. For example, storageAccount.listKeys().
A namespace qualifier isn't needed because the function is used with a resource type.
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| apiVersion | No | string | If you don't provide this parameter, the API version for the resource is used. Only provide a custom API version when you need the function to be run with a specific version. Use the format, yyyy-mm-dd. |
| functionValues | No | object | An object that has values for the function. Only provide this object for functions that support receiving an object with parameter values, such as listAccountSas on a storage account. An example of passing function values is shown in this article. |
Valid uses
Use the list functions in the properties of a resource definition. Don't use a list function that exposes sensitive information in the outputs section of a Bicep file. Output values are stored in the deployment history and a malicious user could retrieve them.
When you use a list function with an iterative loop, you can use it for input because the expression is assigned to the resource property. You can't use it with count because the count must be determined before the list function is resolved.
If you use a list function in a resource that is conditionally deployed, the function is evaluated even if the resource isn't deployed. You get an error if the list function refers to a resource that doesn't exist. Use the conditional expression ?: operator to make sure the function is only evaluated when the resource is being deployed.
The use-recognized-resource-type linter rule flags any referenced resource that uses an unrecognized or invalid resource type.
Return value
The returned object varies by the list function you use. For example, the listKeys function for a storage account returns the following format:
{
"keys": [
{
"keyName": "key1",
"permissions": "Full",
"value": "{value}"
},
{
"keyName": "key2",
"permissions": "Full",
"value": "{value}"
}
]
}
Other list functions have different return formats. To see the format of a function, include it in the outputs section as shown in the example Bicep file.
List example
The following example deploys a storage account and then calls listKeys on that storage account. The key is used when setting a value for deployment scripts.
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
}
...
}
}
The next example shows a list function that takes a parameter. In this case, the function is listAccountSas. Pass an object for the expiry time. The expiry time must be in the future.
param accountSasProperties object {
default: {
signedServices: 'b'
signedPermission: 'r'
signedExpiry: '2020-08-20T11:00:00Z'
signedResourceTypes: 's'
}
}
...
sasToken: storageAccount.listAccountSas('2021-04-01', accountSasProperties).accountSasToken
Implementations
The following table shows possible uses of list* functions.
| Resource type | Function name |
|---|---|
| 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/workspaces/experiments/jobs | 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/webhooks | 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/gateways | listauthkeys |
| Microsoft.DataFactory/factories/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/Clusters/Databases | ListPrincipals |
| Microsoft.LabServices/labs/users | list |
| Microsoft.LabServices/labs/virtualMachines | list |
| 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.Logic/workflows | listCallbackUrl |
| Microsoft.Logic/workflows | listSwagger |
| Microsoft.Logic/workflows/runs/actions | listExpressionTraces |
| Microsoft.Logic/workflows/runs/actions/repetitions | listExpressionTraces |
| Microsoft.Logic/workflows/triggers | listCallbackUrl |
| Microsoft.Logic/workflows/versions/triggers | listCallbackUrl |
| Microsoft.MachineLearning/webServices | listkeys |
| Microsoft.MachineLearning/Workspaces | listworkspacekeys |
| Microsoft.MachineLearningServices/workspaces/computes | listKeys |
| Microsoft.MachineLearningServices/workspaces/computes | listNodes |
| Microsoft.MachineLearningServices/workspaces | listKeys |
| Microsoft.Maps/accounts | listKeys |
| Microsoft.Media/mediaservices/assets | listContainerSas |
| Microsoft.Media/mediaservices/assets | 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 | list |
| Microsoft.OperationalInsights/workspaces | listKeys |
| Microsoft.PolicyInsights/remediations | 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/managers/devices | listFailoverSets |
| Microsoft.StorSimple/managers/devices | listFailoverTargets |
| Microsoft.StorSimple/managers | listActivationKey |
| Microsoft.StorSimple/managers | 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/apis/connections | listconnectionkeys |
| microsoft.web/apimanagementaccounts/apis/connections | listsecrets |
| microsoft.web/sites/backups | list |
| Microsoft.Web/sites/config | list |
| 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 | list |
| Microsoft.Web/sites/slots/config | list |
| microsoft.web/sites/slots/functions | listsecrets |
To determine which resource types have a list operation, use the following options:
View the REST API operations for a resource provider, and look for list operations. For example, storage accounts have the listKeys operation.
Use the Get-AzProviderOperation PowerShell cmdlet. The following example gets all list operations for storage accounts:
Get-AzProviderOperation -OperationSearchString "Microsoft.Storage/*" | where {$_.Operation -like "*list*"} | FT OperationUse the following Azure CLI command to filter only the list operations:
az provider operation show --namespace Microsoft.Storage --query "resourceTypes[?name=='storageAccounts'].operations[].name | [?contains(@, 'list')]"
managementGroupResourceId
managementGroupResourceId(resourceType, resourceName1, [resourceName2], ...)
Returns the unique identifier for a resource deployed at the management group level.
Namespace: az.
The managementGroupResourceId function is available in Bicep files, but you typically don't need it. Instead, use the symbolic name for the resource and access the id property.
The identifier is returned in the following format:
/providers/Microsoft.Management/managementGroups/{managementGroupName}/providers/{resourceType}/{resourceName}
Remarks
Use this function to get the resource ID for resources that are deployed to the management group rather than a resource group. The returned ID differs from the value returned by the resourceId function by not including a subscription ID and a resource group value.
managementGroupResourceID example
The following template creates and assigns a policy definition. It uses the managementGroupResourceId function to get the resource ID for policy definition.
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])
Determines whether a resource type supports zones for a region. This function only supports zonal resources. Zone redundant services return an empty array. For more information, see Azure services that support availability zones.
Namespace: az.
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| providerNamespace | Yes | string | The resource provider namespace for the resource type to check for zone support. |
| resourceType | Yes | string | The resource type to check for zone support. |
| location | Yes | string | The region to check for zone support. |
| numberOfZones | No | integer | The number of logical zones to return. The default is 1. The number must be a positive integer from 1 to 3. Use 1 for single-zoned resources. For multi-zoned resources, the value must be less than or equal to the number of supported zones. |
| offset | No | integer | The offset from the starting logical zone. The function returns an error if offset plus numberOfZones exceeds the number of supported zones. |
Return value
An array with the supported zones. When you use the default values for offset and numberOfZones, a resource type and region that supports zones returns the following array:
[
"1"
]
When you set the numberOfZones parameter to 3, it returns:
[
"1",
"2",
"3"
]
When the resource type or region doesn't support zones, the function returns an empty array.
[
]
Remarks
Azure Availability Zones fall into two categories - zonal and zone-redundant. Use the pickZones function to return an availability zone for a zonal resource. For zone redundant services (ZRS), the function returns an empty array. Zonal resources typically have a zones property at the top level of the resource definition. To determine the category of support for availability zones, see Azure services that support availability zones.
To determine if a given Azure region or location supports availability zones, call the pickZones function with a zonal resource type, such as Microsoft.Network/publicIPAddresses. If the response isn't empty, the region supports availability zones.
pickZones example
The following Bicep file shows three results for using the pickZones function.
output supported array = pickZones('Microsoft.Compute', 'virtualMachines', 'westus2')
output notSupportedRegion array = pickZones('Microsoft.Compute', 'virtualMachines', 'westus')
output notSupportedType array = pickZones('Microsoft.Cdn', 'profiles', 'westus2')
The output from the preceding examples returns three arrays.
| Name | Type | Value |
|---|---|---|
| supported | array | [ "1" ] |
| notSupportedRegion | array | [] |
| notSupportedType | array | [] |
Use the response from pickZones to decide whether to provide null for zones or assign virtual machines to different zones.
providers
The providers function is deprecated in Bicep. Don't use it. If you used this function to get an API version for the resource provider, provide a specific API version in your Bicep file. Using a dynamically returned API version can break your template if the properties change between versions.
The providers operation is still available through the REST API. You can use it outside of a Bicep file to get information about a resource provider.
Namespace: az.
reference
reference(resourceName or resourceIdentifier, [apiVersion], ['Full'])
Returns an object that represents a resource's runtime state. The output and behavior of the reference function depend heavily on how each resource provider (RP) implements its PUT and GET responses.
Namespace: az.
Bicep files provide access to the reference function, although you typically don't need it. Instead, use the symbolic name of the resource. You can only use the reference function within the properties object of a resource. You can't use it for top-level properties like name or location. The same rule generally applies to references that use the symbolic name. However, for properties such as name, you can generate a template without using the reference function. You know enough about the resource name to directly emit the name. These are compile-time properties. Bicep validation can identify any incorrect usage of the symbolic name.
The following example deploys a storage account. The first two outputs give you the same results.
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
To get a property from an existing resource that you didn't deploy in the template, use the existing keyword:
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
To reference a resource that's nested inside a parent resource, use the nested accessor (::). You only use this syntax when you're accessing the nested resource from outside of the parent resource.
vNet1::subnet1.properties.addressPrefix
If you attempt to reference a resource that doesn't exist, you get the NotFound error and your deployment fails. The use-recognized-resource-type linter rule flags any referenced resource that uses an unrecognized or invalid resource type.
resourceId
resourceId([subscriptionId], [resourceGroupName], resourceType, resourceName1, [resourceName2], ...)
Returns the unique identifier of a resource.
Namespace: az.
The resourceId function is available in Bicep files, but you typically don't need it. Instead, use the symbolic name for the resource and access the id property.
Use this function when the resource name is ambiguous or not provisioned within the same Bicep file. The format of the returned identifier varies based on whether the deployment happens at the scope of a resource group, subscription, management group, or tenant.
For example:
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
To get the resource ID for a resource that isn't deployed in the Bicep file, use the existing keyword.
param storageAccountName string
resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' existing = {
name: storageAccountName
}
output storageID string = storageAccount.id
For more information, see the JSON template resourceId function.
roleDefinitions
roleDefinitions(roleName)
Returns information about the specified role definition, including id and roleDefinitionId. It's a name-based helper for Azure RBAC role assignments. Instead of requiring you to hardcode the GUID of a custom or built-in role definition (like Contributor, Reader, and others), it lets you provide the custom or built-in role’s display name, and the function resolves the corresponding role definition information at deployment time.
Namespace: az.
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| roleName | Yes | string | The display name of the role definition. |
Return value
An object representing the role definition, including id and roleDefinitionId.
Examples
The following Bicep code creates a deterministic Azure RBAC role assignment that grants a specified principal the Storage Blob Data Reader built-in role at the deployment scope by resolving the role definition by name at deployment time.
@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
}
}
For more information, see the JSON template resourceId function.
subscriptionResourceId
subscriptionResourceId([subscriptionId], resourceType, resourceName1, [resourceName2], ...)
Returns the unique identifier for a resource deployed at the subscription level.
Namespace: az.
The subscriptionResourceId function is available in Bicep files, but typically you don't need it. Instead, use the symbolic name for the resource and access the id property.
The identifier is returned in the following format:
/subscriptions/{subscriptionId}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
Remarks
Use this function to get the resource ID for resources that are deployed to the subscription rather than a resource group. The returned ID differs from the value returned by the resourceId function by not including a resource group value.
subscriptionResourceId example
The following Bicep file assigns a built-in role. You can deploy it to either a resource group or subscription. It uses the subscriptionResourceId function to get the resource ID for built-in roles.
@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], ...)
Returns the unique identifier for a resource deployed at the tenant level.
Namespace: az.
The tenantResourceId function is available in Bicep files, but typically you don't need it. Instead, use the symbolic name for the resource and access the id property.
The identifier is returned in the following format:
/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
Built-in policy definitions are tenant level resources. To deploy a policy assignment that references a built-in policy definition, use the tenantResourceId function.
@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)
Returns the logical availability zone (for example, 1, 2, or 3) that corresponds to a physical availability zone for a specified subscription in a given Azure region.
Namespace: az
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| subscriptionId | Yes | string | The ID of the Azure subscription, such as 12345678-1234-1234-1234-1234567890ab. |
| location | Yes | string | The Azure region that supports availability zones, such as westus2. |
| physicalZone | Yes | string | The physical availability zone identifier (for example, a data center-specific identifier like westus2-az1). |
Return value
A string representing the logical availability zone (for example, 1, 2, or 3) that corresponds to the specified physical zone in the given region and subscription. If the physical zone is invalid or not supported, the function returns an empty string ('').
Remarks
- The
toLogicalZonefunction retrieves the logical zone mapping based on the subscription’s zone configuration in the specified region. - Logical zones are standardized identifiers (for example,
1,2,3) used in resource configurations to ensure consistent zone assignments across Azure services. - Physical zone identifiers are region-specific and might vary between subscriptions. Use the
toPhysicalZonefunction to reverse this mapping. - The function requires that the region supports availability zones. For a list of supported regions, see Azure services that support availability zones.
- If the physical zone doesn't exist or isn't mapped for the subscription, the function returns an empty string.
- This function is useful for aligning physical zone deployments with logical zone configurations in templates, especially for cross-subscription or multi-region scenarios.
Examples
The following example retrieves the logical zone for a physical zone in West US 2 for a specific subscription:
param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param physicalZone string = 'westus2-az1'
output logicalZone string = toLogicalZone(subscriptionId, 'westus2', physicalZone)
Expected output:
| Name | Type | Value |
|---|---|---|
| logicalZone | String | 1 |
The following example uses toLogicalZone to configure a virtual machine with the correct logical zone:
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
Expected output:
| Name | Type | Value |
|---|---|---|
| logicalZone | String | 1 |
toLogicalZones
toLogicalZones(subscriptionId, location, physicalZones)
Returns the logical availability zones (for example, 1, 2, or 3) corresponding to physical availability zones for a specified subscription in a given Azure region. To convert a single physical zone, use the toLogicalZone function.
Namespace: az
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| subscriptionId | Yes | string | The ID of the Azure subscription, such as 12345678-1234-1234-1234-1234567890ab. |
| location | Yes | string | The Azure region that supports availability zones, such as westus2. |
| physicalZones | Yes | array | An array of physical zone names to convert to logical zones (for example, a data center-specific identifier like westus2-az1, westus2-az2, ...). |
Return value
An array of logical zone names corresponding to the provided physical zones (for example, 1, 2, or 3). If a physical zone is invalid or not supported, the function returns an empty string ('').
Remarks
The toLogicalZones function maps physical zone names to their logical zone equivalents for a specified Azure subscription and region. This mapping is useful for configuring or querying resources based on logical zones within an Azure region. The function requires a valid subscription ID, a supported Azure location, and an array of physical zone names. If a physical zone is invalid or not available in the specified location, the function might return an empty string for that zone or throw an error, depending on the context.
Examples
The following example retrieves the logical zones for a list of physical zones in West US 2 for a specific subscription:
param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param physicalZones array = ['westus2-az1', 'westus2-az2', 'westus2-az3']
output logicalZones array = toLogicalZones(subscriptionId, 'westus2', physicalZones)
Expected output:
| Name | Type | Value |
|---|---|---|
| logicalZone | array | ["1","2","3"] |
toPhysicalZone
toPhysicalZone(subscriptionId, location, logicalZone)
Returns the physical availability zone identifier, such as a data center-specific identifier like westus2-az1, that corresponds to a logical availability zone for a specified subscription in a given Azure region.
Namespace: az
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| subscriptionId | Yes | string | The ID of the Azure subscription, such as 12345678-1234-1234-1234-1234567890ab. |
| location | Yes | string | The Azure region that supports availability zones, such as westus2. |
| logicalZone | Yes | string | The logical availability zone, such as 1, 2, or 3. |
Return value
A string representing the physical availability zone identifier, such as westus2-az1, that corresponds to the specified logical zone in the given region and subscription. If the logical zone is invalid or not supported, the function returns an empty string ('').
Remarks
- The
toPhysicalZonefunction retrieves the physical zone mapping based on the subscription’s zone configuration in the specified region. - Physical zones are data center-specific identifiers that can vary between subscriptions, while logical zones, such as
1,2,3, are standardized for resource configurations. - Use the
toLogicalZonefunction to reverse this mapping and convert a physical zone to its logical equivalent. - The function requires that the region supports availability zones. For a list of supported regions, see Azure services that support availability zones.
- If the logical zone doesn't exist or isn't mapped for the subscription, the function returns an empty string.
- This function is useful for scenarios that require physical zone identifiers, such as logging, auditing, or cross-subscription zone alignment in multiregion deployments.
Examples
The following example retrieves the physical zone for a logical zone in West US 2 for a specific subscription:
param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param logicalZone string = '1'
output physicalZone string = toPhysicalZone(subscriptionId, 'westus2', logicalZone)
Expected output (assuming logical zone 1 maps to westus2-az1):
| Name | Type | Value |
|---|---|---|
| physicalZone | String | westus2-az1 |
The following example uses toPhysicalZone to log the physical zone for a virtual machine deployment:
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
Expected output:
| Name | Type | Value |
|---|---|---|
| physicalZone | String | westus2-az1 |
toPhysicalZones
toPhysicalZones(subscriptionId, location, logicalZones)
Returns the physical availability zone identifiers (for example, a data center-specific identifier like westus2-az1) corresponding to logical availability zones for a specified subscription in a given Azure region. To convert a single logical zone, use the toPhysicalZone function.
Namespace: az
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| subscriptionId | Yes | string | The ID of the Azure subscription, such as 12345678-1234-1234-1234-1234567890ab. |
| location | Yes | string | The Azure region that supports availability zones, such as westus2. |
| logicalZone | Yes | string[] | The logical availability zones (for example, 1, 2, or 3) to convert to physical zones. |
Return value
An array of physical zone names (for example, westus2-az1, westus2-az2 ) corresponding to the provided logical zones. If a logical zone is invalid or not supported, the function returns an empty string ('').
Remarks
The toPhysicalZones function maps logical zone names to their physical zone equivalents for a specified Azure subscription and region. This mapping is useful for deploying or configuring resources in specific physical zones within an Azure region. The function requires a valid subscription ID, a supported Azure location, and an array of logical zone names. If a logical zone is invalid or unavailable in the specified location, the function might return an empty string for that zone or throw an error, depending on the context.
Examples
The following example retrieves the physical zones for a list of logical zones in West US 2 for a specific subscription:
param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param logicalZones array = ['1', '2', '3']
output physicalZones array = toPhysicalZones(subscriptionId, 'westus2', logicalZones)
Expected output (assuming logical zone 1 maps to westus2-az1, logical zone 1 maps to westus2-az1, and logical zone 3 maps to westus2-az3):
| Name | Type | Value |
|---|---|---|
| physicalZone | array | ["westus2-az1","westus2-az2","westus2-az3"] |
Next steps
- To get values from the current deployment, see Deployment value functions.
- To iterate a specified number of times when creating a type of resource, see Iterative loops in Bicep.