Bicep 的资源函数

本文介绍用于获取资源值的 Bicep 函数。

若要从当前部署中获取值，请参阅部署值函数。

this命名空间

命名 this 空间在资源定义中提供了运行时资源状态发现的函数。 这些函数允许模板根据环境中是否已有资源进行调整配置。

• this.exists()返回一个布尔值，表示该资源是否当前存在。
• this.existingResource()： 如果资源存在，返回该资源的对象表示;如果不存在，则返回空。

存在

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() 实际的资源对象。 你可以使用 空宽容算子（！） 或 安全导航算子（.？）安全地访问嵌套属性。

命名空间： 这个

示例

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 = [
  'chinaeast2'
  'chinaeast3'
  'chinanorth3'
]

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 密钥保管库 返回机密。 使用此函数将机密传递给 Bicep 模块的安全字符串参数。

只能在模块的 getSecret 部分中使用 params 函数。 只能将其与 Microsoft.KeyVault/vaults 资源一起使用。

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

如果尝试在 Bicep 文件的任何其他部分使用此函数，则会收到错误。 如果将此函数与字符串内插一起使用，则即使在参数部分使用，也会收到错误。

只在带有 @secure() 装饰器的模块参数时使用该函数。

密钥保管库必须将 enabledForTemplateDeployment 设置为 true。 部署 Bicep 文件的用户必须有权访问该机密。 有关详细信息，请参阅在部署 Bicep 过程中使用 Azure 密钥保管库 传递安全参数值。

不需要命名空间限定符，因为此函数与资源类型配合使用。

参数

返回值

机密名称的机密值。

示例

以下 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 函数。 以下是几个常见示例：list、listKeys、listKeyValue 和 listSecrets。

此函数的语法因列表操作的名称而异。 返回的值也因操作而异。 Bicep 目前不支持 list* 函数的完成和验证。

对于 Bicep CLI 0.4.X 或更高版本，可以使用访问器运算符调用 list 函数。 例如 storageAccount.listKeys()。

不需要命名空间限定符，因为此函数与资源类型配合使用。

参数

有效使用

使用 list 资源定义属性中的函数。 不要使用list会暴露Bicep文件部分敏感信息outputs的功能。 输出值存储在部署历史中，恶意用户可能会获取这些值。

当你使用 list 带有 迭代循环的函数时，你可以用它， input 因为表达式被赋予了资源属性。 你不能用它， count 因为计数必须先确定，函数才能 list 解析。

如果在有条件部署的资源中使用 list 函数，则即使未部署该资源，也会对该函数求值。 如果 list 函数引用某个不存在的资源，则会出现错误。 使用条件表达式 ?: 运算符确保仅在部署资源时计算函数。

use-recognized-resource-type linter 规则会标记任何使用未识别或无效资源类型的引用资源。

返回值

返回的对象因使用的 list 函数而异。 例如，存储账户的 listKeys 函数返回如下格式：

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

其他 list 函数具有不同的返回格式。 要查看函数的格式，请将其包含在outputs示例 Bicep 文件中的部分中。

List 示例

以下示例部署一个存储帐户，然后对该存储帐户调用 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* 。

要确定哪些资源类型有列表操作，请使用以下选项：

• 查看资源提供程序的 REST API 操作，并查找列表操作。 例如，存储帐户具有 listKeys 操作。

• 使用 Get-​AzProvider​Operation PowerShell cmdlet。 以下示例获取存储帐户的所有列表操作：

  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 不同于 resourceId 函数返回的值，前者不包含订阅 ID 和资源组值。

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。

参数

返回值

具有受支持区域的数组。 当你使用默认值和offsetnumberOfZones时，支持区域的资源类型和区域会返回以下数组：

[
  "1"
]

当你将参数设置为 numberOfZones 3时，返回如下：

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

当资源类型或区域不支持区域时，函数返回的是空数组。

[
]

备注

Azure 可用性区域分为两类——区域冗余和区域冗余。 使用 pickZones 该函数返回区域资源的可用区。 区域资源通常有 zones 属性，位于资源定义的顶层。 若要确定可用性区域的支持类别，请参阅 支持可用性区域的 Azure 服务。

若要确定给定的 Azure 区域或位置是否支持可用性区域，请使用区域资源类型调用 pickZones 函数，例如 Microsoft.Network/publicIPAddresses。 如果响应非空，则该区域支持可用性区域。

pickZones 示例

以下 Bicep 文件显示了使用 pickZones 函数的三个结果。

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

上述示例的输出返回三个数组。

利用响应 pickZones 来决定是否为区域提供空值，或将虚拟机分配给不同的区域。

供应商

在Bicep中，提供者功能已被弃用。 不要使用它。 如果你用这个函数获取资源提供者的 API 版本，请在 Bicep 文件中提供具体的 API 版本。 如果版本之间的属性发生更改，则使用动态返回的 API 版本可能会破坏模板。

providers 运算仍可通过 REST API 提供。 你可以在Bicep文件之外使用它来获取资源提供者的信息。

命名空间：az。

引用

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

返回一个表示资源运行状态的对象。 函数的 reference 输出和行为高度依赖于每个资源提供者（RP）如何实现其 PUT 和 GET 响应。

命名空间：az。

Bicep文件提供了访问参考功能的功能，虽然通常你并不需要它。 相反，使用资源的象征名称。 你只能在资源的对象中使用引用函数 properties 。 你不能用它来处理像 name or location这样的顶级属性。 同样的规则通常适用于使用符号名称的引用。 然而，对于像 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 linter 规则会标记任何使用未识别或无效资源类型的引用资源。

ResourceId

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，请使用 existing 关键字。

param storageAccountName string

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

output storageID string = storageAccount.id

有关详细信息，请参阅 JSON 模板 resourceId 函数。

roleDefinitions

roleDefinitions(roleName)

返回有关指定角色定义的信息，包括 id 和 roleDefinitionId。 它是Azure RBAC 角色分配的基于名称的帮助程序。 它不再要求你硬编码自定义或内置角色定义（如 Contributor、Reader 等）的 GUID，而是允许你提供自定义或内置角色的显示名称，函数会在部署时解析对应的角色定义信息。

命名空间：az。

参数

返回值

一个对象，表示角色定义，包括 id 和 roleDefinitionId。

例子

以下 Bicep 代码创建了一个确定性的 Azure RBAC 角色分配，通过在部署时按角色名解析，赋予指定的主体 Storage Blob Data Reader 内置角色。

@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

参数

返回值

一个字符串，表示与给定区域和订阅中的指定物理区域相对应的逻辑可用性区域（例如 1， 2或 3）。 如果物理区无效或不支持，函数返回空字符串（''）。

备注

• 该 toLogicalZone 函数根据指定区域中订阅的区域配置检索逻辑区域映射。
• 逻辑区域是标准化标识符（例如 1， 2，） 3用于资源配置，以确保跨 Azure 服务的区域分配一致。
• 物理区域标识符是特定地区的，且可能因订阅而异。 使用该 toPhysicalZone 函数来反转此映射。
• 该函数要求该区域支持可用性区域。 有关支持区域的列表，请参阅 支持可用性区域的 Azure 服务。
• 如果物理区域不存在或未为订阅映射，该函数将返回一个空字符串。
• 此函数可用于使物理区域部署与模板中的逻辑区域配置保持一致，尤其是跨订阅或多区域方案。

例子

以下示例为特定订阅检索中国北部 2 中物理区域的逻辑区域：

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

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

预期输出：

以下示例用于 toLogicalZone 配置具有正确逻辑区域的虚拟机：

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

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

预期输出：

toLogicalZones

toLogicalZones(subscriptionId, location, physicalZones)

返回与给定 Azure 区域中指定订阅的物理可用性区域对应的逻辑可用性区域（例如 1， 2或 3）。 若要转换单个物理区域，请使用函数 toLogicalZone 。

命名空间： az

参数

返回值

与提供的物理区域（例如，1或23）对应的逻辑区域名称数组。 如果物理区域无效或不支持，函数返回空字符串（''）。

备注

该 toLogicalZones 函数将物理区域名称映射到指定 Azure 订阅和区域的逻辑区域等效项。 这种映射对于基于 Azure 区域内逻辑区域的资源配置或查询非常有用。 该函数需要有效的订阅 ID、支持的 Azure 位置和物理区域名称数组。 如果某个物理区域在指定位置无效或不可用，函数可能会返回该区域的空字符串或抛出错误，具体取决于上下文。

例子

以下示例检索特定订阅中国北部 3 中物理区域列表的逻辑区域：

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

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

预期输出：

toPhysicalZone

toPhysicalZone(subscriptionId, location, logicalZone)

返回物理可用性区标识符，例如数据中心特定的标识符，如 chinanorth3-az1，对应特定 Azure 区域中指定订阅的逻辑可用性区。

命名空间： az

参数

返回值

表示物理可用性区域标识符的字符串，例如 chinanorth3-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, 'chinanorth3', logicalZone)

预期输出（假设逻辑区域 1 映射到 chinanorth3-az1）：

以下示例用于 toPhysicalZone 记录虚拟机部署的物理区域：

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

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

预期输出：

toPhysicalZones

toPhysicalZones(subscriptionId, location, logicalZones)

返回与给定 Azure 区域中指定订阅的逻辑可用性区域对应的物理可用性区域标识符（例如，特定于数据中心的标识符 chinanorth3-az1）。 若要转换单个逻辑区域，请使用函数 toPhysicalZone 。

命名空间： az

参数

返回值

与提供的逻辑区域对应的物理区域名称数组（例如 chinanorth3-az1， chinanorth3-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, 'chinanorth3', logicalZones)

预期输出（假设逻辑区域 1 映射到 chinanorth3-az1，逻辑区域 1 映射到 chinanorth3-az1，逻辑区域 3 映射到 chinanorth3-az3）：

后续步骤

• 若要从当前部署中获取值，请参阅部署值函数。
• 若要在创建资源类型时迭代指定的次数，请参阅 Bicep 中的迭代循环。