Функции ресурсов для шаблонов ARM

Resource Manager предоставляет следующие функции для получения значений ресурсов в шаблоне Azure Resource Manager (шаблон ARM).

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

extensionResourceId

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

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

Параметры

Параметр Обязательно Тип Описание
baseResourceId Да строка Идентификатор ресурса, к которому применяется ресурс расширения.
тип_ресурса Да строка Тип ресурса расширения, включая пространство имен поставщика ресурсов.
имя_ресурса1 Да строка Имя ресурса расширения.
имя_ресурса2 Нет строка Следующий сегмент имени ресурса, если он необходим.

Продолжайте добавлять имена ресурсов в качестве параметров, если тип ресурса включает больше сегментов.

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

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

{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}

Пример использования этой функции с группой управления показан в следующем разделе.

Пример extensionResourceId

В следующем примере возвращается идентификатор ресурса для блокировки группы ресурсов.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "lockName": {
      "type": "string"
    }
  },
  "variables": {},
  "resources": [],
  "outputs": {
    "lockResourceId": {
      "type": "string",
      "value": "[extensionResourceId(resourceGroup().Id , 'Microsoft.Authorization/locks', parameters('lockName'))]"
    }
  }
}

Определение пользовательской политики, развернутое в группе управления, реализуется как ресурс расширения. Чтобы создать и назначить политику, разверните следующий шаблон в группе управления.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "_generator": {
      "name": "bicep",
      "version": "0.4.1.14562",
      "templateHash": "2350252618174097128"
    }
  },
  "parameters": {
    "targetMG": {
      "type": "string",
      "metadata": {
        "description": "Target Management Group"
      }
    },
    "allowedLocations": {
      "type": "array",
      "defaultValue": [
        "australiaeast",
        "australiasoutheast",
        "australiacentral"
      ],
      "metadata": {
        "description": "An array of the allowed locations, all other locations will be denied by the created policy."
      }
    }
  },
  "functions": [],
  "variables": {
    "mgScope": "[tenantResourceId('Microsoft.Management/managementGroups', parameters('targetMG'))]",
    "policyDefinitionName": "LocationRestriction"
  },
  "resources": [
    {
      "type": "Microsoft.Authorization/policyDefinitions",
      "apiVersion": "2020-03-01",
      "name": "[variables('policyDefinitionName')]",
      "properties": {
        "policyType": "Custom",
        "mode": "All",
        "parameters": {},
        "policyRule": {
          "if": {
            "not": {
              "field": "location",
              "in": "[parameters('allowedLocations')]"
            }
          },
          "then": {
            "effect": "deny"
          }
        }
      }
    },
    {
      "type": "Microsoft.Authorization/policyAssignments",
      "apiVersion": "2020-03-01",
      "name": "location-lock",
      "properties": {
        "scope": "[variables('mgScope')]",
        "policyDefinitionId": "[extensionResourceId(variables('mgScope'), 'Microsoft.Authorization/policyDefinitions', variables('policyDefinitionName'))]"
      },
      "dependsOn": [
        "[format('Microsoft.Authorization/policyDefinitions/{0}', variables('policyDefinitionName'))]"
      ]
    }
  ]
}

Определения встроенных политик — это ресурсы уровня клиента. Пример развертывания определения встроенной политики см. в разделе tenantResourceId.

list*

list{Value}(resourceName or resourceIdentifier, apiVersion, functionValues)

Синтаксис для этой функции зависит от имени из списка операций. Каждая реализация возвращает значения для типа ресурса, который поддерживает операцию list. Имя операции должно начинаться с list и может иметь суффикс. Наиболее распространенными вариантами применения являются list, listKeys, listKeyValue и listSecrets.

Параметры

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

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

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

При использовании с итерацией свойства можно использовать функции list для input, так как выражение назначается свойству ресурса. Их нельзя использовать с count, так как count должен быть определен до разрешения функции list.

Варианты реализации решения

Следующая таблица содержит возможные способы использования list*.

Тип ресурса Имя функции
Microsoft.Addons/supportProviders listsupportplaninfo
Microsoft.AnalysisServices/servers listGatewayStatus
Microsoft.ApiManagement/service/authorizationServers listSecrets
Microsoft.ApiManagement/service/gateways listKeys
Microsoft.ApiManagement/service/identityProviders listSecrets
Microsoft.ApiManagement/service/namedValues listValue
Microsoft.ApiManagement/service/openidConnectProviders listSecrets
Microsoft.ApiManagement/service/subscriptions listSecrets
Microsoft.AppConfiguration/configurationStores ListKeys
Microsoft.AppPlatform/Spring listTestKeys
Microsoft.Automation/automationAccounts listKeys
Microsoft.Batch/batchAccounts listkeys
Microsoft.BatchAI/workspaces/experiments/jobs listoutputfiles
Microsoft.Blockchain/blockchainMembers listApiKeys
Microsoft.Blockchain/blockchainMembers/transactionNodes listApiKeys
Microsoft.BotService/botServices/channels listChannelWithKeys
Microsoft.Cache/redis 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.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 listConnectionStrings
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/users ListEnvironments
Microsoft.LabServices/users ListLabs
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/authorizationRules listkeys
Microsoft.Relay/namespaces/disasterRecoveryConfigs/authorizationRules listkeys
Microsoft.Relay/namespaces/HybridConnections/authorizationRules listkeys
Microsoft.Relay/namespaces/WcfRelays/authorizationRules listkeys
Microsoft.Search/searchServices listAdminKeys
Microsoft.Search/searchServices listQueryKeys
Microsoft.ServiceBus/namespaces/authorizationRules listkeys
Microsoft.ServiceBus/namespaces/disasterRecoveryConfigs/authorizationRules listkeys
Microsoft.ServiceBus/namespaces/queues/authorizationRules listkeys
Microsoft.ServiceBus/namespaces/topics/authorizationRules listkeys
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

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

  • Просмотрите операции REST API для поставщика ресурсов и найдите операции list. Например, в учетных записях хранения есть операция listKeys.

  • Воспользуйтесь командлетом PowerShell Get-AzProviderOperation. В следующем примере извлекаются все операции list для учетных записей хранения:

    Get-AzProviderOperation -OperationSearchString "Microsoft.Storage/*" | where {$_.Operation -like "*list*"} | FT Operation
    
  • Используйте следующую команду Azure CLI, чтобы отфильтровать только операции list:

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

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

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

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

Другие функции list возвращают данные в других форматах. Чтобы просмотреть формат функции, включите ее в раздел outputs, как показано в примере шаблона.

Remarks

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

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

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

В следующем примере используется listKeys при задании значения для скриптов развертывания.

"storageAccountSettings": {
  "storageAccountName": "[variables('storageAccountName')]",
  "storageAccountKey": "[listKeys(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2019-06-01').keys[0].value]"
}

В следующем примере показана функция list, которая принимает параметр. В этом случае это функция listAccountSas. Передайте объект для времени окончания срока действия. Время окончания срока действия должно быть в будущем.

"parameters": {
  "accountSasProperties": {
    "type": "object",
    "defaultValue": {
      "signedServices": "b",
      "signedPermission": "r",
      "signedExpiry": "2020-08-20T11:00:00Z",
      "signedResourceTypes": "s"
    }
  }
},
...
"sasToken": "[listAccountSas(parameters('storagename'), '2018-02-01', parameters('accountSasProperties')).accountSasToken]"

pickZones

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

Определяет, поддерживает ли тип ресурса зоны для указанного расположения или региона. Эта функция поддерживает только зональные ресурсы, а избыточные между зонами службы, возвращают пустой массив. Дополнительные сведения см. в разделе Службы Azure, поддерживающие зоны доступности. Чтобы использовать функцию pickZones с избыточными между зонами службами, см. примеры ниже.

Параметры

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

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

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

[
    "1"
]

Если параметр numberOfZones имеет значение 3, возвращается:

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

Если тип или регион ресурса не поддерживает зоны, возвращается пустой массив. Избыточные между зонами службы также возвращают пустой массив.

[
]

Комментарии

Существуют разные категории для зон доступности Azure – зональные и избыточные между зонами. Функцию pickZones можно использовать для возврата номера зоны доступности или номеров для зональных ресурсов. Для служб, избыточных в зоне (ZRS), функция возвращает пустой массив. Зональные ресурсы обычно можно определить с помощью свойства zones в заголовке ресурса. Службы, избыточные в зонах, позволяют по-разному определять и использовать зоны доступности для каждого ресурса. Чтобы определить категорию поддержки для зон доступности, используйте документацию по нужной службе. Дополнительные сведения см. в разделе Службы Azure, поддерживающие зоны доступности.

Чтобы определить, поддерживает ли регион или расположение Azure зоны доступности, вызовите функцию pickZones() с типом зонального ресурса, например Microsoft.Storage/storageAccounts. Если ответное сообщение содержит значение, значит, регион поддерживает зоны доступности.

Пример pickZones

В следующем шаблоне показаны три результата использования функции pickZones.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {},
  "functions": [],
  "variables": {},
  "resources": [],
  "outputs": {
    "supported": {
      "type": "array",
      "value": "[pickZones('Microsoft.Compute', 'virtualMachines', 'westus2')]"
    },
    "notSupportedRegion": {
      "type": "array",
      "value": "[pickZones('Microsoft.Compute', 'virtualMachines', 'northcentralus')]"
    },
    "notSupportedType": {
      "type": "array",
      "value": "[pickZones('Microsoft.Cdn', 'profiles', 'westus2')]"
    }
  }
}

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

Имя Тип Значение
Поддерживается array [ "1" ]
notSupportedRegion array []
notSupportedType array []

Вы можете использовать ответ от pickZones, чтобы определить, следует ли предоставить значение NULL для зон или назначить виртуальные машины разным зонам. В следующем примере задается значение для зоны на основе доступности зон.

"zones": {
  "value": "[if(not(empty(pickZones('Microsoft.Compute', 'virtualMachines', 'westus2'))), string(add(mod(copyIndex(),3),1)), json('null'))]"
},

В следующем примере показано, как использовать функцию pickZones для включения избыточности между зонами для Cosmos DB.

"resources": [
  {
    "type": "Microsoft.DocumentDB/databaseAccounts",
    "apiVersion": "2021-04-15",
    "name": "[variables('accountName_var')]",
    "location": "[parameters('location')]",
    "kind": "GlobalDocumentDB",
    "properties": {
      "consistencyPolicy": "[variables('consistencyPolicy')[parameters('defaultConsistencyLevel')]]",
      "locations": [
        {
          "locationName": "[parameters('primaryRegion')]",
          "failoverPriority": 0,
          "isZoneRedundant": "[if(empty(pickZones('Microsoft.Storage', 'storageAccounts', parameters('primaryRegion'))), bool('false'), bool('true'))]",
        },
        {
          "locationName": "[parameters('secondaryRegion')]",
          "failoverPriority": 1,
          "isZoneRedundant": "[if(empty(pickZones('Microsoft.Storage', 'storageAccounts', parameters('secondaryRegion'))), bool('false'), bool('true'))]",
        }
      ],
      "databaseAccountOfferType": "Standard",
      "enableAutomaticFailover": "[parameters('automaticFailover')]"
    }
  }
]

providers

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

reference

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

Возвращает объект, представляющий состояние среды выполнения ресурса.

Параметры

Параметр Обязательно Тип Описание
имя_ресурса или идентификатор_ресурса Да строка Имя или уникальный идентификатор ресурса. При указании ссылки на ресурс в текущем шаблоне укажите в качестве параметра только имя ресурса. При указании ссылки на ранее развернутый ресурс или если имя ресурса неоднозначно, укажите идентификатор ресурса.
версия_API Нет строка Версия API для указанного ресурса. Этот параметр является обязательным, если ресурс не подготовлен в рамках того же шаблона. Как правило, указывается в формате гггг-мм-дд. Действительные версии API своего ресурса можно посмотреть в справочнике по шаблонам.
Full Нет строка Значение, указывающее, следует ли возвращать полный объект ресурса. Если вы не укажете 'Full', возвращается только объект свойств ресурса. Полный объект включает такие значения, как идентификатор ресурса и расположение.

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

Каждый тип ресурса возвращает для функции reference разные свойства. Функция не возвращает данные в едином предварительно заданном формате. Кроме того, возвращаемое значение отличается в зависимости от значения аргумента 'Full'. Чтобы просмотреть свойства для типа ресурса, возвратите объект в разделе outputs, как показано в примере.

Remarks

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

Обычно функция reference используется, чтобы получить определенное значение из объекта, например универсальный код ресурса (URI) конечной точки большого двоичного объекта или полное доменное имя.

"outputs": {
  "BlobUri": {
    "type": "string",
    "value": "[reference(resourceId('Microsoft.Storage/storageAccounts', parameters('storageAccountName'))).primaryEndpoints.blob]"
  },
  "FQDN": {
    "type": "string",
    "value": "[reference(resourceId('Microsoft.Network/publicIPAddresses', parameters('ipAddressName'))).dnsSettings.fqdn]"
  }
}

Используйте 'Full', если вам нужны значения ресурсов, которые не являются частью схемы свойств. Например, чтобы задать политику доступа к хранилищу ключей, получите свойства идентификатора для виртуальной машины.

{
  "type": "Microsoft.KeyVault/vaults",
  "apiVersion": "2019-09-01",
  "name": "vaultName",
  "properties": {
    "tenantId": "[subscription().tenantId]",
    "accessPolicies": [
      {
        "tenantId": "[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')), '2019-03-01', 'Full').identity.tenantId]",
        "objectId": "[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')), '2019-03-01', 'Full').identity.principalId]",
        "permissions": {
          "keys": [
            "all"
          ],
          "secrets": [
            "all"
          ]
        }
      }
    ],
    ...

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

Эталонную функцию можно использовать только в свойствах определения ресурса и в разделе выходных данных шаблона или развертывания. При использовании с итерацией свойства можно использовать функцию reference для input, так как выражение назначается свойству ресурса.

Нельзя использовать функцию reference для задания значения свойства count в цикле копирования. Можно использовать для задания других свойств в цикле. Функция reference заблокирована для свойства count, так как это свойство должно быть определено до разрешения функции reference.

Чтобы использовать функцию reference или любую функцию list* в разделе outputs вложенного шаблона, необходимо задать для параметра значение expressionEvaluationOptions, чтобы использовать оценку внутренней области, или использовать ссылку вместо вложенного шаблона.

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

Неявная зависимость

С помощью функции reference вы прямо объявляете, что один ресурс зависит от другого, если ресурс, на который указывает ссылка, предоставляется в том же шаблоне и вы ссылаетесь, используя его имя (а не идентификатор). При этом свойство dependsOn использовать не нужно. Расчет функции выполняется только после развертывания ресурса, на который указывает ссылка.

Имя или идентификатор ресурса

При ссылке на ресурс, развернутый в том же шаблоне, укажите имя ресурса.

"value": "[reference(parameters('storageAccountName'))]"

При ссылке на ресурс, который не развернут в том же шаблоне, укажите идентификатор ресурса и apiVersion.

"value": "[reference(resourceId(parameters('storageResourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('storageAccountName')), '2018-07-01')]"

Чтобы избежать неоднозначности в отношении ресурса, на который вы ссылаетесь, можно указать полный идентификатор ресурса.

"value": "[reference(resourceId('Microsoft.Network/publicIPAddresses', parameters('ipAddressName')))]"

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

{resource-provider-namespace}/{parent-resource-type}/{parent-resource-name}[/{child-resource-type}/{child-resource-name}]

Пример:

Microsoft.Compute/virtualMachines/myVM/extensions/myExt — правильно, Microsoft.Compute/virtualMachines/extensions/myVM/myExt — неправильно.

Чтобы упростить создание любого идентификатора ресурса, вместо функции concat() используйте функции resourceId(), описанные в этом документе.

Получение управляемого удостоверения

Управляемые удостоверения для ресурсов Azure являются типами ресурсов расширения, которые создаются неявно для некоторых ресурсов. Так как управляемое удостоверение не определено явным образом в шаблоне, необходимо указать ссылку на ресурс, к которому применяется удостоверение. Используйте Full, чтобы получить все свойства, включая явно созданное удостоверение.

Шаблон:

"[reference(resourceId(<resource-provider-namespace>, <resource-name>), <API-version>, 'Full').Identity.propertyName]"

Например, чтобы получить идентификатор субъекта для управляемого удостоверения, применяемого к виртуальной машине, используйте следующий формат:

"[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')),'2019-12-01', 'Full').identity.principalId]",

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

"[reference(resourceId('Microsoft.Compute/virtualMachineScaleSets',  variables('vmNodeType0Name')), 2019-12-01, 'Full').Identity.tenantId]"

Пример ссылки

В следующем примере выполняется развертывание ресурса и ссылка на этот ресурс.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageAccountName": {
      "type": "string"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2021-04-01",
      "name": "[parameters('storageAccountName')]",
      "location": "[resourceGroup().location]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "tags": {},
      "properties": {
      }
    }
  ],
  "outputs": {
    "referenceOutput": {
      "type": "object",
      "value": "[reference(parameters('storageAccountName'))]"
    },
    "fullReferenceOutput": {
      "type": "object",
      "value": "[reference(parameters('storageAccountName'), '2021-04-01', 'Full')]"
    }
  }
}

В предыдущем примере возвращаются два объекта. Объект свойств имеет следующий формат:

{
   "creationTime": "2017-10-09T18:55:40.5863736Z",
   "primaryEndpoints": {
     "blob": "https://examplestorage.blob.core.windows.net/",
     "file": "https://examplestorage.file.core.windows.net/",
     "queue": "https://examplestorage.queue.core.windows.net/",
     "table": "https://examplestorage.table.core.windows.net/"
   },
   "primaryLocation": "southcentralus",
   "provisioningState": "Succeeded",
   "statusOfPrimary": "available",
   "supportsHttpsTrafficOnly": false
}

Полный объект имеет следующий формат:

{
  "apiVersion":"2021-04-01",
  "location":"southcentralus",
  "sku": {
    "name":"Standard_LRS",
    "tier":"Standard"
  },
  "tags":{},
  "kind":"Storage",
  "properties": {
    "creationTime":"2017-10-09T18:55:40.5863736Z",
    "primaryEndpoints": {
      "blob":"https://examplestorage.blob.core.windows.net/",
      "file":"https://examplestorage.file.core.windows.net/",
      "queue":"https://examplestorage.queue.core.windows.net/",
      "table":"https://examplestorage.table.core.windows.net/"
    },
    "primaryLocation":"southcentralus",
    "provisioningState":"Succeeded",
    "statusOfPrimary":"available",
    "supportsHttpsTrafficOnly":false
  },
  "subscriptionId":"<subscription-id>",
  "resourceGroupName":"functionexamplegroup",
  "resourceId":"Microsoft.Storage/storageAccounts/examplestorage",
  "referenceApiVersion":"2021-04-01",
  "condition":true,
  "isConditionTrue":true,
  "isTemplateResource":false,
  "isAction":false,
  "provisioningOperation":"Read"
}

Следующий пример шаблона ссылается на учетную запись хранения, которая не развертывается в этом шаблоне. Учетная запись хранения уже имеется в той же подписке.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageResourceGroup": {
      "type": "string"
    },
    "storageAccountName": {
      "type": "string"
    }
  },
  "resources": [],
  "outputs": {
    "ExistingStorage": {
      "type": "object",
      "value": "[reference(resourceId(parameters('storageResourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('storageAccountName')), '2021-04-01')]"
    }
  }
}

resourceGroup

resourceGroup()

Возвращает объект, который представляет текущую группу ресурсов.

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

Возвращаемый объект имеет следующий формат:

{
  "id": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}",
  "name": "{resourceGroupName}",
  "type":"Microsoft.Resources/resourceGroups",
  "location": "{resourceGroupLocation}",
  "managedBy": "{identifier-of-managing-resource}",
  "tags": {
  },
  "properties": {
    "provisioningState": "{status}"
  }
}

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

Remarks

Функцию resourceGroup() нельзя использовать в шаблоне, который развернут на уровне подписки. Ее можно использовать только в шаблонах, развернутых в группе ресурсов. Функцию resourceGroup() можно использовать в связанном или вложенном шаблоне (с внутренней областью), предназначенном для группы ресурсов, даже если родительский шаблон развертывается в подписке. В этом сценарии связанный или вложенный шаблон развертывается на уровне группы ресурсов. Дополнительные сведения о нацеливании на группу ресурсов в развертывании уровня подписки см. в разделе Развертывание ресурсов Azure в нескольких подписках или группах ресурсов.

Как правило, функция resourceGroup используется для создания ресурсов в одном расположении с группой ресурсов. В следующем примере расположение группы ресурсов используется в качестве значения параметра по умолчанию.

"parameters": {
  "location": {
    "type": "string",
    "defaultValue": "[resourceGroup().location]"
  }
}

Кроме того, функцию resourceGroup можно использовать для применения к ресурсу тегов из группы ресурсов. Дополнительные сведения см. в разделе Применение тегов из группы ресурсов.

При использовании вложенных шаблонов для развертывания в нескольких группах ресурсов можно указать область для вычисления функции resourceGroup. Дополнительные сведения см. в разделе Развертывание ресурсов Azure в нескольких подписках или группах ресурсов.

Пример группы ресурсов

В следующем примере возвращаются свойства группы ресурсов.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "resourceGroupOutput": {
      "type": "object",
      "value": "[resourceGroup()]"
    }
  }
}

В предыдущем примере возвращается объект в следующем формате:

{
  "id": "/subscriptions/{subscription-id}/resourceGroups/examplegroup",
  "name": "examplegroup",
  "type":"Microsoft.Resources/resourceGroups",
  "location": "southcentralus",
  "properties": {
    "provisioningState": "Succeeded"
  }
}

resourceId

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

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

Параметры

Параметр Обязательно Тип Описание
subscriptionId Нет строка (в формате GUID) Значение по умолчанию — текущая подписка. Укажите это значение, если нужно получить ресурс из другой подписки. Это значение предоставляется только при развертывании в области действия группы ресурсов или подписки.
имя_группы_ресурсов Нет строка Значение по умолчанию — текущая группа ресурсов. Укажите это значение, если нужно получить ресурс из другой группы ресурсов. Это значение предоставляется только при развертывании в области действия группы ресурсов.
тип_ресурса Да строка Тип ресурса, включая пространство имен поставщика ресурсов.
имя_ресурса1 Да строка Имя ресурса.
имя_ресурса2 Нет строка Следующий сегмент имени ресурса, если он необходим.

Продолжайте добавлять имена ресурсов в качестве параметров, если тип ресурса включает больше сегментов.

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

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

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

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

Если при развертывании в подписке используется resourceId, идентификатор ресурса возвращается в следующем формате:

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

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

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

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

Для ресурсов уровня подписки используйте функцию subscriptionResourceId.

Для ресурсов уровня группы управления используйте функцию extensionResourceId для ссылки на ресурс, реализованный как расширение группы управления. Например, определения настраиваемой политики, развернутые в группе управления, являются расширениями группы управления. Используйте функцию tenantResourceId для ссылки на ресурсы, развернутые в клиенте, но доступные в группе управления. Например, встроенные определения политик реализуются как ресурсы уровня клиента.

Для ресурсов на уровне клиента используйте функцию tenantResourceId. Используйте tenantResourceId для встроенных определений политик, так как они реализуются на уровне клиента.

Remarks

Количество предоставляемых параметров зависит от того, является ли ресурс родительским или дочерним, а также находится ли ресурс в той же подписке или группе ресурсов.

Чтобы получить идентификатор ресурса для родительского ресурса в той же подписке и группе ресурсов, укажите тип и имя ресурса.

"[resourceId('Microsoft.ServiceBus/namespaces', 'namespace1')]"

При получении идентификатора ресурса для дочернего ресурса обратите внимание на количество сегментов в типе ресурса. Укажите имя ресурса для каждого сегмента типа ресурса. Имя сегмента соответствует ресурсу, который существует для этой части иерархии.

"[resourceId('Microsoft.ServiceBus/namespaces/queues/authorizationRules', 'namespace1', 'queue1', 'auth1')]"

Чтобы получить идентификатор ресурса в той же подписке, но в другой группе ресурсов, укажите имя группы ресурсов.

"[resourceId('otherResourceGroup', 'Microsoft.Storage/storageAccounts', 'examplestorage')]"

Чтобы получить идентификатор ресурса в другой подписке и группе ресурсов, укажите идентификатор подписки и имя группы ресурсов.

"[resourceId('xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', 'otherResourceGroup', 'Microsoft.Storage/storageAccounts','examplestorage')]"

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string"
    },
    "virtualNetworkName": {
      "type": "string"
    },
    "virtualNetworkResourceGroup": {
      "type": "string"
    },
    "subnet1Name": {
      "type": "string"
    },
    "nicName": {
      "type": "string"
    }
  },
  "variables": {
    "subnet1Ref": "[resourceId(parameters('virtualNetworkResourceGroup'), 'Microsoft.Network/virtualNetworks/subnets', parameters('virtualNetworkName'), parameters('subnet1Name'))]"
  },
  "resources": [
    {
      "type": "Microsoft.Network/networkInterfaces",
      "apiVersion": "2021-02-01",
      "name": "[parameters('nicName')]",
      "location": "[parameters('location')]",
      "properties": {
        "ipConfigurations": [
          {
            "name": "ipconfig1",
            "properties": {
              "privateIPAllocationMethod": "Dynamic",
              "subnet": {
                "id": "[variables('subnet1Ref')]"
              }
            }
          }
        ]
      }
    }
  ]
}

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

Следующий пример возвращает идентификатор ресурса для учетной записи хранения в группе ресурсов:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "sameRGOutput": {
      "type": "string",
      "value": "[resourceId('Microsoft.Storage/storageAccounts','examplestorage')]"
    },
    "differentRGOutput": {
      "type": "string",
      "value": "[resourceId('otherResourceGroup', 'Microsoft.Storage/storageAccounts','examplestorage')]"
    },
    "differentSubOutput": {
      "type": "string",
      "value": "[resourceId('11111111-1111-1111-1111-111111111111', 'otherResourceGroup', 'Microsoft.Storage/storageAccounts','examplestorage')]"
    },
    "nestedResourceOutput": {
      "type": "string",
      "value": "[resourceId('Microsoft.SQL/servers/databases', 'serverName', 'databaseName')]"
    }
  }
}

Выходные данные из предыдущего примера со значениями по умолчанию:

Имя Тип Значение
sameRGOutput Строка /subscriptions/{ИД_текущей_подписки}/resourceGroups/examplegroup/providers/Microsoft.Storage/storageAccounts/examplestorage
differentRGOutput Строка /subscriptions/{ИД_текущей_подписки}/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage
differentSubOutput Строка /subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage
nestedResourceOutput Строка /subscriptions/{ИД_текущей_подписки}/resourceGroups/examplegroup/providers/Microsoft.SQL/servers/serverName/databases/databaseName

Подписка

subscription()

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

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

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

{
  "id": "/subscriptions/{subscription-id}",
  "subscriptionId": "{subscription-id}",
  "tenantId": "{tenant-id}",
  "displayName": "{name-of-subscription}"
}

Remarks

При использовании вложенных шаблонов для развертывания в нескольких подписках можно указать область для вычисления функции subscription. Дополнительные сведения см. в разделе Развертывание ресурсов Azure в нескольких подписках или группах ресурсов.

Пример подписки

В следующем примере показана функция subscription, вызываемая в разделе выходных данных.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "subscriptionOutput": {
      "type": "object",
      "value": "[subscription()]"
    }
  }
}

subscriptionResourceId

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

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

Параметры

Параметр Обязательно Тип Описание
subscriptionId Нет строка (в формате GUID) Значение по умолчанию — текущая подписка. Укажите это значение, если нужно получить ресурс из другой подписки.
тип_ресурса Да строка Тип ресурса, включая пространство имен поставщика ресурсов.
имя_ресурса1 Да строка Имя ресурса.
имя_ресурса2 Нет строка Следующий сегмент имени ресурса, если он необходим.

Продолжайте добавлять имена ресурсов в качестве параметров, если тип ресурса включает больше сегментов.

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

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

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

Remarks

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

Пример subscriptionResourceID

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "principalId": {
      "type": "string",
      "metadata": {
        "description": "The principal to assign the role to"
      }
    },
    "builtInRoleType": {
      "type": "string",
      "allowedValues": [
        "Owner",
        "Contributor",
        "Reader"
      ],
      "metadata": {
        "description": "Built-in role to assign"
      }
    },
    "roleNameGuid": {
      "type": "string",
      "defaultValue": "[newGuid()]",
      "metadata": {
        "description": "A new GUID used to identify the role assignment"
      }
    }
  },
  "variables": {
    "Owner": "[subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8e3af657-a8ff-443c-a75c-2fe8c4bcb635')]",
    "Contributor": "[subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b24988ac-6180-42a0-ab88-20f7382dd24c')]",
    "Reader": "[subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'acdd72a7-3385-48ef-bd42-f606fba81ae7')]"
  },
  "resources": [
    {
      "type": "Microsoft.Authorization/roleAssignments",
      "apiVersion": "2020-10-01-preview",
      "name": "[parameters('roleNameGuid')]",
      "properties": {
        "roleDefinitionId": "[variables(parameters('builtInRoleType'))]",
        "principalId": "[parameters('principalId')]"
      }
    }
  ]
}

tenantResourceId

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

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

Параметры

Параметр Обязательно Тип Описание
тип_ресурса Да строка Тип ресурса, включая пространство имен поставщика ресурсов.
имя_ресурса1 Да строка Имя ресурса.
имя_ресурса2 Нет строка Следующий сегмент имени ресурса, если он необходим.

Продолжайте добавлять имена ресурсов в качестве параметров, если тип ресурса включает больше сегментов.

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

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

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

Remarks

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

Пример tenantResourceId

Определения встроенных политик — это ресурсы уровня клиента. Чтобы развернуть назначение политики, ссылающееся на определение встроенной политики, используйте tenantResourceId функцию.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "policyDefinitionID": {
      "type": "string",
      "defaultValue": "0a914e76-4921-4c19-b460-a2d36003525a",
      "metadata": {
        "description": "Specifies the ID of the policy definition or policy set definition being assigned."
      }
    },
    "policyAssignmentName": {
      "type": "string",
      "defaultValue": "[guid(parameters('policyDefinitionID'), resourceGroup().name)]",
      "metadata": {
        "description": "Specifies the name of the policy assignment, can be used defined or an idempotent name as the defaultValue provides."
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.Authorization/policyAssignments",
      "name": "[parameters('policyAssignmentName')]",
      "apiVersion": "2020-09-01",
      "properties": {
        "scope": "[subscriptionResourceId('Microsoft.Resources/resourceGroups', resourceGroup().name)]",
        "policyDefinitionId": "[tenantResourceId('Microsoft.Authorization/policyDefinitions', parameters('policyDefinitionID'))]"
      }
    }
  ]
}

Дальнейшие действия