Bicep 的资源函数

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

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

extensionResourceId

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

返回扩展资源的资源 ID。 扩展资源是一种资源类型,可应用于扩充另一资源的功能。

命名空间:az

extensionResourceId 函数在 Bicep 文件中可用,但通常不需要它。 请改用资源的符号名称并访问 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'
  'chinaeast'
  'chinanorth'
]

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

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

内置策略定义是租户级别的资源。 有关部署内置策略定义的示例,请参阅 tenantResourceId

getSecret

keyVaultName.getSecret(secretName)

从 Azure Key Vault 返回机密。 使用此函数将机密传递给 Bicep 模块的安全字符串参数。

注意

可以在 .bicepparam 文件中使用 az.getSecret(subscriptionId, resourceGroupName, keyVaultName, secretName, secretVersion) 函数来检索密钥保管库机密。 有关详细信息,请参阅 getSecret

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

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

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

此函数只能与带 @secure() 修饰器的模块参数一起使用。

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

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

参数

参数 必选 Type 说明
secretName 字符串 密钥保管库中存储的机密的名称。

返回值

机密名称的机密值。

示例

以下 Bicep 文件用作模块。 其中包含一个定义有 @secure() 修饰器的 adminPassword 参数。

param sqlServerName string
param adminLogin string

@secure()
param adminPassword string

resource sqlServer 'Microsoft.Sql/servers@2022-08-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@2023-02-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])

可以使用以 list 开头的操作为任何资源类型调用 list 函数。 以下是几个常见示例:listlistKeyslistKeyValuelistSecrets

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

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

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

参数

参数 必选 Type 说明
apiVersion 字符串 如果未提供此参数,将使用资源的 API 版本。 仅当需要使用特定版本来运行函数时,才提供自定义 API 版本。 使用 yyyy-mm-dd 格式。
functionValues object 具有函数值的对象。 仅为支持接收具有参数值的对象的函数提供此对象,例如存储帐户上的 listAccountSas。 本文中演示了传递函数值的示例。

有效使用

list 函数可以在资源定义的属性中使用。 请不要使用在 Bicep 文件的 outputs 节中公开敏感信息的 list 函数。 输出值存储在部署历史记录中,可能会被恶意用户检索到。

迭代循环一起使用时,可对 input 使用 list 函数,因为表达式分配给了资源属性。 不能将将其与 count 一起使用,因为在解析 list 函数之前必须先要确定 count。

如果在有条件部署的资源中使用 list 函数,则即使未部署该资源,也会对该函数求值。 如果 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@2022-09-01' = {
  name: 'dscript${uniqueString(resourceGroup().id)}'
  location: location
  kind: 'StorageV2'
  sku: {
    name: 'Standard_LRS'
  }
}

resource dScript 'Microsoft.Resources/deploymentScripts@2020-10-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.AnalysisServices/servers listGatewayStatus
Microsoft.AppConfiguration/configurationStores ListKeys
Microsoft.AppPlatform/Spring listTestKeys
Microsoft.Automation/automationAccounts listKeys
Microsoft.Batch/batchAccounts listkeys
Microsoft.CognitiveServices/accounts listKeys
Microsoft.ContainerRegistry/registries listBuildSourceUploadUrl
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.Devices/iotHubs listkeys
Microsoft.Devices/iotHubs/iotHubKeys listkeys
Microsoft.Devices/provisioningServices/keys listkeys
Microsoft.Devices/provisioningServices 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.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.MachineLearningServices/workspaces/computes listKeys
Microsoft.MachineLearningServices/workspaces/computes listNodes
Microsoft.MachineLearningServices/workspaces 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.Relay/namespaces/authorizationRules listkeys
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.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

若要确定哪些资源类型具有列表操作,请使用以下选项:

  • 查看资源提供程序的 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')]"
    

pickZones

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

确定资源类型是否支持某一地区的区域。

命名空间:az

参数

参数 必选 Type 说明
providerNamespace 字符串 要检查是否有区域支持的资源类型的资源提供程序命名空间。
resourceType 字符串 要检查是否有区域支持的资源类型。
location 字符串 要检查是否有区域支持的地区。
numberOfZones integer 要返回的逻辑区域数。 默认值为 1。 该数字必须是 1 到 3 的正整数。 对于单区域资源,请使用 1。 对于多区域资源,该值必须小于或等于受支持区域的数量。
offset integer 起始逻辑区域的偏移量。 如果 offset 加上 numberOfZones 超过受支持区域的数量,函数将返回错误。

返回值

具有受支持区域的数组。 如果使用 offset 和 numberOfZones 的默认值,支持区域的资源类型和地区返回以下数组:

[
    "1"
]

numberOfZones 参数设置为 3 时,它将返回:

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

如果资源类型或地区不支持区域,则返回空数组。

[
]

pickZones 示例

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

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

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

名称 类型
受支持 array [ "1" ]
notSupportedRegion array []
notSupportedType array []

可以使用 pickZones 的响应来确定是为区域提供 null,还是将虚拟机分配给不同的区域。

providers

在 Bicep 中已弃用 providers 函数。 我们不再建议使用它。 如果你使用了此函数来获取资源提供程序的 API 版本,建议在 Bicep 文件中提供特定的 API 版本。 如果版本之间的属性发生更改,则使用动态返回的 API 版本可能会破坏模板。

providers 运算仍可通过 REST API 提供。 可以在 Bicep 文件外部使用该操作来获取有关资源提供程序的信息。

命名空间:az

reference

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

返回表示资源的运行时状态的对象。

命名空间:az

Bicep 文件提供了对引用函数的访问权限,尽管这通常是不必要的。 相反,建议使用资源的符号名称。 引用函数只能在资源的 properties 对象中使用,不能用于 namelocation 等顶级属性。 这通常也适用于使用符号名称的引用。 但是,对于 name 之类的属性,可以在不使用引用函数的情况下生成模板。 了解有关资源名称的足够信息可以直接发出该名称。 它称为编译时属性。 Bicep 验证可以识别符号名称的任何错误用法。

以下示例部署一个存储帐户。 前两个输出提供相同的结果。

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

resource storageAccount 'Microsoft.Storage/storageAccounts@2022-09-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@2022-09-01' existing = {
  name: storageAccountName
}

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

若要引用嵌套在父资源中的资源,请使用嵌套访问器(::) 。 仅在从父资源外部访问嵌套资源时,才使用此语法。

vNet1::subnet1.properties.addressPrefix

如果尝试引用不存在的资源,则将出现 NotFound 错误,并且部署将失败。

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@2022-09-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@2022-09-01' existing = {
    name: storageAccountName
}

output storageID string = storageAccount.id

有关详细信息,请参阅 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
  }
}

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 = [
  'chinanorth'
  'chinanorth2'
  'chinanorth3'
]

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

resource policyDefinition 'Microsoft.Authorization/policyDefinitions@2021-06-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@2021-06-01' = {
  name: 'location-lock'
  properties: {
    scope: mgScope
    policyDefinitionId: managementGroupResourceId('Microsoft.Authorization/policyDefinitions', policyDefinitionName)
  }
  dependsOn: [
    policyDefinition
  ]
}

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@2022-06-01' = {
  name: policyAssignmentName
  properties: {
    scope: subscriptionResourceId('Microsoft.Resources/resourceGroups', resourceGroup().name)
    policyDefinitionId: tenantResourceId('Microsoft.Authorization/policyDefinitions', policyDefinitionID)
  }
}

后续步骤