Функции ресурсов для Bicep

В этой статье описываются функции Bicep для получения значений ресурсов.

Получение значений параметров текущего развертывания описано в разделе Функции значений развертывания.

Пространство `this` имён

Пространство имён предоставляет функции для обнаружения состояния this ресурса во время выполнения в определении ресурса. Эти функции позволяют вашему шаблону адаптировать конфигурацию в зависимости от того, существует ли ресурс уже в среде.

this.exists(): Возвращает значение bool, указывающее, существует ли ресурс в данный момент.
this.existingResource(): Возвращает объектное представление ресурса, если оно существует, или null, если нет.

существует

this.exists()

Возвращает значение bool, указывающее, существует ли ресурс в 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'
  }
}

существующийРесурс

this.existingResource()

Возвращает объектное представление ресурса, если оно существует или null нет. Эта функция сочетается с this.exists(). Возвращая exists() простой булевой результат, existingResource() возвращает фактический объект ресурса. Вы можете безопасно получить доступ к вложенным свойствам, используя оператор null-forgiving (!) или оператор безопасной навигации(.?).

Пространство имён: это

Пример

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], ...)

Возвращает идентификатор ресурса для ресурса расширения. Ресурс расширения — это тип ресурса, который вы применяете к другому ресурсу для расширения его возможностей.

Пространство имен: az.

Вы можете использовать эту extensionResourceId функцию в файлах Bicep, но обычно она не нужна. Вместо этого используйте символьное имя для ресурса и получите доступ к свойству id.

Базовый формат идентификатора ресурса, возвращаемого этой функцией:

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

Сегмент области зависит от расширяемого ресурса.

Когда вы применяете ресурс расширения к ресурсу, идентификатор ресурса возвращается в следующем формате:

/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 возникает ошибка. При использовании этой функции с интерполяцией строк также возникает ошибка, даже если она используется в разделе params.

Используйте функцию только с параметром модуля, в котором есть @secure() декоратор.

У хранилища ключей параметр enabledForTemplateDeployment должен иметь значение true. Пользователь, развертывающий файл Bicep, должен иметь доступ к секрету. Дополнительные сведения см. в разделе Использовать Azure Key Vault для передачи значения безопасного параметра во время развертывания Bicep.

Квалификатор пространства имен не требуется, так как функция используется с типом ресурса.

Параметры

Параметр	Обязательное поле	Тип	Описание
secretName;	Да	строка	Имя секрета, хранящегося в хранилище ключей.

Возвращаемое значение

Значение секрета для имени секрета.

Пример

Следующий 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.

Синтаксис для этой функции зависит от названия операции list. Перечень возвращаемых значений также зависит от конкретной операции. Bicep в настоящее время не поддерживает завершения и проверку для функций list*.

Если Bicep CLI версии 0.4.X или более поздней вы вызываете функцию списка с помощью оператора accessor. Например, storageAccount.listKeys().

Квалификатор пространства имен не требуется, так как функция используется с типом ресурса.

Параметры

Параметр	Обязательное поле	Тип	Описание
версия_API	Нет	строка	Если не указать этот параметр, будет использоваться версия API для ресурса. Если необходимо выполнять функцию с определенной версией, укажите только пользовательскую версию API. Используйте формат гггг-мм-дд.
functionValues	Нет	объект	Объект, содержащий значения для функции. Предоставляйте этот объект только для функций, которые поддерживают прием объекта с такими значениями параметров, как `listAccountSas`, в учетной записи хранения. В этой статье показан пример передачи значения функции.

Допустимые варианты использования

Используйте list функции в свойствах определения ресурса. Не используйте list функцию, которая раскрывает чувствительную информацию в разделе outputs файла Bicep. Выходные значения хранятся в истории развертывания, и злонамеренный пользователь может их извлечь.

Когда вы используете list функцию с итеративным циклом, вы можете использовать её для , input потому что выражение назначено свойству ресурса. Вы не можете использовать его с count ней, потому что количество нужно определить до того, как list функция будет решена.

При использовании функции list в ресурсе, который развернут условно, функция вычисляется, даже если ресурс не развернут. Если функция list ссылается на несуществующий ресурс, возникает ошибка. Используйте оператор условного выражения ?:, чтобы убедиться, что функция вычисляется только при развертывании ресурса.

Правило linter отмечает use-recognized-resource-type любой ссылающийся ресурс, использующий нераспознанный или недопустимый тип ресурса.

Возвращаемое значение

Возвращаемый объект зависит от используемой функции 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* .

Тип ресурса	Имя функции
Microsoft. Addons/supportProviders	listupportplaninfo
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. Автоматизация и автоматизацияAccounts	listKeys
Microsoft. Batch/batchAccounts	listkeys
Microsoft. BatchAI/workspaces/experiments/jobs	listoutputfiles
Microsoft. BotService/botServices/channel	listChannelWithKeys
Microsoft. Кэш/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/Container	listSasTokens
Microsoft. DataShare/accounts/share	listSynchronizations
Microsoft. DataShare/accounts/shareSubscriptions	listSourceShareSynchronizationSettings
Microsoft. DataShare/accounts/shareSubscriptions	listSynchronizationDetails
Microsoft. DataShare/accounts/shareSubscriptions	listSynchronizations
Microsoft. Устройства и iotHubs	listkeys
Microsoft. Устройства/iotHubs/iotHubKeys	listkeys
Microsoft. Устройства, подготовка служб и ключей	listkeys
Microsoft. Устройства и службы подготовки	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/темы	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/Database	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. Media/mediaservices/assets	listContainerSas
Microsoft. Media/mediaservices/assets	listStreamingLocator
Microsoft. Media/mediaservices/streamingLocator	listContentKeys
Microsoft. Media/mediaservices/streamingLocator	listPaths
Microsoft. Network/applicationSecurityGroups	listIpConfigurations
Microsoft. NotificationHubs/Namespaces/authorizationRules	listkeys
Microsoft. NotificationHubs/Namespaces/NotificationHubs/authorizationRules	listkeys
Microsoft. OperationsInsights/workspaces	список
Microsoft. OperationsInsights/workspaces	listKeys
Microsoft. ПолитикиInsights/исправлений	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/manager/devices	listFailoverSets
Microsoft. StorSimple/manager/devices	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/apis/connections	listconnectionkeys
microsoft.web/apimanagementaccounts/apis/connections	listsecrets
microsoft.web/sites/backups	список
Microsoft. Web/sites/config	список
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. Web/sites/slots/config	список
microsoft.web/sites/slots/functions	listsecrets

Чтобы определить, какие типы ресурсов имеют операцию списка, используйте следующие параметры:

Просмотрите операции REST API для поставщика ресурсов и найдите операции list. Например, в учетных записях хранения есть операция listKeys.
Воспользуйтесь командлетом PowerShell Get-AzProviderOperation. В следующем примере извлекаются все операции 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}

Замечания

Используйте эту функцию, чтобы получить идентификатор ресурсов для ресурсов, развернутых в управленческую группу , а не в группу ресурсов. Возвращаемый идентификатор отличается от значения, возвращаемого функцией resourceId, поскольку не включает идентификатор подписки и значение группы ресурсов.

Пример managementGroupResourceID

Следующий шаблон создает и назначает определение политики. Для получения идентификатора ресурса для определения политики используется функция managementGroupResourceId.

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.

Параметры

Параметр	Обязательное поле	Тип	Описание
пространство_имен_поставщика	Да	строка	Пространство имен поставщика ресурсов для типа ресурса, для которого проверяется поддержка зоны.
Тип ресурса	Да	строка	Тип ресурса для проверки поддержки зоны.
расположение	Да	строка	Регион, в котором проверяется поддержка зоны.
numberOfZones	Нет	целое число	Число логических зон для возврата. Значение по умолчанию — 1. Это должно быть целое положительное число от 1 до 3. Используйте 1 для ресурсов с одной зоной. Для ресурсов с несколькими зонами значение должно быть меньше или равно числу поддерживаемых зон.
смещение	Нет	целое число	Смещение от начальной логической зоны. Функция возвращает ошибку, если смещение плюс numberOfZones превышает число поддерживаемых зон.

Возвращаемое значение

Массив с поддерживаемыми зонами. Когда вы используете значения по умолчанию для offset и numberOfZones, тип ресурса и регион, поддерживающий зоны, возвращает следующий массив:

[
  "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')

Выходные данные из предыдущих примеров возвращают три массива.

Имя.	Тип	значение
службы	массив	[ "1" ]
notSupportedRegion	массив	[]
notSupportedType	массив	[]

Используйте отклик от pickZones для решения, предоставлять ли нулевое значение для зон или назначать виртуальные машины разным зонам.

поставщики

Функция врача в Bicep устарела. Не используйте его. Если вы использовали эту функцию для получения версии API для провайдера ресурса, укажите конкретную версию API в вашем файле Bicep. Использование динамически возвращаемой версии API может привести к поломке вашего шаблона, если свойства изменяются между версиями.

Операция поставщиков по-прежнему доступна посредством REST API. Вы можете использовать его вне файла Bicep, чтобы получить информацию о поставщике ресурсов.

Пространство имен: az.

Получение

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

Возвращает объект, отражающий состояние ресурса во время выполнения. Выход и поведение reference функции во многом зависят от того, как каждый поставщик ресурсов (RP) реализует свои ответы PUT и GET.

Пространство имен: az.

Bicep-файлы предоставляют доступ к функции референса, хотя обычно она не нужна. Вместо этого используйте символическое название ресурса. Вы можете использовать функцию ссылки только внутри properties объекта ресурса. Вы не можете использовать его для верхних свойств, таких name как или 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, а развертывание завершится сбоем. Правило linter отмечает use-recognized-resource-type любой ссылающийся ресурс, использующий нераспознанный или недопустимый тип ресурса.

идентификатор ресурса

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, используйте существующее ключевое слово.

param storageAccountName string

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

output storageID string = storageAccount.id

Дополнительные сведения см. в функции resourceId шаблона JSON.

roleDefinitions

roleDefinitions(roleName)

Возвращает сведения об определении указанной роли, включая id и roleDefinitionId. Это вспомогательный элемент на основе имен для назначений ролей RBAC Azure. Вместо того чтобы требовать жёсткого кодирования GUID собственного или встроенного определения роли (например, Contributor, Reader и других), он позволяет указать имя отображаемой или встроенной роли, а функция разрешает соответствующую информацию о определении роли в момент развертывания.

Пространство имен: az.

Параметры

Параметр	Обязательное поле	Тип	Описание
roleName	Да	строка	Отображаемое имя определения роли.

Возвращаемое значение

Объект, представляющий определение роли, включая 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
  }
}

Дополнительные сведения см. в функции resourceId шаблона JSON.

subscriptionResourceId

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

Возвращает уникальный идентификатор ресурса, развернутого на уровне подписки.

Пространство имен: az.

Функция subscriptionResourceId доступна в Bicep файлах, но обычно она не нужна. Вместо этого используйте символьное имя для ресурса и получите доступ к свойству id.

Идентификатор возвращается в следующем формате:

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

Замечания

Используйте эту функцию, чтобы получить идентификатор ресурсов для ресурсов, развернутых в подписке , а не в группе ресурсов. Возвращаемый идентификатор отличается от значения, возвращаемого функцией resourceId, тем, что он не включает значение группы ресурсов.

Пример subscriptionResourceId

Следующий Bicep файл назначает встроенную роль. Его можно развернуть либо в группе ресурсов, либо в подписке. Для получения идентификатора ресурса для встроенных ролей в нем используется функция subscriptionResourceId.

@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)

Возвращает логическую зону доступности (например, 1, 2, или 3), которая соответствует физической зоне доступности для определённой подписки в данном регионе Azure.

Пространство имен: az

Параметры

Параметр	Обязательное поле	Тип	Описание
ID подписки	Да	строка	ID подписки Azure, например `12345678-1234-1234-1234-1234567890ab`.
расположение	Да	строка	Регион Azure, поддерживающий зоны доступности, такие как `westus2`.
physicalZone	Да	строка	Идентификатор физической зоны доступности (например, идентификатор `westus2-az1`конкретного центра обработки данных).

Возвращаемое значение

Строка, представляющая логическую зону доступности (например, 1или23), соответствующую указанной физической зоне в заданном регионе и подписке. Если физическая зона недействительна или не поддерживается, функция возвращает пустую строку ('').

Замечания

Функция toLogicalZone извлекает сопоставление логических зон на основе конфигурации зоны подписки в указанном регионе.
Логические зоны — это стандартизированные идентификаторы (например, 1, 2, 3) для обеспечения согласованных назначений зон в службах Azure.
Физические идентификаторы зоны зависят от региона и могут различаться в зависимости от подписки. Используйте функцию для обратного 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)

Возвращает зоны логической доступности (например, 1, 2 или 3), соответствующие физическим зонам доступности для указанной подписки в заданном регионе Azure. Чтобы преобразовать одну физическую зону, используйте функцию toLogicalZone .

Пространство имен: az

Параметры

Параметр	Обязательное поле	Тип	Описание
ID подписки	Да	строка	ID подписки Azure, например `12345678-1234-1234-1234-1234567890ab`.
расположение	Да	строка	Регион Azure, поддерживающий зоны доступности, такие как `westus2`.
physicalZones	Да	массив	Массив имен физических зон для преобразования в логические зоны (например, идентификатор конкретного центра обработки данных, например `westus2-az1`, `westus2-az2`...).

Возвращаемое значение

Массив имен логических зон, соответствующих предоставленным физическим зонам (например, 1или23). Если физическая зона невалидна или не поддерживается, функция возвращает пустую строку ('').

Замечания

Функция toLogicalZones сопоставляет имена физических зон с эквивалентами логической зоны для указанной подписки и региона Azure. Это отображение полезно для настройки или запроса ресурсов на основе логических зон внутри региона Azure. Для функции требуется допустимый идентификатор подписки, поддерживаемое 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)

Возвращает физический идентификатор зоны доступности, например, специфичный для дата-центра идентификатор, например westus2-az1, который соответствует логической зоне доступности для определённой подписки в данном регионе Azure.

Пространство имен: az

Параметры

Параметр	Обязательное поле	Тип	Описание
ID подписки	Да	строка	ID подписки Azure, например `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)

Возвращает идентификаторы физической зоны доступности (например, идентификатор конкретного центра обработки данных, например westus2-az1), соответствующий зонам логической доступности для указанной подписки в заданном регионе Azure. Чтобы преобразовать одну логическую зону, используйте функцию toPhysicalZone .

Пространство имен: az

Параметры

Параметр	Обязательное поле	Тип	Описание
ID подписки	Да	строка	ID подписки Azure, например `12345678-1234-1234-1234-1234567890ab`.
расположение	Да	строка	Регион Azure, поддерживающий зоны доступности, такие как `westus2`.
логическая зона	Да	строка[]	Зоны логической доступности (например, `1`или`23`) для преобразования в физические зоны.

Возвращаемое значение

Массив имен физических зон (например, westus2-az1), westus2-az2 соответствующий предоставленным логическим зонам. Если логическая зона недопустима или не поддерживается, функция возвращает пустую строку ('').

Замечания

Функция toPhysicalZones сопоставляет имена логических зон с эквивалентами физической зоны для указанной подписки и региона Azure. Это отображение полезно для развертывания или настройки ресурсов в определённых физических зонах внутри региона Azure. Для функции требуется допустимый идентификатор подписки, поддерживаемое 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-az1 сопоставляется с 1westus2-az1и логическими зонами 3 сопоставляется с westus2-az3):

Имя.	Тип	значение
physicalZone	массив	["westus2-az1","westus2-az2","westus2-az3"]

Следующие шаги

Получение значений параметров текущего развертывания описано в разделе Функции значений развертывания.
Чтобы выполнить итерацию указанного количества раз при создании типа ресурса, см. раздел Iterative циклов в Bicep.

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-06-26

Функции ресурсов для Bicep

Пространство this имён

существует

Пример

существующийРесурс

Пример

extensionResourceId

getSecret

Параметры

Возвращаемое значение

Пример

список*

Параметры

Допустимые варианты использования

Возвращаемое значение

Пример функции list

Реализации

managementGroupResourceId

Замечания

Пример managementGroupResourceID

pickZones

Параметры

Возвращаемое значение

Замечания

Пример pickZones

поставщики

Получение

идентификатор ресурса

roleDefinitions

Параметры

Возвращаемое значение

Примеры

subscriptionResourceId

Замечания

Пример subscriptionResourceId

tenantResourceId

toLogicalZone

Параметры

Возвращаемое значение

Замечания

Примеры

toLogicalZones

Параметры

Возвращаемое значение

Замечания

Примеры

toPhysicalZone

Параметры

Возвращаемое значение

Замечания

Примеры

toPhysicalZones

Параметры

Возвращаемое значение

Замечания

Примеры

Следующие шаги

Обратная связь

Дополнительные ресурсы

Пространство `this` имён