Funções de recursos para modelos ARM

Resource Manager fornece as seguintes funções para obter valores de recursos no seu modelo de Resource Manager Azure (modelo ARM):

Para obter valores a partir de parâmetros, variáveis ou a implementação atual, consulte as funções de valor de Implementação.

Para obter valores de âmbito de implantação, consulte as funções De Âmbito.

Dica

Recomendamos a Bicep porque oferece as mesmas capacidades que os modelos ARM e a sintaxe é mais fácil de usar. Para saber mais, consulte as funções de recursos .

extensãoResourceId

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

Devolve o ID do recurso para um recurso de extensão. Um recurso de extensão é um tipo de recurso que é aplicado a outro recurso para adicionar às suas capacidades.

Em Bicep, utilize a função ExtensionResourceId .

Parâmetros

Parâmetro Necessário Tipo Description
baseResourceId Yes string O ID de recursos para o recurso a que o recurso de extensão é aplicado.
resourceType Yes string Tipo de recurso de extensão, incluindo espaço de nome do fornecedor de recursos.
recursoName1 Yes string Nome do recurso de extensão.
recursoName2 No string Próximo segmento de nome de recurso, se necessário.

Continue a adicionar nomes de recursos como parâmetros quando o tipo de recurso inclui mais segmentos.

Valor devolvido

O formato básico do ID de recurso devolvido por esta função é:

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

O segmento de âmbito varia de acordo com o recurso base que está a ser alargado. Por exemplo, o ID para uma subscrição tem segmentos diferentes do ID para um grupo de recursos.

Quando o recurso de extensão é aplicado a um recurso, o ID de recurso é devolvido no seguinte formato:

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{baseResourceProviderNamespace}/{baseResourceType}/{baseResourceName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

Quando o recurso de extensão é aplicado a um grupo de recursos, o formato devolvido é:

/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

Um exemplo de utilização desta função com um grupo de recursos é mostrado na secção seguinte.

Quando o recurso de extensão é aplicado a uma subscrição, o formato devolvido é:

/subscriptions/{subscriptionId}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

Quando o recurso de extensão é aplicado a um grupo de gestão, o formato devolvido é:

/providers/Microsoft.Management/managementGroups/{managementGroupName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}

Um exemplo de utilização desta função com um grupo de gestão é mostrado na secção seguinte.

extensãoResourceD exemplo

O exemplo a seguir devolve o ID do recurso para um bloqueio de grupo de recursos.

{
  "$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'))]"
    }
  }
}

Uma definição de política personalizada implantada num grupo de gestão é implementada como um recurso de extensão. Para criar e atribuir uma política, desloque o modelo seguinte para um grupo de gestão.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "_generator": {
      "name": "bicep",
      "version": "0.5.6.12127",
      "templateHash": "1532257987028557958"
    }
  },
  "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."
      }
    }
  },
  "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": [
        "[extensionResourceId(managementGroup().id, 'Microsoft.Authorization/policyDefinitions', variables('policyDefinitionName'))]"
      ]
    }
  ]
}

As definições políticas incorporadas são recursos de nível de inquilino. Para um exemplo de implementação de uma definição de política incorporada, consulte o inquilinoResourceId.

lista*

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

A sintaxe para esta função varia em função do nome das operações da lista. Cada implementação devolve valores para o tipo de recurso que suporta uma operação de lista. O nome da operação deve começar list e pode ter um sufixo. Alguns usos comuns sãolist, listKeyslistKeyValuee listSecrets.

Em Bicep, utilize a função lista* .

Parâmetros

Parâmetro Necessário Tipo Description
recursoName ou resourceIdentifier Yes string Identificador único para o recurso.
apiVersion Yes string Versão API do estado de execução de recursos. Tipicamente, no formato, yyy-mm-dd.
funçõesValues No objeto Um objeto que tem valores para a função. Apenas forneça este objeto para funções que suportem a receção de um objeto com valores de parâmetros, como listAccountSas numa conta de armazenamento. Neste artigo é mostrado um exemplo de valores de função de passagem.

Usos válidos

As funções da lista podem ser utilizadas nas propriedades de uma definição de recurso. Não utilize uma função de lista que exponha informações sensíveis na secção de saídas de um modelo. Os valores de saída são armazenados no histórico de implementação e podem ser recuperados por um utilizador malicioso.

Quando usado com iteração de propriedade, você pode usar as funções da lista porque input a expressão é atribuída à propriedade de recursos. Não pode usá-los porque count a contagem deve ser determinada antes da função da lista ser resolvida.

Implementações

As possíveis utilizações list* são mostradas na tabela seguinte.

Tipo de recurso Nome da função
Microsoft.Addons/supportProviders listsupportplaninfo
Microsoft.AnalysisServices/servidores listGatewayStatus
Microsoft.ApiManagement/serviço/autorizaçãoServadores listSecrets
Microsoft.ApiManagement/service/gateways listKeys
Microsoft.ApiManagement/service/identityProviders listSecrets
Microsoft.ApiManagement/service/namedValues listValue
Microsoft.ApiManagement/service/openidConnectProviders listSecrets
Microsoft.ApiManagement/service/subscrições listSecrets
Microsoft.AppConfiguration/configurationStores ListKeys
Microsoft.AppPlatform/primavera listTestKeys
Microsoft.Automation/automation listKeys
Microsoft.Batch/batchAccounts listKeys
Microsoft.BatchAI/workspaces/experiments/jobs listoutputfiles
Microsoft.Blockchain/blockchainMembers listApiKeys
Microsoft.Blockchain/blockchainMembers/transactionNodes listApiKeys
Microsoft.BotService/botServices/canais listChannelWithKeys
Microsoft.Cache/redis listKeys
Microsoft.CognitiveServices/contas 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/empregos listCredentials
Microsoft.DataFactory/datafactories/gateways listauthkeys
Microsoft.DataFactory/fábricas/integrationruns listauthkeys
Microsoft.DataLakeAnalytics/accounts/storageAcounts/Contentores listSasTokens
Microsoft.DataShare/contas/ações listSynchronizations
Microsoft.DataShare/contas/shareSubscriptions listSourceShareSynchronizationSettings
Microsoft.DataShare/contas/shareSubscriptions listSynchronizationDetails
Microsoft.DataShare/contas/shareSubscriptions listSynchronizations
Microsoft.Devices/iotHubs listKeys
Microsoft.Devices/iotHubs/iotHubKeys listKeys
Microsoft.Devices/provisioningServices/keys listKeys
Microsoft.Devices/ProvisioningServices listKeys
Microsoft.DevTestLab/laboratórios ListVhds
Microsoft.DevTestLab/laboratórios/horários ListApplicable
Microsoft.DevTestLab/labs/users/serviceFabrics ListApplicableSchedules
Microsoft.DevTestLab/labs/virtualMachines ListApplicableSchedules
Microsoft.DocumentDB/databaseSacons listConnectionStrings
Microsoft.DocumentDB/databaseSacons listKeys
Microsoft.DocumentDB/databaseAcons/notebookS listConnectionInfo
Microsoft.DomainRegistration/topLevelDomains listAgreements
Microsoft.EventGrid/domínios listKeys
Microsoft.EventGrid/tópicos listKeys
Microsoft.EventHub/namespaces/autorizaçõesRules listKeys
Microsoft.EventHub/namespaces/disasterRecoveryConfigs/authorizationRules listKeys
Microsoft.EventHub/namespaces/eventhubs/autorizaçõesRules listKeys
Microsoft.ImportExport/jobs listBitLockerKeys
A Microsoft. Kusto/Clusters/Bases de Dados ListPrincipals
Microsoft.LabServices/utilizadores ListEnvironments
Microsoft.LabServices/utilizadores ListLabs
Microsoft.Logic/integrationAconselhos/acordos listContentCallbackUrl
Microsoft.Logic/integrationContas/conjuntos listContentCallbackUrl
Microsoft.Logic/integrationAcontas listCallbackUrl
Microsoft.Logic/integrationAcontas listKeyVaultKeys
Microsoft.Logic/integrationAconselhos/mapas listContentCallbackUrl
Microsoft.Logic/integrationAconsecondas/parceiros listContentCallbackUrl
Microsoft.Logic/integrationAconselhos/esquemas listContentCallbackUrl
Microsoft.Logic/workflows listCallbackUrl
Microsoft.Logic/workflows listSwagger
Microsoft.Logic/workflows/runs/actions listExpressionTraces
Microsoft.Logic/workflows/runs/actions/repetições listExpressionTraces
Microsoft.Logic/workflows/triggers listCallbackUrl
Microsoft.Logic/workflows/versões/triggers listCallbackUrl
Microsoft.MachineLearning/webServices listkeys
Microsoft.MachineLearning/Workspaces listworkspacekeys
Microsoft.MachineLearningServices/workspaces/computes listKeys
Microsoft.MachineLearningServices/workspaces/computes listNodes
Microsoft.MachineLearningServices/workspaces listKeys
A Microsoft. Mapas/contas listKeys
Microsoft.Media/mediaservices/ativos listContainerSas
Microsoft.Media/mediaservices/ativos listStreamingLocators
Microsoft.Media/mediaservices/streamingLocators listContentKeys
Microsoft.Media/mediaservices/streamingLocators listPaths
Microsoft.Network/applicationSecurityGroups listIpConfigurations
Microsoft.NotificationHubs/Namespaces/autorizações listkeys
Microsoft.NotificationHubs/Namespaces/NotificationHubs/autorizaçõesRules listkeys
Microsoft.OperationalInsights/workspaces lista
Microsoft.OperationalInsights/workspaces listKeys
Microsoft.PolicyInsights/remediações listaDeployments
Microsoft.RedHatOpenShift/openShiftClusters listCredentials
Microsoft.Relay/namespaces/autorizaçõesRules listKeys
Microsoft.Relay/namespaces/disasterRecoveryConfigs/authorizationRules listKeys
Microsoft.Relay/namespaces/HybridConnections/autorizaçõesRules listKeys
Microsoft.Relay/namespaces/WcfRelays/authorizationRules listkeys
Microsoft.Search/searchServices listAdminKeys
Microsoft.Search/searchServices listQueryKeys
Microsoft.ServiceBus/namespaces/autorizaçõesRules listKeys
Microsoft.ServiceBus/namespaces/disasterRecoveryConfigs/authorizationRules listKeys
Microsoft.ServiceBus/namespaces/filas/autorizaçõesRules listKeys
Microsoft.ServiceBus/namespaces/topics/authorizationRules listKeys
Microsoft.SignalRService/Signalr listKeys
A Microsoft. Armazenamento/armazenamentoContas listAccountSas
A Microsoft. Armazenamento/armazenamentoContas listKeys
A Microsoft. Armazenamento/armazenamentoContas listServiceSas
Microsoft.StorSimple/managers/devices listFailoverSets
Microsoft.StorSimple/managers/devices listFailoverTargets
Microsoft.StorSimple/managers listActivaçãoKey
Microsoft.StorSimple/managers listPublicEncryptionKey
Microsoft.Synapse/workspaces/integrationRuntimes listAuthKeys
Microsoft.Web/connectionGateways ListStatus
microsoft.web/conexões 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 lista
Microsoft.Web/sites/config lista
microsoft.web/sites/funções listKeys
microsoft.web/sites/funções listSecrets
microsoft.web/sites/hybridconnectionnamespaces/relays listKeys
microsoft.web/sites listsyncfunctiontriggerstatus
microsoft.web/sites/slots/functions listSecrets
microsoft.web/sites/slots/backups lista
Microsoft.Web/sites/slots/config lista
microsoft.web/sites/slots/functions listSecrets

Para determinar quais os tipos de recursos que têm uma operação de lista, tem as seguintes opções:

  • Consulte as operações da API REST para um fornecedor de recursos e procure operações de lista. Por exemplo, as contas de armazenamento têm a operação listKeys.

  • Utilize o cmdlet Get-AzProviderOperation PowerShell. O exemplo a seguir obtém todas as operações da lista para contas de armazenamento:

    Get-AzProviderOperation -OperationSearchString "Microsoft.Storage/*" | where {$_.Operation -like "*list*"} | FT Operation
    
  • Utilize o seguinte comando Azure CLI para filtrar apenas as operações da lista:

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

Valor devolvido

O objeto devolvido varia em função da list utilização. Por exemplo, a listKeys conta de armazenamento para uma conta de armazenamento devolve o seguinte formato:

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

Outras list funções têm diferentes formatos de retorno. Para ver o formato de uma função, inclua-o na secção de saídas, como mostrado no modelo de exemplo.

Observações

Especifique o recurso utilizando o nome do recurso ou a função resourceId. Quando utilizar uma list função no mesmo modelo que implementa o recurso referenciado, utilize o nome do recurso.

Se utilizar uma list função num recurso que esteja implantado condicionalmente, a função é avaliada mesmo que o recurso não seja implantado. Obtém-se um erro se a list função se referir a um recurso que não existe. Utilize a if função para se certificar de que a função só é avaliada quando o recurso está a ser implantado. Consulte a função se for para um modelo de amostra que utiliza if e list com um recurso implantado condicionalmente.

Exemplo da lista

O exemplo a seguir utiliza-se listKeys ao definir um valor para scripts de implementação.

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

O próximo exemplo mostra uma list função que toma um parâmetro. Neste caso, a função é listAccountSas. Passe um objeto pelo tempo de validade. O prazo de validade deve ser no futuro.

"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])

Determina se um tipo de recurso suporta zonas para a localização ou região especificadas. Esta função suporta apenas recursos zonais. Os serviços redundantes da zona devolvem uma matriz vazia. Para mais informações, consulte a Azure Services que suporta Zonas de Disponibilidade.

Em Bicep, utilize a função pickZones .

Parâmetros

Parâmetro Necessário Tipo Description
providerNamespace Yes string O espaço de nome do fornecedor de recursos para o tipo de recurso para verificar o suporte da zona.
resourceType Yes string O tipo de recurso para verificar o suporte da zona.
localização Yes string A região para verificar o apoio da zona.
númeroOfZones No número inteiro O número de zonas lógicas para regressar. A predefinição é 1. O número deve ser um número inteiro positivo de 1 a 3. Utilize 1 para recursos de zona única. No que diz a favor de recursos multi-zonas, o valor deve ser inferior ou igual ao número de zonas apoiadas.
offset No número inteiro O offset da zona lógica inicial. A função retorna um erro se o offset plus numberOfZones exceder o número de zonas suportadas.

Valor devolvido

Uma matriz com as zonas apoiadas. Ao utilizar os valores predefinidos para compensação e numberOfZones, um tipo de recurso e região que suporta zonas devolve o seguinte conjunto:

[
    "1"
]

Quando o numberOfZones parâmetro é definido para 3, ele retorna:

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

Quando o tipo de recurso ou região não suporta zonas, uma matriz vazia é devolvida. Uma matriz vazia também é devolvida para serviços redundantes de zona.

[
]

Observações

Existem diferentes categorias para a Zonas de Disponibilidade Azure - zonal e zona redundante. A pickZones função pode ser usada para devolver uma zona de disponibilidade para um recurso zonal. Para serviços redundantes de zona (ZRS), a função devolve uma matriz vazia. Os recursos zonais normalmente têm uma zones propriedade no nível superior da definição de recursos. Para determinar a categoria de suporte para zonas de disponibilidade, consulte os Serviços Azure que suportam Zonas de Disponibilidade.

Para determinar se uma determinada região ou localização do Azure suporta zonas de disponibilidade, ligue para a pickZones função com um tipo de recurso zonal, como Microsoft.Network/publicIPAddresses. Se a resposta não estiver vazia, a região suporta zonas de disponibilidade.

exemplo pickZones

O modelo a seguir mostra três resultados para a utilização da pickZones função.

{
  "$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', 'westus')]"
    },
    "notSupportedType": {
      "type": "array",
      "value": "[pickZones('Microsoft.Cdn', 'profiles', 'westus2')]"
    }
  }
}

A saída dos exemplos anteriores devolve três matrizes.

Nome Tipo Valor
Suportado matriz [ "1" ]
não SupporteRegion matriz []
Não SupportedType matriz []

Pode utilizar a resposta pickZones para determinar se fornece nulos para zonas ou atribui máquinas virtuais a diferentes zonas. O exemplo a seguir define um valor para a zona com base na disponibilidade de zonas.

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

Cosmos DB não é um recurso zonal, mas você pode usar a pickZones função para determinar se permite a redundância de zona para georeplicação. Passe o Microsoft.Armazenamento /armazenamentoA tipo de recurso para determinar se permite a redundância de zona.

"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')]"
    }
  }
]

fornecedores

A função dos fornecedores foi depreciada. Já não recomendamos a sua utilização. Se usou esta função para obter uma versão API para o fornecedor de recursos, recomendamos que forneça uma versão API específica no seu modelo. A utilização de uma versão API devolvida dinamicamente pode quebrar o seu modelo se as propriedades mudarem entre versões.

Em Bicep, a função de fornecedores é depreciada.

referência

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

Devolve um objeto que representa o estado de execução de um recurso.

Em Bicep, utilize a função de referência .

Parâmetros

Parâmetro Necessário Tipo Description
recursoName ou resourceIdentifier Yes string Nome ou identificador único de um recurso. Ao fazer referência a um recurso no modelo atual, forneça apenas o nome do recurso como parâmetro. Quando se refere a um recurso previamente implantado ou quando o nome do recurso for ambíguo, forneça o ID do recurso.
apiVersion No string Versão API do recurso especificado. Este parâmetro é necessário quando o recurso não é aprovisionado dentro do mesmo modelo. Tipicamente, no formato, yyy-mm-dd. Para versões API válidas para o seu recurso, consulte a referência do modelo.
'Cheio' No string Valor que especifica se deve devolver o objeto de recurso completo. Se não especificar 'Full', apenas o objeto de propriedades do recurso é devolvido. O objeto completo inclui valores como o ID de recurso e a localização.

Valor devolvido

Cada tipo de recurso devolve diferentes propriedades para a função de referência. A função não devolve um único formato predefinido. Além disso, o valor devolvido difere com base no valor do 'Full' argumento. Para ver as propriedades de um tipo de recurso, devolva o objeto na secção de saídas, como mostra o exemplo.

Observações

A função de referência recupera o estado de tempo de execução de um recurso previamente implantado ou de um recurso implantado no modelo atual. Este artigo mostra exemplos para ambos os cenários.

Normalmente, você usa a reference função para devolver um valor particular de um objeto, como o ponto final blob URI ou o nome de domínio totalmente qualificado.

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

Use 'Full' quando precisar de valores de recursos que não fazem parte do esquema de propriedades. Por exemplo, para definir as principais políticas de acesso ao cofre, obtenha as propriedades de identidade para uma máquina virtual.

{
  "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"
          ]
        }
      }
    ],
    ...

Usos válidos

A reference função só pode ser utilizada nas propriedades de uma definição de recurso e na secção de saídas de um modelo ou implantação. Quando usado com iteração de propriedade, pode usar a reference função porque input a expressão é atribuída à propriedade de recursos.

Não é possível utilizar a reference função para definir o valor do imóvel num ciclo de count cópia. Pode utilizar para definir outras propriedades no loop. A referência está bloqueada para a propriedade da contagem porque essa propriedade deve ser determinada antes da reference função ser resolvida.

Para utilizar a reference função ou qualquer list* função na secção de saídas de um modelo aninhado, deve definir a avaliação do expressionEvaluationOptionsâmbito interno ou utilizar um modelo ligado em vez de um modelo aninhado.

Se utilizar a reference função num recurso que esteja implantado condicionalmente, a função é avaliada mesmo que o recurso não seja implantado. Obtém-se um erro se a reference função se referir a um recurso que não existe. Utilize a if função para se certificar de que a função só é avaliada quando o recurso está a ser implantado. Consulte a função se for para um modelo de amostra que utiliza if e reference com um recurso implantado condicionalmente.

Dependência implícita

Ao utilizar a reference função, declara implicitamente que um recurso depende de outro recurso se o recurso referenciado for aprovisionado dentro do mesmo modelo e se referir ao recurso pelo seu nome (não iD de recurso). Você não precisa também usar a dependsOn propriedade. A função não é avaliada até que o recurso referenciado tenha concluído a implementação.

Nome de recurso ou identificador

Ao fazer referência a um recurso que é implantado no mesmo modelo, forneça o nome do recurso.

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

Ao fazer referência a um recurso que não seja implantado no mesmo modelo, forneça o ID do recurso e apiVersion.

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

Para evitar ambiguidades sobre o recurso a que se refere, pode fornecer um identificador de recursos totalmente qualificado.

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

Ao construir uma referência totalmente qualificada a um recurso, a ordem de combinar segmentos do tipo e do nome não é simplesmente uma concatenação dos dois. Em vez disso, após o espaço de nome, utilize uma sequência de pares de tipo/nome de menos específicos para os mais específicos:

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

Por exemplo:

Microsoft.Compute/virtualMachines/myVM/extensions/myExt está correto Microsoft.Compute/virtualMachines/extensions/myVM/myExt não é correto

Para simplificar a criação de qualquer ID de recurso, utilize as resourceId() funções descritas neste documento em vez da concat() função.

Obter identidade gerida

Identidades geridas para recursos Azure são tipos de recursos de extensão que são criados implicitamente para alguns recursos. Como a identidade gerida não está explicitamente definida no modelo, deve referenciar o recurso a que a identidade é aplicada. Use Full para obter todas as propriedades, incluindo a identidade implicitamente criada.

O padrão é:

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

Por exemplo, para obter o ID principal para uma identidade gerida que é aplicada a uma máquina virtual, use:

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

Ou, para obter a identificação do inquilino para uma identidade gerida que é aplicada a um conjunto de escala de máquina virtual, use:

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

Exemplo de referência

O exemplo a seguir implementa um recurso, e faz referências a esse recurso.

{
  "$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')]"
    }
  }
}

O exemplo anterior devolve os dois objetos. O objeto de propriedades está no seguinte formato:

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

O objeto completo está no seguinte formato:

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

O modelo de exemplo a seguir refere uma conta de armazenamento que não é implantada neste modelo. A conta de armazenamento já existe dentro da mesma subscrição.

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

Consulte a função de âmbito do Grupo de Recursos.

Em Bicep, utilize a função de âmbito do grupo de recursos .

resourceId

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

Devolve o identificador único de um recurso. Utilize esta função quando o nome do recurso é ambíguo ou não é aprovisionado dentro do mesmo modelo. O formato do identificador devolvido varia em base se a implementação ocorre no âmbito de um grupo de recursos, subscrição, grupo de gestão ou inquilino.

Em Bicep, utilize a função resourceId .

Parâmetros

Parâmetro Necessário Tipo Description
subscriptionId No cadeia (no formato GUID) O valor predefinido é a subscrição atual. Especifique este valor quando precisar de recuperar um recurso noutra subscrição. Apenas forneça este valor ao implementar no âmbito de um grupo de recursos ou subscrição.
resourceGroupName No string O valor predefinido é o grupo de recursos corrente. Especifique este valor quando necessitar de recuperar um recurso noutro grupo de recursos. Apenas forneça este valor ao implementar no âmbito de um grupo de recursos.
resourceType Yes string Tipo de recurso, incluindo o espaço de nome do fornecedor de recursos.
recursoName1 Yes string Nome do recurso.
recursoName2 No string Próximo segmento de nome de recurso, se necessário.

Continue a adicionar nomes de recursos como parâmetros quando o tipo de recurso inclui mais segmentos.

Valor devolvido

O ID de recurso é devolvido em diferentes formatos em diferentes âmbitos:

  • Âmbito do grupo de recursos:

    /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
    
  • Âmbito de subscrição:

    /subscriptions/{subscriptionId}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
    
  • Âmbito de gestão do grupo ou do inquilino:

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

Para evitar confusões, recomendamos que não utilize resourceId quando trabalhar com recursos implantados na subscrição, grupo de gestão ou inquilino. Em vez disso, utilize a função ID que é concebida para o âmbito.

Observações

O número de parâmetros que fornece varia consoá-lo em relação ao recurso de pai ou filho, e se o recurso está no mesmo grupo de subscrição ou recursos.

Para obter o ID de recurso para um recurso principal no mesmo grupo de subscrição e recursos, forneça o tipo e o nome do recurso.

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

Para obter o ID de recurso para um recurso infantil, preste atenção ao número de segmentos do tipo de recurso. Fornecer um nome de recurso para cada segmento do tipo de recurso. O nome do segmento corresponde ao recurso que existe para essa parte da hierarquia.

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

Para obter o ID de recurso para um recurso na mesma subscrição, mas grupo de recursos diferente, forneça o nome do grupo de recursos.

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

Para obter o ID de recurso para um recurso em um grupo de subscrição e recursos diferente, forneça o ID de subscrição e o nome do grupo de recursos.

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

Muitas vezes, é necessário utilizar esta função quando utilizar uma conta de armazenamento ou uma rede virtual num grupo de recursos alternativos. O exemplo a seguir mostra como um recurso de um grupo de recursos externos pode ser facilmente utilizado:

{
  "$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')]"
              }
            }
          }
        ]
      }
    }
  ]
}

Exemplo de ID de recursos

O exemplo a seguir devolve o ID do recurso para uma conta de armazenamento no grupo de recursos:

{
  "$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')]"
    }
  }
}

A saída do exemplo anterior com os valores predefinidos é:

Nome Tipo Valor
sameRGOutput String /subscrições/{current-sub-id}/resourceGroups/exemplogroup/providers/Microsoft. Armazenamento/armazenamentoContas/exemplostorage
diferenteRSoutput String /subscrições/{current-sub-id}/resourceGroups/otherResourceGroup/providers/Microsoft. Armazenamento/armazenamentoContas/exemplostorage
diferenteSubOutput String /subscrições/11111111-1111-1111-1111-111111111/resourceGroups/otherResourceGroup/providers/Microsoft. Armazenamento/armazenamentoContas/exemplostorage
nestedResourceOutput String /subscrições/{current-sub-id}/resourceGroups/exemplogroup/providers/Microsoft. SQL/servidores/servidorName/bases de dados/base de dadosName

subscrição

Consulte a função de âmbito de subscrição.

Em Bicep, utilize a função de âmbito de subscrição .

subscriçãoResourceId

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

Devolve o identificador único para um recurso implantado ao nível da subscrição.

Em Bicep, utilize a função SubscriçãoResourceId .

Parâmetros

Parâmetro Necessário Tipo Description
subscriptionId No corda (em formato GUID) O valor predefinido é a subscrição atual. Especifique este valor quando precisar de recuperar um recurso noutra subscrição.
resourceType Yes string Tipo de recurso, incluindo o espaço de nome do fornecedor de recursos.
recursoName1 Yes string Nome do recurso.
recursoName2 No string Próximo segmento de nome de recurso, se necessário.

Continue a adicionar nomes de recursos como parâmetros quando o tipo de recurso inclui mais segmentos.

Valor devolvido

O identificador é devolvido no seguinte formato:

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

Observações

Utiliza esta função para obter o ID de recursos para recursos que são implantados na subscrição em vez de um grupo de recursos. O ID devolvido difere do valor devolvido pela função resourceid , não incluindo um valor de grupo de recursos.

subscriçãoResourceID exemplo

O modelo a seguir atribui um papel incorporado. Pode implantá-lo para um grupo de recursos ou para uma subscrição. Utiliza a subscriptionResourceId função para obter o ID de recursos para funções incorporadas.

{
  "$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')]"
      }
    }
  ]
}

managementGroupResourceId

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

Devolve o identificador único para um recurso implantado ao nível do grupo de gestão.

Em Bicep, utilize a função ManagementGroupResourceId .

Parâmetros

Parâmetro Necessário Tipo Description
managementGroupResourceId No corda (em formato GUID) O valor predefinido é o grupo de gestão atual. Especifique este valor quando precisar de recuperar um recurso em outro grupo de gestão.
resourceType Yes string Tipo de recurso, incluindo o espaço de nome do fornecedor de recursos.
recursoName1 Yes string Nome do recurso.
recursoName2 No string Próximo segmento de nome de recurso, se necessário.

Continue a adicionar nomes de recursos como parâmetros quando o tipo de recurso inclui mais segmentos.

Valor devolvido

O identificador é devolvido no seguinte formato:

/providers/Microsoft.Management/managementGroups/{managementGroupName}/providers/{resourceType}/{resourceName}

Observações

Utiliza esta função para obter o ID de recursos para recursos que são implantados no grupo de gestão em vez de um grupo de recursos. O ID devolvido difere do valor devolvido pela função ResourceId , não incluindo um ID de subscrição e um valor de grupo de recursos.

exemplo de GestãoGrouopResourceID

O modelo a seguir cria uma definição de política e atribui a definição de política. Utiliza a managementGroupResourceId função para obter o ID de recurso para definição de política.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "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": "[managementGroupResourceId('Microsoft.Authorization/policyDefinitions', variables('policyDefinitionName'))]"
      },
      "dependsOn": [
        "[format('Microsoft.Authorization/policyDefinitions/{0}', variables('policyDefinitionName'))]"
      ]
    }
  ]
}

inquilinoResourceId

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

Devolve o identificador único para um recurso implantado ao nível do inquilino.

Em Bicep, use a função TenantResourceId .

Parâmetros

Parâmetro Necessário Tipo Description
resourceType Yes string Tipo de recurso, incluindo o espaço de nome do fornecedor de recursos.
recursoName1 Yes string Nome do recurso.
recursoName2 No string Próximo segmento de nome de recurso, se necessário.

Continue a adicionar nomes de recursos como parâmetros quando o tipo de recurso inclui mais segmentos.

Valor devolvido

O identificador é devolvido no seguinte formato:

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

Observações

Você usa esta função para obter o ID de recurso para um recurso que é implantado para o inquilino. O ID devolvido difere dos valores devolvidos por outras funções de ID de recursos, não incluindo o grupo de recursos ou os valores de subscrição.

tenantResourceD exemplo

As definições políticas incorporadas são recursos de nível de inquilino. Para implementar uma atribuição de política que refira uma definição de política incorporada, use a tenantResourceId função.

{
  "$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'))]"
      }
    }
  ]
}

Passos seguintes