Funções de recurso para modelos do ARM

  • Artigo

O Resource Manager fornece as seguintes funções para obter valores de recurso em seu modelo do ARM (modelo Azure Resource Manager):

Para obter valores de parâmetros, de variáveis ou da implantação atual, veja Funções de valor de implantação.

Para obter valores de escopo de implantação, confira Funções de escopo.

Dica

Recomendamos o Bicep porque ele oferece as mesmas funcionalidades que os modelos do ARM e a sintaxe é mais fácil de usar. Para saber mais, confira funções de recurso.

extensionResourceId

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

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

No Bicep, use a função extensionResourceId.

Parâmetros

Parâmetro Obrigatório Type Description
baseResourceId Sim string A ID de recurso para o recurso ao qual o recurso de extensão é aplicado.
resourceType Sim string Tipo de recurso de extensão, incluindo o namespace do provedor de recursos.
resourceName1 Sim string O nome da extensão do recurso.
resourceName2 Não string Próximo segmento de nome de recurso, se necessário.

Continue adicionando nomes de recursos como parâmetros quando o tipo de recurso incluir mais segmentos.

Valor retornado

O formato básico da ID do recurso retornado por essa função é:

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

O segmento de escopo varia conforme o recurso de base que está sendo estendido. Por exemplo, a ID de uma assinatura tem segmentos diferentes da ID de um grupo de recursos.

Quando o recurso de extensão é aplicado a um recurso, a ID de recurso é retornada 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 retornado é:

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

Um exemplo de como usar essa função com um grupo de recursos é mostrado na próxima seção.

Quando o recurso de extensão é aplicado a uma assinatura, o formato retornado é:

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

Quando o recurso de extensão é aplicado a um grupo de gerenciamento, o formato retornado é:

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

Um exemplo de como usar essa função com um grupo de gerenciamento é mostrado na próxima seção.

Exemplo de extensionResourceId

O exemplo a seguir retorna a ID de 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 em um grupo de gerenciamento é implementada como um recurso de extensão. Para criar e atribuir uma política, implante o modelo a seguir em um grupo de gerenciamento.

{
  "$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 de políticas internas são recursos em nível de locatário. Para obter um exemplo de implantação de uma definição de política interna, consulte tenantResourceId.

lista*

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

A sintaxe dessa função varia de acordo com o nome das operações de lista. Cada implementação retorna valores para o tipo de recurso compatível com uma operação de lista. O nome da operação deve começar com list e pode ter um sufixo. Alguns usos comuns são list, listKeys, listKeyValue e listSecrets.

No Bicep, use a função list*.

Parâmetros

Parâmetro Obrigatório Type Descrição
resourceName ou resourceIdentifier Sim string Identificador exclusivo para o recurso.
apiVersion Sim string Versão de API do estado de runtime do recurso. Normalmente, no formato aaaa-mm-dd.
functionValues Não objeto Um objeto que tem valores para a função. Fornecer apenas este objeto para funções que dão suporte ao recebimento de um objeto com valores de parâmetro, como listAccountSas em uma conta de armazenamento. Um exemplo de passar valores de função é mostrado neste artigo.

Usos válidos

A lista de funções podem ser usadas nas propriedades de uma definição de recurso. Não use uma função de lista que exponha informações confidenciais na seção de saídas de um modelo. Os valores de saída são armazenados no histórico de implantação e podem ser recuperados por um usuário mal-intencionado.

Quando usado com iteração de propriedade, você pode usar as funções de lista para input porque a expressão é atribuída à propriedade de recurso. Você não pode usá-las com count porque a contagem deve ser determinada antes que a função list seja resolvida.

Implementações

Os possíveis usos de list* são mostrados na tabela a seguir.

Tipo de recurso Nome da função
Microsoft.Addons/supportProviders listsupportplaninfo
Microsoft.AnalysisServices/servers listGatewayStatus
Microsoft.ApiManagement/service/authorizationServers listSecrets
Microsoft.ApiManagement/service/gateways listKeys
Microsoft.ApiManagement/service/identityProviders listSecrets
Microsoft.ApiManagement/service/namedValues listValue
Microsoft.ApiManagement/service/openidConnectProviders listSecrets
Microsoft.ApiManagement/service/subscriptions listSecrets
Microsoft.AppConfiguration/configurationStores ListKeys
Microsoft.AppPlatform/Spring listTestKeys
Microsoft.Automation/automationAccounts listKeys
Microsoft.Batch/batchAccounts listKeys
Microsoft.BatchAI/workspaces/experiments/jobs listoutputfiles
Microsoft.BotService/botServices/channels listChannelWithKeys
Microsoft.Cache/redis listKeys
Microsoft.CognitiveServices/accounts listKeys
Microsoft.ContainerRegistry/registries listCredentials
Microsoft.ContainerRegistry/registries listUsages
Microsoft.ContainerRegistry/registries/agentpools listQueueStatus
Microsoft.ContainerRegistry/registries/buildTasks listSourceRepositoryProperties
Microsoft.ContainerRegistry/registries/buildTasks/steps listBuildArguments
Microsoft.ContainerRegistry/registries/taskruns listDetails
Microsoft.ContainerRegistry/registries/webhooks listEvents
Microsoft.ContainerRegistry/registries/runs listLogSasUrl
Microsoft.ContainerRegistry/registries/tasks listDetails
Microsoft.ContainerService/managedClusters listClusterAdminCredential
Microsoft.ContainerService/managedClusters listClusterMonitoringUserCredential
Microsoft.ContainerService/managedClusters listClusterUserCredential
Microsoft.ContainerService/managedClusters/accessProfiles listCredential
Microsoft.DataBox/jobs listCredentials
Microsoft.DataFactory/datafactories/gateways listauthkeys
Microsoft.DataFactory/factories/integrationruntimes listauthkeys
Microsoft.DataLakeAnalytics/accounts/storageAccounts/Containers listSasTokens
Microsoft.DataShare/accounts/shares listSynchronizations
Microsoft.DataShare/accounts/shareSubscriptions listSourceShareSynchronizationSettings
Microsoft.DataShare/accounts/shareSubscriptions listSynchronizationDetails
Microsoft.DataShare/accounts/shareSubscriptions listSynchronizations
Microsoft.Devices/iotHubs listKeys
Microsoft.Devices/iotHubs/iotHubKeys listKeys
Microsoft.Devices/provisioningServices/keys listKeys
Microsoft.Devices/provisioningServices listKeys
Microsoft.DevTestLab/labs ListVhds
Microsoft.DevTestLab/labs/schedules ListApplicable
Microsoft.DevTestLab/labs/users/serviceFabrics ListApplicableSchedules
Microsoft.DevTestLab/labs/virtualMachines ListApplicableSchedules
Microsoft.DocumentDB/databaseAccounts listKeys
Microsoft.DocumentDB/databaseAccounts/notebookWorkspaces listConnectionInfo
Microsoft.DomainRegistration/topLevelDomains listAgreements
Microsoft.EventHub/namespaces/authorizationRules listKeys
Microsoft.EventHub/namespaces/disasterRecoveryConfigs/authorizationRules listKeys
Microsoft.EventHub/namespaces/eventhubs/authorizationRules listKeys
Microsoft.ImportExport/jobs listBitLockerKeys
Microsoft.Kusto/Clusters/Databases ListPrincipals
Microsoft.LabServices/labs/users list
Microsoft.LabServices/labs/virtualMachines list
Microsoft.Logic/integrationAccounts/agreements listContentCallbackUrl
Microsoft.Logic/integrationAccounts/assemblies listContentCallbackUrl
Microsoft.Logic/integrationAccounts listCallbackUrl
Microsoft.Logic/integrationAccounts listKeyVaultKeys
Microsoft.Logic/integrationAccounts/maps listContentCallbackUrl
Microsoft.Logic/integrationAccounts/partners listContentCallbackUrl
Microsoft.Logic/integrationAccounts/schemas listContentCallbackUrl
Microsoft.Logic/workflows listCallbackUrl
Microsoft.Logic/workflows listSwagger
Microsoft.Logic/workflows/runs/actions listExpressionTraces
Microsoft.Logic/workflows/runs/actions/repetitions listExpressionTraces
Microsoft.Logic/workflows/triggers listCallbackUrl
Microsoft.Logic/workflows/versions/triggers listCallbackUrl
Microsoft.MachineLearning/webServices listkeys
Microsoft.MachineLearning/Workspaces listworkspacekeys
Microsoft.Maps/accounts listKeys
Microsoft.Media/mediaservices/assets listContainerSas
Microsoft.Media/mediaservices/assets listStreamingLocators
Microsoft.Media/mediaservices/streamingLocators listContentKeys
Microsoft.Media/mediaservices/streamingLocators listPaths
Microsoft.Network/applicationSecurityGroups listIpConfigurations
Microsoft.NotificationHubs/Namespaces/authorizationRules listkeys
Microsoft.NotificationHubs/Namespaces/NotificationHubs/authorizationRules listkeys
Microsoft.OperationalInsights/workspaces list
Microsoft.OperationalInsights/workspaces listKeys
Microsoft.PolicyInsights/remediations listDeployments
Microsoft.RedHatOpenShift/openShiftClusters listCredentials
Microsoft.Relay/namespaces/authorizationRules listKeys
Microsoft.Relay/namespaces/disasterRecoveryConfigs/authorizationRules listKeys
Microsoft.Relay/namespaces/HybridConnections/authorizationRules listKeys
Microsoft.Relay/namespaces/WcfRelays/authorizationRules listkeys
Microsoft.Search/searchServices listAdminKeys
Microsoft.Search/searchServices listQueryKeys
Microsoft.ServiceBus/namespaces/authorizationRules listKeys
Microsoft.ServiceBus/namespaces/disasterRecoveryConfigs/authorizationRules listKeys
Microsoft.ServiceBus/namespaces/queues/authorizationRules listKeys
Microsoft.SignalRService/SignalR listKeys
Microsoft.Storage/storageAccounts listAccountSas
Microsoft.Storage/storageAccounts listKeys
Microsoft.Storage/storageAccounts listServiceSas
Microsoft.StorSimple/managers/devices listFailoverSets
Microsoft.StorSimple/managers/devices listFailoverTargets
Microsoft.StorSimple/managers listActivationKey
Microsoft.StorSimple/managers listPublicEncryptionKey
Microsoft.Synapse/workspaces/integrationRuntimes listAuthKeys
Microsoft.Web/connectionGateways ListStatus
microsoft.web/connections listconsentlinks
Microsoft.Web/customApis listWsdlInterfaces
microsoft.web/locations listwsdlinterfaces
microsoft.web/apimanagementaccounts/apis/connections listconnectionkeys
microsoft.web/apimanagementaccounts/apis/connections listSecrets
microsoft.web/sites/backups list
Microsoft.Web/sites/config list
microsoft.web/sites/functions listKeys
microsoft.web/sites/functions listSecrets
microsoft.web/sites/hybridconnectionnamespaces/relays listKeys
microsoft.web/sites listsyncfunctiontriggerstatus
microsoft.web/sites/slots/functions listSecrets
microsoft.web/sites/slots/backups list
Microsoft.Web/sites/slots/config list
microsoft.web/sites/slots/functions listSecrets

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

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

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

    Get-AzProviderOperation -OperationSearchString "Microsoft.Storage/*" | where {$_.Operation -like "*list*"} | FT Operation

  • Use o seguinte comando da CLI do Azure para filtrar apenas as operações de lista:

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

Valor retornado

O objeto retornado varia de acordo com a função list que você usa. Por exemplo, listKeys para uma conta de armazenamento retorna o seguinte formato:

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

Outras funções list têm formatos diferentes de retorno. Para ver o formato de uma função, inclua-a na seção de saídas, conforme mostra o exemplo de modelo.

Comentários

Especifique o recurso usando o nome de recurso ou o função resourceId. Ao usar uma função list no mesmo modelo que implanta o recurso referenciado, use o nome do recurso.

Se você usar a função list em um recurso implantado condicionalmente, a função será avaliada mesmo que o recurso não seja implantado. Você receberá um erro se a função list se referir a um recurso que não existe. Use a função if para garantir que a função seja avaliada apenas quando o recurso estiver sendo implantado. Consulte a função if para um modelo de exemplo que usa if e list com um recurso implantado condicionalmente.

Exemplo de lista

O exemplo a seguir usa listKeys ao definir um valor para scripts de implantação.

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

O exemplo a seguir mostra uma função list que aceita um parâmetro. Nesse caso, a função é listAccountSas. Passe um objeto para a hora de expiração. A data de validade deve ser futura.

"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 dá suporte a zonas para o local ou região especificado. Essa função só dá suporte a recursos de zona. Os serviços redundantes de zona retornam uma matriz vazia. Para mais informações, confira Serviços do Azure que dão suporte às Zonas de Disponibilidade.

No bicep, use a função pickZones.

Parâmetros

Parâmetro Obrigatório Type Descrição
providerNamespace Sim string O namespace do provedor de recursos para o tipo de recurso para verificar se há suporte para zona.
resourceType Sim string O tipo de recurso a ser verificar se há suporte para zona.
local Sim string A região a ser verificada quanto ao suporte à zona.
numberOfZones Não inteiro O número de zonas lógicas para retornar. O padrão é 1. O número deve ser um número inteiro positivo de 1 a 3. Use 1 para recursos de zona única. Para recursos de várias zonas, o valor deve ser menor ou igual ao número de zonas com suporte.
deslocamento Não inteiro O deslocamento da zona lógica inicial. A função retornará um erro se offset mais numberOfZones exceder o número de zonas com suporte.

Retornar valor

Uma matriz com as zonas com suporte. Ao usar os valores padrão para deslocamento e numberOfZones, um tipo de recurso e uma região que dão suporte a zonas retornam a seguinte matriz:

[
    "1"
]

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

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

Quando o tipo de recurso ou a região não dá suporte a zonas, uma matriz vazia é retornada. Também é retornada uma matriz vazia para serviços com redundância de zona.

[
]

Comentários

Existem categorias diferentes para Zonas de Disponibilidade do Azure; a zonal e a com redundância de zona. A função pickZones pode ser usada para retornar uma zona de disponibilidade para um recurso de zona. Para ZRS (armazenamento com redundância de zona), a função retornará uma matriz vazia. Os recursos de zona costumam ter uma propriedade zones no nível superior da definição de recurso. Para determinar a categoria de suporte para zonas de disponibilidade, confira Serviços do Azure que dão suporte a Zonas de Disponibilidade.

Para verificar se uma determinada região ou local do Azure dá suporte a zonas de disponibilidade, chame a função pickZones com um tipo de recurso de zona, por exemplo Microsoft.Network/publicIPAddresses. Se a resposta não estiver vazia, a região será compatível com zonas de disponibilidade.

exemplo de pickZones

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

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

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

Nome Tipo Valor
com suporte array [ "1" ]
notSupportedRegion array []
notSupportedType array []

Você pode usar a resposta de pickZones para determinar se deve fornecer null para zonas ou atribuir 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'))]"
},

O Azure Cosmos DB não é um recurso zonal, mas você pode usar a função pickZones para determinar se a redundância de zona deve ser habilitada para replicação geográfica. Passe o tipo de recurso Microsoft.Storage/storageAccounts para determinar se a redundância de zona deve ser habilitada.

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

providers

A função providers foi preterida nos modelos do ARM. Não recomendamos mais usá-la. Se você usou essa função para obter uma versão da API para o provedor de recursos, recomendamos que você forneça uma versão de API específica em seu modelo. O uso de uma versão de API retornada dinamicamente pode quebrar seu modelo se as propriedades mudam entre as versões.

No Bicep, a função providers foi preterida.

A operação providers ainda está disponível por meio da API REST. Ela pode ser usada fora de um modelo do ARM para obter informações sobre um provedor de recursos.

reference

Nos modelos sem nomes simbólicos:

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

Nos modelos com nomes simbólicos:

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

Retorna um objeto que representa o estado de runtime de um recurso. A saída e o comportamento da função reference dependem muito de como cada RP (provedor de recursos) implementa suas respostas PUT e GET. Para retornar uma matriz de objetos que representam os estados de runtime de uma coleção de recursos, consulte referências.

O Bicep fornece a função de referência, mas, na maioria dos casos, a função de referência não é necessária. Em vez disso, é recomendável usar o nome simbólico para o recurso. Confira a referência.

Parâmetros

Parâmetro Obrigatório Type Descrição
resourceName/resourceIdentifier ou symbolicName/resourceIdentifier Sim string Nos modelos sem nomes simbólicos, especifique o nome ou o identificador exclusivo de um recurso. Ao referenciar um recurso no modelo atual, forneça apenas o nome do recurso como parâmetro. Ao fazer referência a um recurso implantado anteriormente ou quando o nome do recurso for ambíguo, forneça a ID do recurso.
Nos modelos com nomes simbólicos, especifique o nome simbólico ou o identificador exclusivo de um recurso. Ao referenciar um recurso no modelo atual, forneça apenas o nome simbólico do recurso como parâmetro. Ao referenciar um recurso implantado anteriormente, forneça a ID de recurso.
apiVersion Não string Versão da API do recurso especificado. Esse parâmetro é exigido quando o recurso não estiver provisionado no mesmo modelo. Normalmente, no formato aaaa-mm-dd. Para obter as versões de API válidas para seu recurso, confira referência de modelo.
'Full' Não string Valor que especifica se o objeto de recurso completo deve ser retornado. Se você não especificar 'Full', apenas o objeto de propriedades do recurso será retornado. O objeto completo inclui valores como a ID do recurso e o local.

Valor retornado

Cada tipo de recurso retorna propriedades diferentes para a função de referência. A função não retorna um único formato predefinido. Além disso, o valor retornado difere com base no valor do argumento 'Full'. Para ver as propriedades de um tipo de recurso, retorne o objeto na seção de saída, conforme mostra o exemplo.

Comentários

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

Normalmente, você usa a função reference para retornar um valor específico de um objeto, como o URI do ponto de extremidade de blob 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 recurso que não fizerem parte do esquema de propriedades. Por exemplo, para definir políticas de acesso ao cofre de chaves, obtenha as propriedades de identidade de uma máquina virtual.

{
  "type": "Microsoft.KeyVault/vaults",
  "apiVersion": "2022-07-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 função reference pode ser usada somente nas propriedades de uma definição de recurso e na seção de saídas de um modelo ou uma implantação. Ele não pode ser usado para propriedades de recurso, como type, name, location e outras propriedades de nível superior da definição de recurso. Quando usado com iteração de propriedade, você pode usar a função reference para input porque a expressão é atribuída à propriedade de recurso.

Você não pode usar a função reference para definir o valor da propriedade count em um loop de cópia. Você pode usar para definir outras propriedades no loop. A referência está bloqueada para a propriedade de contagem porque essa propriedade deve ser determinada antes que a função reference seja resolvida.

Para usar a função reference ou qualquer função list* na seção de saídas de um modelo aninhado, você deve definir o expressionEvaluationOptions para usar a avaliação de escopo interno ou usar um link vinculado em vez de um modelo aninhado.

Se você usar a função reference em um recurso implantado condicionalmente, a função será avaliada mesmo que o recurso não seja implantado. Você receberá um erro se a função reference se referir a um recurso que não existe. Use a função if para garantir que a função seja avaliada apenas quando o recurso estiver sendo implantado. Consulte a função if para um modelo de exemplo que usa if e reference com um recurso implantado condicionalmente.

Dependência implícita

Usando a função reference, você implicitamente declara que um recurso depende de outro recurso, se o recurso referenciado for provisionado no mesmo modelo, e consulta o recurso pelo nome (não pela ID de recurso). Você também não precisa usar a propriedade dependsOn. A função não é avaliada até que o recurso referenciado conclua a implantação.

Nome do recurso, nome simbólico ou identificador

Ao fazer referência a um recurso implantado no mesmo modelo de nome não simbólico, forneça o nome do recurso.

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

Ao fazer referência a um recurso implantado no mesmo modelo de nome simbólico, forneça o nome simbólico do recurso.

"value": "[reference('myStorage').primaryEndpoints]"

Ou

"value": "[reference('myStorage', '2022-09-01', 'Full').location]"

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

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

Para evitar ambiguidade sobre qual recurso você está referenciando, forneça um identificador de recurso totalmente qualificado.

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

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

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

Por exemplo:

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

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

Obter identidade gerenciada

As identidades gerenciadas para recursos do Azure são tipos de recursos de extensão criados implicitamente para alguns recursos. Como a identidade gerenciada não é definida explicitamente no modelo, você deve referenciar o recurso ao qual a identidade é aplicada. Use Full para obter todas as propriedades, incluindo a identidade criada implicitamente.

O padrão é:

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

Por exemplo, para obter a ID principal para uma identidade gerenciada aplicada a uma máquina virtual, use:

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

Ou, para obter a ID de locatário para uma identidade gerenciada aplicada a um conjunto de dimensionamento de máquinas virtuais, use:

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

Exemplo de referência

O exemplo a seguir implanta um recurso e faz referência a esse recurso.

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

O exemplo anterior retorna os dois objetos. O objeto de propriedades tem o 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 tem o seguinte formato:

{
  "apiVersion":"2022-09-01",
  "location":"southcentralus",
  "sku": {
    "name":"Standard_LRS",
    "tier":"Standard"
  },
  "tags":{},
  "kind":"Storage",
  "properties": {
    "creationTime":"2021-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 faz referência a uma conta de armazenamento que não está implantada nesse modelo. A conta de armazenamento já existe na mesma assinatura.

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

referências

references(symbolic name of a resource collection, ['Full', 'Properties])

A função references funciona da mesma forma que reference. Em vez de retornar um objeto que apresenta o estado de runtime de um recurso, a função references retorna uma matriz de objetos que representam uma coleção de estados de runtime do recurso. Essa função requer a linguagem de modelo do ARM versão 2.0 e com o nome simbólico habilitado:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  ...
}

No Bicep, não existe uma função explícita references. Em vez disso, o uso da coleção simbólica é empregado diretamente e, durante a geração do código, o Bicep o traduz para um modelo do ARM que utiliza a função references do modelo do ARM. Para obter mais informações, consulte Referência de coleções de recursos/módulos.

Parâmetros

Parâmetro Obrigatório Type Descrição
Nome simbólico de uma coleção de recursos Sim string Nome simbólico de uma coleção de recursos definida no modelo atual. A função references não dá suporte à referência de recursos externos ao modelo atual.
'Full', 'Properties' Não string Valor que especifica se uma matriz dos objetos de recurso completo deve ser retornada. O valor padrão é 'Properties'. Se você não especificar 'Full', apenas os objetos de propriedades dos recursos serão retornados. O objeto completo inclui valores como a ID do recurso e o local.

Valor retornado

Uma matriz da coleção de recursos. Cada tipo de recurso retorna propriedades diferentes para a função reference. Além disso, o valor retornado difere com base no valor do argumento 'Full'. Para obter mais informações, consulte Referência.

A ordem de saída de references será sempre organizada em ordem crescente com base no índice de cópia. Portanto, o primeiro recurso na coleção com índice 0 será exibido primeiro, seguido pelo índice 1 e assim por diante. Por exemplo, [worker-0, worker-1, worker-2, ...].

No exemplo anterior, se trabalho-0 e trabalho-2 estiverem implantados e trabalho-1 não estiver devido a uma condição falsa, a saída de references omitirá o recurso não implantado e exibirá os implantados, ordenados por seus números. A saída de references será [worker-0, worker-2, ...]. Se todos os recursos forem omitidos, a função retornará uma matriz vazia.

Usos válidos

A função references não pode ser usada em loops de cópia de recurso ou no Bicep para loop. Por exemplo, references não é permitido no seguinte cenário:

{
  resources: {
    "resourceCollection": {
       "copy": { ... },
       "properties": {
         "prop": "[references(...)]"
       }
    }
  }
}

Para usar a função references ou qualquer função list* na seção de saídas de um modelo aninhado, você deve definir o expressionEvaluationOptions para usar a avaliação de escopo interno ou usar um link vinculado em vez de um modelo aninhado.

Dependência implícita

Ao usar a função references, você declara de modo implícito que um recurso depende de outro. Você também não precisa usar a propriedade dependsOn. A função não é avaliada até que o recurso referenciado conclua a implantação.

Exemplo de referência

O exemplo a seguir implanta uma coleção de recursos e faz referência a essa coleção de recursos.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "Location for all resources."
      }
    },
    "numWorkers": {
      "type": "int",
      "defaultValue": 4,
      "metadata": {
        "description": "The number of workers"
      }
    }
  },
  "resources": {
    "containerWorkers": {
      "copy": {
        "name": "containerWorkers",
        "count": "[length(range(0, parameters('numWorkers')))]"
      },
      "type": "Microsoft.ContainerInstance/containerGroups",
      "apiVersion": "2023-05-01",
      "name": "[format('worker-{0}', range(0, parameters('numWorkers'))[copyIndex()])]",
      "location": "[parameters('location')]",
      "properties": {
        "containers": [
          {
            "name": "[format('worker-container-{0}', range(0, parameters('numWorkers'))[copyIndex()])]",
            "properties": {
              "image": "mcr.microsoft.com/azuredocs/aci-helloworld",
              "ports": [
                {
                  "port": 80,
                  "protocol": "TCP"
                }
              ],
              "resources": {
                "requests": {
                  "cpu": 1,
                  "memoryInGB": 2
                }
              }
            }
          }
        ],
        "osType": "Linux",
        "restartPolicy": "Always",
        "ipAddress": {
          "type": "Public",
          "ports": [
            {
              "port": 80,
              "protocol": "TCP"
            }
          ]
        }
      }
    },
    "containerController": {
      "type": "Microsoft.ContainerInstance/containerGroups",
      "apiVersion": "2023-05-01",
      "name": "controller",
      "location": "[parameters('location')]",
      "properties": {
        "containers": [
          {
            "name": "controller-container",
            "properties": {
              "command": [
                "echo",
                "[format('Worker IPs are {0}', join(map(references('containerWorkers', 'full'), lambda('w', lambdaVariables('w').properties.ipAddress.ip)), ','))]"
              ],
              "image": "mcr.microsoft.com/azuredocs/aci-helloworld",
              "ports": [
                {
                  "port": 80,
                  "protocol": "TCP"
                }
              ],
              "resources": {
                "requests": {
                  "cpu": 1,
                  "memoryInGB": 2
                }
              }
            }
          }
        ],
        "osType": "Linux",
        "restartPolicy": "Always",
        "ipAddress": {
          "type": "Public",
          "ports": [
            {
              "port": 80,
              "protocol": "TCP"
            }
          ]
        }
      },
      "dependsOn": [
        "containerWorkers"
      ]
    }
  },
  "outputs": {
    "workerIpAddresses": {
      "type": "string",
      "value": "[join(map(references('containerWorkers', 'full'), lambda('w', lambdaVariables('w').properties.ipAddress.ip)), ',')]"
    },
    "containersFull": {
      "type": "array",
      "value": "[references('containerWorkers', 'full')]"
    },
    "container": {
      "type": "array",
      "value": "[references('containerWorkers')]"
    }
  }
}

O exemplo anterior retorna os três objetos.

"outputs": {
  "workerIpAddresses": {
    "type": "String",
    "value": "20.66.74.26,20.245.100.10,13.91.86.58,40.83.249.30"
  },
  "containersFull": {
    "type": "Array",
    "value": [
      {
        "apiVersion": "2023-05-01",
        "condition": true,
        "copyContext": {
          "copyIndex": 0,
          "copyIndexes": {
            "": 0,
            "containerWorkers": 0
          },
          "name": "containerWorkers"
        },
        "copyLoopSymbolicName": "containerWorkers",
        "deploymentResourceLineInfo": {
          "lineNumber": 30,
          "linePosition": 25
        },
        "existing": false,
        "isAction": false,
        "isConditionTrue": true,
        "isTemplateResource": true,
        "location": "westus",
        "properties": {
          "containers": [
            {
              "name": "worker-container-0",
              "properties": {
                "environmentVariables": [],
                "image": "mcr.microsoft.com/azuredocs/aci-helloworld",
                "instanceView": {
                  "currentState": {
                    "detailStatus": "",
                    "startTime": "2023-07-31T19:25:31.996Z",
                    "state": "Running"
                  },
                  "restartCount": 0
                },
                "ports": [
                  {
                    "port": 80,
                    "protocol": "TCP"
                  }
                ],
                "resources": {
                  "requests": {
                    "cpu": 1.0,
                    "memoryInGB": 2.0
                  }
                }
              }
            }
          ],
          "initContainers": [],
          "instanceView": {
            "events": [],
            "state": "Running"
          },
          "ipAddress": {
            "ip": "20.66.74.26",
            "ports": [
              {
                "port": 80,
                "protocol": "TCP"
              }
            ],
            "type": "Public"
          },
          "isCustomProvisioningTimeout": false,
          "osType": "Linux",
          "provisioningState": "Succeeded",
          "provisioningTimeoutInSeconds": 1800,
          "restartPolicy": "Always",
          "sku": "Standard"
        },
        "provisioningOperation": "Create",
        "references": [],
        "resourceGroupName": "demoRg",
        "resourceId": "Microsoft.ContainerInstance/containerGroups/worker-0",
        "scope": "",
        "subscriptionId": "",
        "symbolicName": "containerWorkers[0]"
      },
      ...
    ]
  },
  "containers": {
    "type": "Array",
    "value": [
      {
        "containers": [
          {
            "name": "worker-container-0",
            "properties": {
              "environmentVariables": [],
              "image": "mcr.microsoft.com/azuredocs/aci-helloworld",
              "instanceView": {
                "currentState": {
                  "detailStatus": "",
                  "startTime": "2023-07-31T19:25:31.996Z",
                  "state": "Running"
                },
                "restartCount": 0
              },
              "ports": [
                {
                  "port": 80,
                  "protocol": "TCP"
                }
              ],
              "resources": {
                "requests": {
                  "cpu": 1.0,
                  "memoryInGB": 2.0
                }
              }
            }
          }
        ],
        "initContainers": [],
        "instanceView": {
          "events": [],
          "state": "Running"
        },
        "ipAddress": {
          "ip": "20.66.74.26",
          "ports": [
            {
              "port": 80,
              "protocol": "TCP"
            }
          ],
          "type": "Public"
        },
        "isCustomProvisioningTimeout": false,
        "osType": "Linux",
        "provisioningState": "Succeeded",
        "provisioningTimeoutInSeconds": 1800,
        "restartPolicy": "Always",
        "sku": "Standard"
      },
      ...
    ]
  }
}

resourceGroup

Confira a função de escopo resourceGroup.

No Bicep, use a função de escopo resourcegroup.

resourceId

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

Retorna o identificador exclusivo de um recurso. Você pode usar essa função quando o nome do recurso é ambíguo ou não provisionado no mesmo modelo. O formato do identificador retornado varia dependendo de se a implantação ocorre no escopo de um grupo de recursos, de assinatura, de um grupo de gerenciamento ou do locatário.

No bicep, use a função resourceId.

Parâmetros

Parâmetro Obrigatório Type Descrição
subscriptionId Não string (no formato GUID) O valor padrão é a assinatura atual. Especifique esse valor quando você precisar recuperar um recurso em outra assinatura. Forneça esse valor apenas ao implantar no escopo de um grupo de recursos ou assinatura.
resourceGroupName Não string O valor padrão é o grupo de recursos atual. Especifique esse valor quando você precisar recuperar um recurso em outro grupo de recursos. Forneça esse valor apenas ao implantar no escopo de um grupo de recursos.
resourceType Sim string Tipo de recurso, incluindo o namespace do provedor de recursos.
resourceName1 Sim string Nome do recurso.
resourceName2 Não string Próximo segmento de nome de recurso, se necessário.

Continue adicionando nomes de recursos como parâmetros quando o tipo de recurso incluir mais segmentos.

Valor retornado

A ID do recurso é retornada em formatos diferentes em escopos diferentes:

  • Escopo do grupo de recursos:

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

  • Escopo da assinatura:

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

  • Escopo do grupo de gerenciamento ou do locatário:

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

Para evitar confusão, recomendamos que você não use resourceId ao trabalhar com recursos implantados na assinatura, no grupo de gerenciamento ou no locatário. Em vez disso, use a função ID que foi projetada para o escopo.

Comentários

O número de parâmetros que você fornece varia dependendo de o recurso ser pai ou filho e de estar na mesma assinatura ou grupo de recursos.

Para obter a ID de recurso de um recurso pai na mesma assinatura e grupo de recursos, forneça o tipo e o nome do recurso.

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

Para obter a ID de recurso de um recurso filho, preste atenção ao número de segmentos no tipo de recurso. Forneça 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 a ID de recurso de um recurso na mesma assinatura, mas em um grupo de recursos diferente, forneça o nome do grupo de recursos.

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

Para obter a ID de recurso de um recurso em uma assinatura e um grupo de recursos diferentes, forneça a ID da assinatura e o nome do grupo de recursos.

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

Frequentemente, você precisa usar essa função ao usar uma conta de armazenamento ou rede virtual em um grupo de recursos alternativo. O exemplo a seguir mostra como um recurso de um grupo de recursos externo pode ser facilmente usado:

{
  "$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": "2022-11-01",
      "name": "[parameters('nicName')]",
      "location": "[parameters('location')]",
      "properties": {
        "ipConfigurations": [
          {
            "name": "ipconfig1",
            "properties": {
              "privateIPAllocationMethod": "Dynamic",
              "subnet": {
                "id": "[variables('subnet1Ref')]"
              }
            }
          }
        ]
      }
    }
  ]
}

Exemplo de ID de recurso

O exemplo a seguir retorna a ID de recurso de 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 padrão é:

Nome Tipo Valor
sameRGOutput String /subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft.Storage/storageAccounts/examplestorage
differentRGOutput String /subscriptions/{current-sub-id}/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage
differentSubOutput String /subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage
nestedResourceOutput String /subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft.SQL/servers/serverName/databases/databaseName

subscription

Confira a função de escopo de assinatura.

No Bicep, use a função de escopo subscription.

subscriptionResourceId

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

Retorna o identificador exclusivo de um recurso implantado no nível da assinatura.

No Bicep, use a função subscriptionResourceId.

Parâmetros

Parâmetro Obrigatório Type Descrição
subscriptionId Não string (no formato GUID) O valor padrão é a assinatura atual. Especifique esse valor quando você precisar recuperar um recurso em outra assinatura.
resourceType Sim string Tipo de recurso, incluindo o namespace do provedor de recursos.
resourceName1 Sim string Nome do recurso.
resourceName2 Não string Próximo segmento de nome de recurso, se necessário.

Continue adicionando nomes de recursos como parâmetros quando o tipo de recurso incluir mais segmentos.

Valor retornado

O identificador é retornado no seguinte formato:

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

Comentários

Use essa função para obter a ID de recurso dos recursos que são implantados na assinatura, em vez de um grupo de recursos. A ID retornada difere do valor retornado pela função resourceId ao não incluir um valor de grupo de recursos.

Exemplo de subscriptionResourceID

O modelo a seguir atribui uma função interna. Você pode implantá-lo em um grupo de recursos ou assinatura. Ele usa a função subscriptionResourceId para obter a ID de recurso para funções internas.

{
  "$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": "2022-04-01",
      "name": "[parameters('roleNameGuid')]",
      "properties": {
        "roleDefinitionId": "[variables(parameters('builtInRoleType'))]",
        "principalId": "[parameters('principalId')]"
      }
    }
  ]
}

managementGroupResourceId

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

Retorna o identificador exclusivo de um recurso implantado no nível do grupo de gerenciamento.

No Bicep, use a função de escopo managementGroupResourceId.

Parâmetros

Parâmetro Obrigatório Type Descrição
managementGroupResourceId Não string (no formato GUID) O valor padrão é o grupo de gerenciamento atual. Especifique esse valor quando você precisar recuperar um recurso em outro grupo de gerenciamento.
resourceType Sim string Tipo de recurso, incluindo o namespace do provedor de recursos.
resourceName1 Sim string Nome do recurso.
resourceName2 Não string Próximo segmento de nome de recurso, se necessário.

Continue adicionando nomes de recursos como parâmetros quando o tipo de recurso incluir mais segmentos.

Valor retornado

O identificador é retornado no seguinte formato:

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

Comentários

Use essa função para obter a ID de recurso dos recursos que são implantados no grupo de gerenciamento, em vez de um grupo de recursos. A ID retornada é diferente do valor retornado pela função resourceId, pois não inclui uma ID da assinatura e um valor de grupo de recursos.

managementGroupResourceID example

O modelo a seguir cria e atribui uma definição de política. Ele usa a função managementGroupResourceId para obter a 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."
      }
    }
  },
  "variables": {
    "mgScope": "[tenantResourceId('Microsoft.Management/managementGroups', parameters('targetMG'))]",
    "policyDefinitionName": "LocationRestriction"
  },
  "resources": [
    {
      "type": "Microsoft.Authorization/policyDefinitions",
      "apiVersion": "2021-06-01",
      "name": "[variables('policyDefinitionName')]",
      "properties": {
        "policyType": "Custom",
        "mode": "All",
        "parameters": {},
        "policyRule": {
          "if": {
            "not": {
              "field": "location",
              "in": "[parameters('allowedLocations')]"
            }
          },
          "then": {
            "effect": "deny"
          }
        }
      }
    },
    "location_lock": {
      "type": "Microsoft.Authorization/policyAssignments",
      "apiVersion": "2022-06-01",
      "name": "location-lock",
      "properties": {
        "scope": "[variables('mgScope')]",
        "policyDefinitionId": "[managementGroupResourceId('Microsoft.Authorization/policyDefinitions', variables('policyDefinitionName'))]"
      },
      "dependsOn": [
        "[format('Microsoft.Authorization/policyDefinitions/{0}', variables('policyDefinitionName'))]"
      ]
    }
  ]
}

tenantResourceId

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

Retorna o identificador exclusivo de um recurso implantado no nível do locatário.

No Bicep, use a função tenantResourceId.

Parâmetros

Parâmetro Obrigatório Type Descrição
resourceType Sim string Tipo de recurso, incluindo o namespace do provedor de recursos.
resourceName1 Sim string Nome do recurso.
resourceName2 Não string Próximo segmento de nome de recurso, se necessário.

Continue adicionando nomes de recursos como parâmetros quando o tipo de recurso incluir mais segmentos.

Valor retornado

O identificador é retornado no seguinte formato:

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

Comentários

Você usa essa função para obter a ID do recurso para um recurso que é implantado no locatário. A ID retornada difere dos valores retornados por outras funções de ID de recurso ao não incluir os valores de grupo de recursos ou de assinatura.

tenantResourceId example

As definições de políticas internas são recursos em nível de locatário. Para implantar uma atribuição de política que faz referência a uma definição de política interna, use a função tenantResourceId.

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

Próximas etapas