Функции для работы с ресурсами в шаблонах Azure Resource ManagerResource functions for Azure Resource Manager templates

Диспетчер ресурсов предоставляет следующие функции для получения значений ресурсов:Resource Manager provides the following functions for getting resource values:

Получение значений параметров, переменных или текущего развертывания описано в разделе Функции для параметров развертывания.To get values from parameters, variables, or the current deployment, see Deployment value functions.

list*list*

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

Синтаксис для этой функции зависит от имени из списка операций.The syntax for this function varies by name of the list operations. Каждая реализация возвращает значения для типа ресурса, который поддерживает операцию list.Each implementation returns values for the resource type that supports a list operation. Имя операции должно начинаться с list.The operation name must start with list. Наиболее распространенными вариантами применения являются listKeys и listSecrets.Some common usages are listKeys and listSecrets.

ПараметрыParameters

ПараметрParameter Обязательное значениеRequired ТипType ОписаниеDescription
имя_ресурса или идентификатор_ресурсаresourceName or resourceIdentifier ДаYes строкаstring Уникальный идентификатор ресурса.Unique identifier for the resource.
версия_APIapiVersion ДаYes строкаstring Версия API для состояния среды выполнения ресурса.API version of resource runtime state. Как правило, указывается в формате гггг-мм-дд.Typically, in the format, yyyy-mm-dd.
functionValuesfunctionValues НетNo объектobject Объект, содержащий значения для функции.An object that has values for the function. Предоставляйте этот объект только для функций, которые поддерживают прием объекта с параметрами, например listAccountSas в учетной записи хранения.Only provide this object for functions that support receiving an object with parameter values, such as listAccountSas on a storage account. В этой статье показан пример передачи значения функции.An example of passing function values is shown in this article.

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

Следующая таблица содержит возможные способы использования list*.The possible uses of list* are shown in the following table.

Тип ресурсаResource type Имя функцииFunction name
Microsoft.AnalysisServices/serversMicrosoft.AnalysisServices/servers listGatewayStatuslistGatewayStatus
Microsoft. Аппконфигуратион/КонфигуратионсторесMicrosoft.AppConfiguration/configurationStores ListKeysListKeys
Microsoft.Automation/automationAccountsMicrosoft.Automation/automationAccounts listKeyslistKeys
Microsoft.Batch/batchAccountsMicrosoft.Batch/batchAccounts listkeyslistkeys
Microsoft.BatchAI/workspaces/experiments/jobsMicrosoft.BatchAI/workspaces/experiments/jobs listoutputfileslistoutputfiles
Microsoft. Блокчейн/БлоккчаинмемберсMicrosoft.Blockchain/blockchainMembers листапикэйсlistApiKeys
Microsoft. Блокчейн/Блоккчаинмемберс/ТрансактионнодесMicrosoft.Blockchain/blockchainMembers/transactionNodes листапикэйсlistApiKeys
Microsoft. Ботсервице/Ботсервицес/каналыMicrosoft.BotService/botServices/channels листчаннелвискэйсlistChannelWithKeys
Microsoft.Cache/redisMicrosoft.Cache/redis listKeyslistKeys
Microsoft.CognitiveServices/accountsMicrosoft.CognitiveServices/accounts listKeyslistKeys
Microsoft.ContainerRegistry/registriesMicrosoft.ContainerRegistry/registries listBuildSourceUploadUrllistBuildSourceUploadUrl
Microsoft.ContainerRegistry/registriesMicrosoft.ContainerRegistry/registries listCredentialslistCredentials
Microsoft.ContainerRegistry/registriesMicrosoft.ContainerRegistry/registries listPolicieslistPolicies
Microsoft.ContainerRegistry/registriesMicrosoft.ContainerRegistry/registries listUsageslistUsages
Microsoft.ContainerRegistry/registries/webhooksMicrosoft.ContainerRegistry/registries/webhooks listEventslistEvents
Microsoft. ContainerRegistry/реестров/запускиMicrosoft.ContainerRegistry/registries/runs листлогсасурлlistLogSasUrl
Microsoft. ContainerRegistry/реестра/задачиMicrosoft.ContainerRegistry/registries/tasks листдетаилсlistDetails
Microsoft.ContainerService/managedClustersMicrosoft.ContainerService/managedClusters listClusterAdminCredentiallistClusterAdminCredential
Microsoft.ContainerService/managedClustersMicrosoft.ContainerService/managedClusters listClusterUserCredentiallistClusterUserCredential
Microsoft. ContainerService/Манажедклустерс/АкцесспрофилесMicrosoft.ContainerService/managedClusters/accessProfiles листкредентиалlistCredential
Microsoft. Датабокс/заданияMicrosoft.DataBox/jobs листкредентиалсlistCredentials
Microsoft.DataFactory/datafactories/gatewaysMicrosoft.DataFactory/datafactories/gateways listauthkeyslistauthkeys
Microsoft.DataFactory/factories/integrationruntimesMicrosoft.DataFactory/factories/integrationruntimes listauthkeyslistauthkeys
Microsoft.DataLakeAnalytics/accounts/storageAccounts/ContainersMicrosoft.DataLakeAnalytics/accounts/storageAccounts/Containers listSasTokenslistSasTokens
Microsoft.Devices/iotHubsMicrosoft.Devices/iotHubs listkeyslistkeys
Microsoft.Devices/provisioningServices/keysMicrosoft.Devices/provisioningServices/keys listkeyslistkeys
Microsoft.Devices/provisioningServicesMicrosoft.Devices/provisioningServices listkeyslistkeys
Microsoft.DevTestLab/labsMicrosoft.DevTestLab/labs ListVhdsListVhds
Microsoft.DevTestLab/labs/schedulesMicrosoft.DevTestLab/labs/schedules ListApplicableListApplicable
Microsoft.DevTestLab/labs/users/serviceFabricsMicrosoft.DevTestLab/labs/users/serviceFabrics ListApplicableSchedulesListApplicableSchedules
Microsoft.DevTestLab/labs/virtualMachinesMicrosoft.DevTestLab/labs/virtualMachines ListApplicableSchedulesListApplicableSchedules
Microsoft.DocumentDB/databaseAccountsMicrosoft.DocumentDB/databaseAccounts listConnectionStringslistConnectionStrings
Microsoft.DocumentDB/databaseAccountsMicrosoft.DocumentDB/databaseAccounts listKeyslistKeys
Microsoft.DomainRegistrationMicrosoft.DomainRegistration listDomainRecommendationslistDomainRecommendations
Microsoft.DomainRegistration/topLevelDomainsMicrosoft.DomainRegistration/topLevelDomains listAgreementslistAgreements
Microsoft. EventGrid/DomainsMicrosoft.EventGrid/domains listKeyslistKeys
Microsoft.EventGrid/topicsMicrosoft.EventGrid/topics listKeyslistKeys
Microsoft.EventHub/namespaces/authorizationRulesMicrosoft.EventHub/namespaces/authorizationRules listkeyslistkeys
Microsoft.EventHub/namespaces/disasterRecoveryConfigs/authorizationRulesMicrosoft.EventHub/namespaces/disasterRecoveryConfigs/authorizationRules listkeyslistkeys
Microsoft.EventHub/namespaces/eventhubs/authorizationRulesMicrosoft.EventHub/namespaces/eventhubs/authorizationRules listkeyslistkeys
Microsoft.ImportExport/jobsMicrosoft.ImportExport/jobs listBitLockerKeyslistBitLockerKeys
Microsoft. Лабсервицес/пользователиMicrosoft.LabServices/users листенвиронментсListEnvironments
Microsoft. Лабсервицес/пользователиMicrosoft.LabServices/users листлабсListLabs
Microsoft.Logic/integrationAccounts/agreementsMicrosoft.Logic/integrationAccounts/agreements listContentCallbackUrllistContentCallbackUrl
Microsoft.Logic/integrationAccounts/assembliesMicrosoft.Logic/integrationAccounts/assemblies listContentCallbackUrllistContentCallbackUrl
Microsoft.Logic/integrationAccountsMicrosoft.Logic/integrationAccounts listCallbackUrllistCallbackUrl
Microsoft.Logic/integrationAccountsMicrosoft.Logic/integrationAccounts listKeyVaultKeyslistKeyVaultKeys
Microsoft.Logic/integrationAccounts/mapsMicrosoft.Logic/integrationAccounts/maps listContentCallbackUrllistContentCallbackUrl
Microsoft.Logic/integrationAccounts/partnersMicrosoft.Logic/integrationAccounts/partners listContentCallbackUrllistContentCallbackUrl
Microsoft.Logic/integrationAccounts/schemasMicrosoft.Logic/integrationAccounts/schemas listContentCallbackUrllistContentCallbackUrl
Microsoft.Logic/workflowsMicrosoft.Logic/workflows listCallbackUrllistCallbackUrl
Microsoft.Logic/workflowsMicrosoft.Logic/workflows listSwaggerlistSwagger
Microsoft. Logic/рабочие процессы/триггерыMicrosoft.Logic/workflows/triggers listCallbackUrllistCallbackUrl
Microsoft. Logic/рабочие процессы/версии/триггерыMicrosoft.Logic/workflows/versions/triggers listCallbackUrllistCallbackUrl
Microsoft.MachineLearning/webServicesMicrosoft.MachineLearning/webServices listkeyslistkeys
Microsoft.MachineLearning/WorkspacesMicrosoft.MachineLearning/Workspaces listworkspacekeyslistworkspacekeys
Microsoft.MachineLearningServices/workspaces/computesMicrosoft.MachineLearningServices/workspaces/computes listKeyslistKeys
Microsoft.MachineLearningServices/workspacesMicrosoft.MachineLearningServices/workspaces listKeyslistKeys
Microsoft.Maps/accountsMicrosoft.Maps/accounts listKeyslistKeys
Microsoft.Media/mediaservices/assetsMicrosoft.Media/mediaservices/assets listContainerSaslistContainerSas
Microsoft.Media/mediaservices/assetsMicrosoft.Media/mediaservices/assets listStreamingLocatorslistStreamingLocators
Microsoft.Media/mediaservices/streamingLocatorsMicrosoft.Media/mediaservices/streamingLocators listContentKeyslistContentKeys
Microsoft.Media/mediaservices/streamingLocatorsMicrosoft.Media/mediaservices/streamingLocators listPathslistPaths
Microsoft. Network/АппликатионсекуритиграупсMicrosoft.Network/applicationSecurityGroups листипконфигуратионсlistIpConfigurations
Microsoft.NotificationHubs/Namespaces/authorizationRulesMicrosoft.NotificationHubs/Namespaces/authorizationRules listkeyslistkeys
Microsoft.NotificationHubs/Namespaces/NotificationHubs/authorizationRulesMicrosoft.NotificationHubs/Namespaces/NotificationHubs/authorizationRules listkeyslistkeys
Microsoft.OperationalInsights/workspacesMicrosoft.OperationalInsights/workspaces listKeyslistKeys
Microsoft.Relay/namespaces/authorizationRulesMicrosoft.Relay/namespaces/authorizationRules listkeyslistkeys
Microsoft. Relay/Namespaces/Дисастеррековериконфигс/authorizationRulesMicrosoft.Relay/namespaces/disasterRecoveryConfigs/authorizationRules listkeyslistkeys
Microsoft.Relay/namespaces/HybridConnections/authorizationRulesMicrosoft.Relay/namespaces/HybridConnections/authorizationRules listkeyslistkeys
Microsoft.Relay/namespaces/WcfRelays/authorizationRulesMicrosoft.Relay/namespaces/WcfRelays/authorizationRules listkeyslistkeys
Microsoft.Search/searchServicesMicrosoft.Search/searchServices listAdminKeyslistAdminKeys
Microsoft.Search/searchServicesMicrosoft.Search/searchServices listQueryKeyslistQueryKeys
Microsoft.ServiceBus/namespaces/authorizationRulesMicrosoft.ServiceBus/namespaces/authorizationRules listkeyslistkeys
Microsoft.ServiceBus/namespaces/disasterRecoveryConfigs/authorizationRulesMicrosoft.ServiceBus/namespaces/disasterRecoveryConfigs/authorizationRules listkeyslistkeys
Microsoft.ServiceBus/namespaces/queues/authorizationRulesMicrosoft.ServiceBus/namespaces/queues/authorizationRules listkeyslistkeys
Microsoft.ServiceBus/namespaces/topics/authorizationRulesMicrosoft.ServiceBus/namespaces/topics/authorizationRules listkeyslistkeys
Microsoft.SignalRService/SignalRMicrosoft.SignalRService/SignalR listkeyslistkeys
Microsoft.Storage/storageAccountsMicrosoft.Storage/storageAccounts listAccountSaslistAccountSas
Microsoft.Storage/storageAccountsMicrosoft.Storage/storageAccounts listkeyslistkeys
Microsoft.Storage/storageAccountsMicrosoft.Storage/storageAccounts listServiceSaslistServiceSas
Microsoft.StorSimple/managers/devicesMicrosoft.StorSimple/managers/devices listFailoverSetslistFailoverSets
Microsoft.StorSimple/managers/devicesMicrosoft.StorSimple/managers/devices listFailoverTargetslistFailoverTargets
Microsoft.StorSimple/managersMicrosoft.StorSimple/managers listActivationKeylistActivationKey
Microsoft.StorSimple/managersMicrosoft.StorSimple/managers listPublicEncryptionKeylistPublicEncryptionKey
Microsoft.Web/connectionGatewaysMicrosoft.Web/connectionGateways ListStatusListStatus
microsoft.web/connectionsmicrosoft.web/connections listconsentlinkslistconsentlinks
Microsoft.Web/customApisMicrosoft.Web/customApis listWsdlInterfaceslistWsdlInterfaces
microsoft.web/locationsmicrosoft.web/locations listwsdlinterfaceslistwsdlinterfaces
Microsoft. Web/апиманажементаккаунтс/API/подключенияmicrosoft.web/apimanagementaccounts/apis/connections листконнектионкэйсlistconnectionkeys
Microsoft. Web/апиманажементаккаунтс/API/подключенияmicrosoft.web/apimanagementaccounts/apis/connections листсекретсlistsecrets
microsoft.web/sites/functionsmicrosoft.web/sites/functions listsecretslistsecrets
microsoft.web/sites/hybridconnectionnamespaces/relaysmicrosoft.web/sites/hybridconnectionnamespaces/relays listkeyslistkeys
microsoft.web/sitesmicrosoft.web/sites listsyncfunctiontriggerstatuslistsyncfunctiontriggerstatus
microsoft.web/sites/slots/functionsmicrosoft.web/sites/slots/functions listsecretslistsecrets

Чтобы определить, какие типы ресурсов поддерживают операцию list, можно использовать следующие варианты:To determine which resource types have a list operation, you have the following options:

  • Просмотрите операции REST API для поставщика ресурсов и найдите операции list.View the REST API operations for a resource provider, and look for list operations. Например, в учетных записях хранения есть операция listKeys.For example, storage accounts have the listKeys operation.

  • Воспользуйтесь командлетом PowerShell Get-AzProviderOperation.Use the Get-AzProviderOperation PowerShell cmdlet. В следующем примере извлекаются все операции list для учетных записей хранения:The following example gets all list operations for storage accounts:

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

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

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

Возвращаемый объект зависит от используемой функции списка.The returned object varies by the list function you use. Например, listKeys для учетной записи хранения возвращает следующий формат.For example, the listKeys for a storage account returns the following format:

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

Другие функции list возвращают данные в других форматах.Other list functions have different return formats. Чтобы просмотреть формат функции, включите ее в раздел outputs, как показано в примере шаблона.To see the format of a function, include it in the outputs section as shown in the example template.

ПримечанияRemarks

Укажите ресурс с помощью его имени или функции resourceId.Specify the resource by using either the resource name or the resourceId function. Если эта функция списка задана в том же шаблоне, с помощью которого выполняется развертывание ресурса, на который указывает ссылка, следует использовать имя ресурса.When using a list function in the same template that deploys the referenced resource, use the resource name.

При использовании функции List в ресурсе, который условно развернут, функция вычисляется, даже если ресурс не развернут.If you use a list function in a resource that is conditionally deployed, the function is evaluated even if the resource isn't deployed. Если функция List ссылается на несуществующий ресурс, возникает ошибка.You get an error if the list function refers to a resource that doesn't exist. Используйте функцию If , чтобы убедиться, что функция вычисляется только при развертывании ресурса.Use the if function to make sure the function is only evaluated when the resource is being deployed. См. функцию if для примера шаблона, который использует if и List с условно развернутым ресурсом.See the if function for a sample template that uses if and list with a conditionally deployed resource.

ПримерExample

В следующем примере шаблона показано, как получить в разделе выходных данных первичный и вторичный ключи из учетной записи хранения.The following example template shows how to return the primary and secondary keys from a storage account in the outputs section. Он также возвращает маркер SAS для учетной записи хранения.It also returns a SAS token for the storage account.

Чтобы получить маркер SAS, передайте объект для времени окончания срока действия.To get the SAS token, pass an object for the expiry time. Время окончания срока действия должно быть в будущем.The expiry time must be in the future. В этом примере показано, как использовать функции перечисления.This example is intended to show how you use the list functions. Как правило, нужно использовать токен SAS в значении ресурса, а не возвращать его в качестве выходного значения.Typically, you would use the SAS token in a resource value rather than return it as an output value. Выходные значения хранятся в истории развертывания и не являются безопасными.Output values are stored in the deployment history and aren't secure.

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "storagename": {
            "type": "string"
        },
        "location": {
            "type": "string",
            "defaultValue": "southcentralus"
        },
        "accountSasProperties": {
            "type": "object",
            "defaultValue": {
                "signedServices": "b",
                "signedPermission": "r",
                "signedExpiry": "2018-08-20T11:00:00Z",
                "signedResourceTypes": "s"
            }
        }
    },
    "resources": [
        {
            "apiVersion": "2018-02-01",
            "name": "[parameters('storagename')]",
            "location": "[parameters('location')]",
            "type": "Microsoft.Storage/storageAccounts",
            "sku": {
                "name": "Standard_LRS"
            },
            "kind": "StorageV2",
            "properties": {
                "supportsHttpsTrafficOnly": false,
                "accessTier": "Hot",
                "encryption": {
                    "services": {
                        "blob": {
                            "enabled": true
                        },
                        "file": {
                            "enabled": true
                        }
                    },
                    "keySource": "Microsoft.Storage"
                }
            },
            "dependsOn": []
        }
    ],
    "outputs": {
        "keys": {
            "type": "object",
            "value": "[listKeys(parameters('storagename'), '2018-02-01')]"
        },
        "accountSAS": {
            "type": "object",
            "value": "[listAccountSas(parameters('storagename'), '2018-02-01', parameters('accountSasProperties'))]"
        }
    }
}

providersproviders

providers(providerNamespace, [resourceType])

Возвращает сведения о поставщике ресурсов и поддерживаемых типах ресурсов.Returns information about a resource provider and its supported resource types. Если тип ресурса не указан, функция возвращает все типы, поддерживаемые для поставщика ресурсов.If you don't provide a resource type, the function returns all the supported types for the resource provider.

ПараметрыParameters

ПараметрParameter Обязательное значениеRequired ТипType ОписаниеDescription
пространство_имен_поставщикаproviderNamespace ДаYes строкаstring Пространство имен поставщика.Namespace of the provider
resourceTyperesourceType НетNo строкаstring Тип ресурса в указанном пространстве имен.The type of resource within the specified namespace.

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

Все поддерживаемые типы возвращаются в следующем формате:Each supported type is returned in the following format:

{
    "resourceType": "{name of resource type}",
    "locations": [ all supported locations ],
    "apiVersions": [ all supported API versions ]
}

Упорядочение массива возвращаемых значений не гарантируется.Array ordering of the returned values isn't guaranteed.

ПримерExample

В следующем примере шаблона показано, как использовать функцию provider:The following example template shows how to use the provider function:

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "providerNamespace": {
            "type": "string"
        },
        "resourceType": {
            "type": "string"
        }
    },
    "resources": [],
    "outputs": {
        "providerOutput": {
            "value": "[providers(parameters('providerNamespace'), parameters('resourceType'))]",
            "type" : "object"
        }
    }
}

Для поставщика ресурсов Microsoft.Web и типа ресурса sites приведенный выше пример возвращает объект в таком формате:For the Microsoft.Web resource provider and sites resource type, the preceding example returns an object in the following format:

{
  "resourceType": "sites",
  "locations": [
    "South Central US",
    "North Europe",
    "West Europe",
    "Southeast Asia",
    ...
  ],
  "apiVersions": [
    "2016-08-01",
    "2016-03-01",
    "2015-08-01-preview",
    "2015-08-01",
    ...
  ]
}

referencereference

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

Возвращает объект, представляющий состояние среды выполнения ресурса.Returns an object representing a resource's runtime state.

ПараметрыParameters

ПараметрParameter Обязательное значениеRequired ТипType ОписаниеDescription
имя_ресурса или идентификатор_ресурсаresourceName or resourceIdentifier ДаYes строкаstring Имя или уникальный идентификатор ресурса.Name or unique identifier of a resource. При указании ссылки на ресурс в текущем шаблоне укажите в качестве параметра только имя ресурса.When referencing a resource in the current template, provide only the resource name as a parameter. При ссылке на ранее развернутый ресурс укажите идентификатор ресурса.When referencing a previously deployed resource, provide the resource ID.
apiVersionapiVersion НетNo строкаstring Версия API для указанного ресурса.API version of the specified resource. Если ресурс не предоставляется в рамках того же шаблона, необходимо включить этот параметр.Include this parameter when the resource isn't provisioned within same template. Как правило, указывается в формате гггг-мм-дд.Typically, in the format, yyyy-mm-dd. Допустимые версии API для ресурса см. в разделе Справочникпо шаблонам.For valid API versions for your resource, see template reference.
Full'Full' НетNo строкаstring Значение, указывающее, следует ли возвращать полный объект ресурса.Value that specifies whether to return the full resource object. Если вы не укажете 'Full', возвращается только объект свойств ресурса.If you don't specify 'Full', only the properties object of the resource is returned. Полный объект включает такие значения, как идентификатор ресурса и расположение.The full object includes values such as the resource ID and location.

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

Каждый тип ресурса возвращает для функции reference разные свойства.Every resource type returns different properties for the reference function. Функция не возвращает данные в едином предварительно заданном формате.The function doesn't return a single, predefined format. Кроме того, возвращаемое значение зависит от того, указали ли вы полный объект.Also, the returned value differs based on whether you specified the full object. Чтобы просмотреть свойства для типа ресурса, возвратите объект в разделе outputs, как показано в примере.To see the properties for a resource type, return the object in the outputs section as shown in the example.

ПримечанияRemarks

Эталонная функция извлекает состояние среды выполнения ранее развернутого ресурса или ресурса, развернутого в текущем шаблоне.The reference function retrieves the runtime state of either a previously deployed resource or a resource deployed in the current template. В этой статье приведены примеры для обоих сценариев.This article shows examples for both scenarios.

Обычно функция reference используется, чтобы получить определенное значение из объекта, например универсальный код ресурса (URI) конечной точки большого двоичного объекта или полное доменное имя.Typically, you use the reference function to return a particular value from an object, such as the blob endpoint URI or fully qualified domain name.

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

Используйте 'Full', если вам нужны значения ресурсов, которые не являются частью схемы свойств.Use 'Full' when you need resource values that aren't part of the properties schema. Например, чтобы задать политику доступа к хранилищу ключей, получите свойства идентификатора для виртуальной машины.For example, to set key vault access policies, get the identity properties for a virtual machine.

{
  "type": "Microsoft.KeyVault/vaults",
  "properties": {
    "tenantId": "[reference(concat('Microsoft.Compute/virtualMachines/', variables('vmName')), '2017-03-30', 'Full').identity.tenantId]",
    "accessPolicies": [
      {
        "tenantId": "[reference(concat('Microsoft.Compute/virtualMachines/', variables('vmName')), '2017-03-30', 'Full').identity.tenantId]",
        "objectId": "[reference(concat('Microsoft.Compute/virtualMachines/', variables('vmName')), '2017-03-30', 'Full').identity.principalId]",
        "permissions": {
          "keys": [
            "all"
          ],
          "secrets": [
            "all"
          ]
        }
      }
    ],
    ...

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

Эталонную функцию можно использовать только в свойствах определения ресурса и в разделе выходных данных шаблона или развертывания.The reference function can only be used in the properties of a resource definition and the outputs section of a template or deployment. При использовании с итерацией свойстваможно использовать функцию Reference для input , так как выражение назначается свойству ресурса.When used with property iteration, you can use the reference function for input because the expression is assigned to the resource property. Его нельзя использовать с count , так как счетчик должен быть определен до разрешения функции Reference.You can't use it with count because the count must be determined before the reference function is resolved.

Нельзя использовать функцию Reference в выходных данных вложенного шаблона для возврата ресурса, развернутого во вложенном шаблоне.You can't use the reference function in the outputs of a nested template to return a resource you've deployed in the nested template. Вместо этого используйте связанный шаблон.Instead, use a linked template.

При использовании функции Reference в ресурсе, который условно развернут, функция вычисляется, даже если ресурс не развернут.If you use the reference function in a resource that is conditionally deployed, the function is evaluated even if the resource isn't deployed. Если ссылочная функция ссылается на несуществующий ресурс, возникает ошибка.You get an error if the reference function refers to a resource that doesn't exist. Используйте функцию If , чтобы убедиться, что функция вычисляется только при развертывании ресурса.Use the if function to make sure the function is only evaluated when the resource is being deployed. См. функцию if для примера шаблона, который использует оператор If и ссылку с условно развернутым ресурсом.See the if function for a sample template that uses if and reference with a conditionally deployed resource.

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

С помощью функции reference вы прямо объявляете, что один ресурс зависит от другого, если ресурс, на который указывает ссылка, предоставляется в том же шаблоне и вы ссылаетесь, используя его имя (а не идентификатор).By using the reference function, you implicitly declare that one resource depends on another resource if the referenced resource is provisioned within same template and you refer to the resource by its name (not resource ID). При этом свойство dependsOn использовать не нужно.You don't need to also use the dependsOn property. Расчет функции выполняется только после развертывания ресурса, на который указывает ссылка.The function isn't evaluated until the referenced resource has completed deployment.

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

При ссылке на ресурс, развернутый в том же шаблоне, укажите имя ресурса.When referencing a resource that is deployed in the same template, provide the name of the resource.

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

При ссылке на ресурс, который не развернут в том же шаблоне, укажите идентификатор ресурса.When referencing a resource that isn't deployed in the same template, provide the resource ID.

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

Чтобы избежать неоднозначности в отношении ресурса, на который вы ссылаетесь, можно указать полное имя ресурса.To avoid ambiguity about which resource you're referencing, you can provide a fully qualified resource name.

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

При создании полной ссылки на ресурс порядок объединения сегментов из типа и имени представляет собой не только использование этих двух вариантов.When constructing a fully qualified reference to a resource, the order to combine segments from the type and name isn't simply a concatenation of the two. Вместо этого после пространства имен используйте пары типа и имени, начиная от наименее подходящей к наиболее подходящей.Instead, after the namespace, use a sequence of type/name pairs from least specific to most specific:

{Resource-Provider-Namespace}/{Парент-ресаурце-типе}/{Парент-ресаурце-наме} [/{Чилд-ресаурце-типе}/{Чилд-ресаурце-наме}]{resource-provider-namespace}/{parent-resource-type}/{parent-resource-name}[/{child-resource-type}/{child-resource-name}]

Пример:For example:

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

ПримерExample

Следующий пример шаблона развертывает ресурс и ссылается на этот ресурс.The following example template deploys a resource, and references that resource.

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

В предыдущем примере возвращаются два объекта.The preceding example returns the two objects. Объект свойств имеет следующий формат:The properties object is in the following format:

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

Полный объект имеет следующий формат:The full object is in the following format:

{
  "apiVersion":"2016-12-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":"2016-12-01",
  "condition":true,
  "isConditionTrue":true,
  "isTemplateResource":false,
  "isAction":false,
  "provisioningOperation":"Read"
}

Следующий пример шаблона ссылается на учетную запись хранения, которая не развертывается в этом шаблоне.The following example template references a storage account that isn't deployed in this template. Учетная запись хранения уже имеется в той же подписке.The storage account already exists within the same subscription.

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

resourceGroupresourceGroup

resourceGroup()

Возвращает объект, который представляет текущую группу ресурсов.Returns an object that represents the current resource group.

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

Возвращаемый объект имеет следующий формат:The returned object is in the following format:

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

Свойство ManagedBy возвращается только для групп ресурсов, содержащих ресурсы, управляемые другой службой.The managedBy property is returned only for resource groups that contain resources that are managed by another service. Для управляемых приложений, кирпичей данных и AKS значение свойства — это идентификатор ресурса для управления ресурсом.For Managed Applications, Databricks, and AKS, the value of the property is the resource ID of the managing resource.

ПримечанияRemarks

Функцию resourceGroup() нельзя использовать в шаблоне, который развернут на уровне подписки.The resourceGroup() function can't be used in a template that is deployed at the subscription level. Ее можно использовать только в шаблонах, развернутых в группе ресурсов.It can only be used in templates that are deployed to a resource group.

Как правило, функция resourceGroup используется для создания ресурсов в одном расположении с группой ресурсов.A common use of the resourceGroup function is to create resources in the same location as the resource group. В следующем примере расположение группы ресурсов используется для назначения расположения веб-сайту.The following example uses the resource group location to assign the location for a web site.

"resources": [
   {
      "apiVersion": "2016-08-01",
      "type": "Microsoft.Web/sites",
      "name": "[parameters('siteName')]",
      "location": "[resourceGroup().location]",
      ...
   }
]

Кроме того, функцию resourceGroup можно использовать для применения тегов из группы ресурсов к ресурсу.You can also use the resourceGroup function to apply tags from the resource group to a resource. Дополнительные сведения см. в статье применение тегов из группы ресурсов.For more information, see Apply tags from resource group.

ПримерExample

Следующий пример шаблона возвращает свойства группы ресурсов.The following example template returns the properties of the resource group.

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

В предыдущем примере возвращается объект в следующем формате:The preceding example returns an object in the following format:

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

resourceIdresourceId

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

Возвращает уникальный идентификатор ресурса.Returns the unique identifier of a resource. Используйте эту функцию в том случае, когда имя ресурса является неоднозначным или не было предоставлено в пределах того же шаблона.You use this function when the resource name is ambiguous or not provisioned within the same template.

ПараметрыParameters

ПараметрParameter Обязательное значениеRequired ТипType ОписаниеDescription
subscriptionIdsubscriptionId НетNo строка (в формате GUID)string (In GUID format) Значение по умолчанию — текущая подписка.Default value is the current subscription. Укажите это значение, если нужно получить ресурс из другой подписки.Specify this value when you need to retrieve a resource in another subscription.
resourceGroupNameresourceGroupName НетNo строкаstring Значение по умолчанию — текущая группа ресурсов.Default value is current resource group. Укажите это значение, если нужно получить ресурс из другой группы ресурсов.Specify this value when you need to retrieve a resource in another resource group.
resourceTyperesourceType ДаYes строкаstring Тип ресурса, включая пространство имен поставщика ресурсов.Type of resource including resource provider namespace.
имя_ресурса1resourceName1 ДаYes строкаstring Имя ресурса.Name of resource.
имя_ресурса2resourceName2 НетNo строкаstring Имя следующего ресурса, если ресурс является вложенным.Next resource name segment if resource is nested.

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

Идентификатор возвращается в следующем формате:The identifier is returned in the following format:

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

ПримечанияRemarks

При использовании с развертыванием на уровне подписки функция resourceId() может извлечь только идентификаторы ресурсов, развернутых на этом уровне.When used with a subscription-level deployment, the resourceId() function can only retrieve the ID of resources deployed at that level. Например, вы можете получить идентификатор определения политики или роли, но не идентификатор учетной записи хранения.For example, you can get the ID of a policy definition or role definition, but not the ID of a storage account. Для развертываний в группе ресурсов все происходит наоборот.For deployments to a resource group, the opposite is true. Вы не можете получить идентификаторы ресурсов, развернутых на уровне подписки.You can't get the resource ID of resources deployed at the subscription-level.

Указанные значения параметров зависят от того, находится ли ресурс в той же подписке и группе ресурсов, что и текущее развертывание.The parameter values you specify depend on whether the resource is in the same subscription and resource group as the current deployment. Чтобы получить идентификатор ресурса для учетной записи хранения в одной подписке и группе ресурсов, используйте команду ниже:To get the resource ID for a storage account in the same subscription and resource group, use:

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

Чтобы получить идентификатор ресурса для учетной записи хранения в той же подписке, но другой группе ресурсов, используйте команду ниже:To get the resource ID for a storage account in the same subscription but a different resource group, use:

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

Чтобы получить идентификатор ресурса для учетной записи хранения в других подписке и группе ресурсов, используйте команду ниже:To get the resource ID for a storage account in a different subscription and resource group, use:

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

Чтобы получить идентификатор ресурса для базы данных в другой группе ресурсов, используйте команду ниже:To get the resource ID for a database in a different resource group, use:

"[resourceId('otherResourceGroup', 'Microsoft.SQL/servers/databases', parameters('serverName'), parameters('databaseName'))]"

Чтобы получить идентификатор ресурса на уровне подписки при развертывании в области подписки, выполните команду ниже:To get the resource ID of a subscription-level resource when deploying at the subscription scope, use:

"[resourceId('Microsoft.Authorization/policyDefinitions', 'locationpolicy')]"

Эта функция часто необходима при использовании учетной записи хранения или виртуальной сети в альтернативной группе ресурсов.Often, you need to use this function when using a storage account or virtual network in an alternate resource group. В следующем примере показано, как ресурс из внешней группы ресурсов можно легко использовать:The following example shows how a resource from an external resource group can easily be used:

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
      "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": [
  {
      "apiVersion": "2015-05-01-preview",
      "type": "Microsoft.Network/networkInterfaces",
      "name": "[parameters('nicName')]",
      "location": "[parameters('location')]",
      "properties": {
          "ipConfigurations": [{
              "name": "ipconfig1",
              "properties": {
                  "privateIPAllocationMethod": "Dynamic",
                  "subnet": {
                      "id": "[variables('subnet1Ref')]"
                  }
              }
          }]
       }
  }]
}

ПримерExample

Следующий пример шаблона возвращает идентификатор ресурса для учетной записи хранения в группе ресурсов:The following example template returns the resource ID for a storage account in the resource group:

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

Выходные данные из предыдущего примера со значениями по умолчанию:The output from the preceding example with the default values is:

НазваниеName TypeType ЗначениеValue
sameRGOutputsameRGOutput СтроковоеString /subscriptions/{ИД_текущей_подписки}/resourceGroups/examplegroup/providers/Microsoft.Storage/storageAccounts/examplestorage/subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft.Storage/storageAccounts/examplestorage
differentRGOutputdifferentRGOutput СтроковоеString /subscriptions/{ИД_текущей_подписки}/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage/subscriptions/{current-sub-id}/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage
differentSubOutputdifferentSubOutput СтроковоеString /subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage
nestedResourceOutputnestedResourceOutput СтроковоеString /subscriptions/{ИД_текущей_подписки}/resourceGroups/examplegroup/providers/Microsoft.SQL/servers/serverName/databases/databaseName/subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft.SQL/servers/serverName/databases/databaseName

подпискаsubscription

subscription()

Возвращает сведения о подписке для текущего развертывания.Returns details about the subscription for the current deployment.

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

Функция возвращает значение в следующем формате:The function returns the following format:

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

ПримерExample

В следующем примере шаблона показана функция subscription, вызываемая в разделе выходных данных.The following example template shows the subscription function called in the outputs section.

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

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