Funções de recurso para modelos ARM

Artigo
03/18/2024

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

extensionResourceId
lista*
pickZones [en]
provedores (preterido)
referência
Referências
resourceId
subscriptionResourceId
managementGroupResourceId
tenantResourceId

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

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

Gorjeta

Recomendamos o Bicep porque ele oferece os mesmos recursos que os modelos ARM e a sintaxe é mais fácil de usar. Para saber mais, consulte Funções de recurso .

extensionResourceId

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

Retorna a 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 aos seus recursos.

No Bicep, use a função extensionResourceId .

Parâmetros

Parâmetro	Necessário	Type	Description
baseResourceId	Sim	string	A ID do recurso ao qual o recurso de extensão é aplicado.
resourceType	Sim	string	Tipo do recurso de extensão, incluindo namespace do provedor de recursos.
nome_do_recurso1	Sim	string	Nome do recurso de extensão.
nome_do_recurso2	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 devolvido

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

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

O segmento de escopo varia de acordo com o recurso 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 do 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 uso dessa 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 uso dessa função com um grupo de gerenciamento é mostrado na próxima seção.

Exemplo de extensionResourceId

O exemplo a seguir retorna a 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 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ítica internas são recursos no nível do 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 para esta função varia de acordo com o nome das operações de lista. Cada implementação retorna valores para o tipo de recurso que dá suporte a 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	Necessário	Type	Description
resourceName ou resourceIdentifier	Sim	string	Identificador exclusivo do recurso.
apiVersion	Sim	string	Versão da API do estado de tempo de execução do recurso. Normalmente, no formato, aaaa-mm-dd.
functionValues	Não	objeto	Um objeto que tem valores para a função. Forneça esse objeto somente para funções que suportam o recebimento de um objeto com valores de parâmetro, como `listAccountSas` em uma conta de armazenamento. Um exemplo de passagem de valores de função é mostrado neste artigo.

Utilizações válidas

As funções de lista 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á-los com count porque a contagem deve ser determinada antes que a função de lista seja resolvida.

Implementações

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

Tipo de recurso	Nome da função
Microsoft.Addons/supportProviders	ListSupportPlanInfo
Microsoft.AnalysisServices/servidores	listGatewayStatus
Microsoft.ApiManagement/service/authorizationServers	listaSegredos
Microsoft.ApiManagement/serviço/gateways	listKeys
Microsoft.ApiManagement/service/identityProviders	listaSegredos
Microsoft.ApiManagement/service/namedValues	listValue
Microsoft.ApiManagement/service/openidConnectProviders	listaSegredos
Microsoft.ApiManagement/serviço/assinaturas	listaSegredos
Microsoft.AppConfiguration/configurationStores	ListKeys
Microsoft.AppPlatform/primavera	listTestKeys
Microsoft.Automation/automationContas	listKeys
Microsoft.Batch/batchAccounts	listKeys
Microsoft.BatchAI/workspaces/experiments/jobs	ListOutputFiles
Microsoft.BotService/botServices/canais	listChannelWithKeys
Microsoft.Cache/redis	listKeys
Microsoft.CognitiveServices/contas	listKeys
Microsoft.ContainerRegistry/registries	listCredentials
Microsoft.ContainerRegistry/registries	listUsos
Microsoft.ContainerRegistry/registries/agentpools	listQueueStatus
Microsoft.ContainerRegistry/registries/buildTasks	listSourceRepositoryProperties
Microsoft.ContainerRegistry/registries/buildTasks/steps	listBuildArguments
Microsoft.ContainerRegistry/registries/taskruns	listDetalhes
Microsoft.ContainerRegistry/registros/webhooks	listEventos
Microsoft.ContainerRegistry/registries/runs	listLogSasUrl
Microsoft.ContainerRegistry/registros/tarefas	listDetalhes
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/factories/integrationruntimes	listauthkeys
Microsoft.DataLakeAnalytics/accounts/storageAccounts/Containers	listSasTokens
Microsoft.DataShare/contas/compartilhamentos	listSincronizações
Microsoft.DataShare/accounts/shareSubscriptions	listSourceShareSynchronizationSettings
Microsoft.DataShare/accounts/shareSubscriptions	listSynchronizationDetails
Microsoft.DataShare/accounts/shareSubscriptions	listSincronizações
Microsoft.Devices/iotHubs	listKeys
Microsoft.Devices/iotHubs/iotHubKeys	listKeys
Microsoft.Devices/provisioningServices/chaves	listKeys
Microsoft.Devices/provisioningServices	listKeys
Microsoft.DevTestLab/labs	ListVhds
Microsoft.DevTestLab/labs/agendas	ListApplicable
Microsoft.DevTestLab/labs/users/serviceFabrics	ListApplicableSchedules
Microsoft.DevTestLab/labs/virtualMachines	ListApplicableSchedules
Microsoft.DocumentDB/databaseAccounts	listKeys
Microsoft.DocumentDB/databaseAccounts/notebookWorkspaces	listConnectionInfo
Microsoft.DomainRegistration/topLevelDomains	listAcordos
Microsoft.EventHub/namespaces/authorizationRules	listKeys
Microsoft.EventHub/namespaces/disasterRecoveryConfigs/authorizationRules	listKeys
Microsoft.EventHub/namespaces/eventhubs/authorizationRules	listKeys
Microsoft.ImportExport/jobs	listBitLockerKeys
Microsoft.Kusto/Clusters/Bases de Dados	ListPrincipals
Microsoft.LabServices/labs/usuários	list
Microsoft.LabServices/labs/virtualMachines	list
Microsoft.Logic/integrationAccounts/agreements	listContentCallbackUrl
Microsoft.Logic/integrationContas/assemblies	listContentCallbackUrl
Microsoft.Logic/integrationAccounts	listCallbackUrl
Microsoft.Logic/integrationAccounts	listKeyVaultKeys
Microsoft.Logic/integrationContas/mapas	listContentCallbackUrl
Microsoft.Logic/integrationContas/parceiros	listContentCallbackUrl
Microsoft.Logic/integrationAccounts/schemas	listContentCallbackUrl
Microsoft.Logic/fluxos de trabalho	listCallbackUrl
Microsoft.Logic/fluxos de trabalho	listSwagger
Microsoft.Logic/workflows/runs/actions	listExpressionTraces
Microsoft.Logic/workflows/runs/actions/repetitions	listExpressionTraces
Microsoft.Logic/fluxos de trabalho/triggers	listCallbackUrl
Microsoft.Logic/fluxos de trabalho/versões/triggers	listCallbackUrl
Microsoft.MachineLearning/webServices	listkeys
Microsoft.MachineLearning/Espaços de trabalho	ListWorkspaceKeys
Microsoft.Maps/contas	listKeys
Microsoft.Media/mediaservices/assets	listContainerSas
Microsoft.Media/mediaservices/assets	listStreamingLocalizadores
Microsoft.Media/mediaservices/streamingLocalizadores	listContentKeys
Microsoft.Media/mediaservices/streamingLocalizadores	listPaths
Microsoft.Network/applicationSecurityGroups	listIpConfigurations
Microsoft.NotificationHubs/Namespaces/authorizationRules	listkeys
Microsoft.NotificationHubs/Namespaces/NotificationHubs/authorizationRules	listkeys
Microsoft.OperationalInsights/espaços de trabalho	list
Microsoft.OperationalInsights/espaços de trabalho	listKeys
Microsoft.PolicyInsights/remediações	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/conexões	ListConsentLinks
Microsoft.Web/customApis	listWsdlInterfaces
microsoft.web/localizações	listwsdlinterfaces
Microsoft.Web/ApiManagementAccounts/APIS/Conexões	ListConnectionKeys
Microsoft.Web/ApiManagementAccounts/APIS/Conexões	`listSecrets`
microsoft.web/sites/backups	list
Microsoft.Web/sites/config	list
microsoft.web/sites/funções	listKeys
microsoft.web/sites/funções	listaSegredos
microsoft.web/sites/hybridconnectionnamespaces/relays	listKeys
microsoft.web/sites	ListSyncFunctionTriggerStatus
microsoft.web/sites/slots/funções	listaSegredos
microsoft.web/sites/slots/backups	list
Microsoft.Web/sites/slots/config	list
microsoft.web/sites/slots/funções	listaSegredos

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

Exiba as operações da API REST para um provedor de recursos e procure operações de lista. Por exemplo, as contas de armazenamento têm a operação listKeys.
Use o cmdlet Get-AzProviderOperation PowerShell. O exemplo a seguir obtém todas as operações de lista para contas de armazenamento:
```
Get-AzProviderOperation -OperationSearchString "Microsoft.Storage/*" | where {$_.Operation -like "*list*"} | FT Operation
```

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

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

Valor devolvido

O objeto retornado varia de acordo com a list função que você usa. Por exemplo, o listKeys para uma conta de armazenamento retorna 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-a na seção de saídas, conforme mostrado no modelo de exemplo.

Observações

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

Se você usar uma list função em um recurso implantado condicionalmente, a função será avaliada mesmo que o recurso não seja implantado. Você receberá um erro se a list função se referir a um recurso que não existe. Use a if função para garantir que a função só seja avaliada 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 próximo exemplo mostra uma list função que usa um parâmetro. Neste caso, a função é listAccountSas. Passe um objeto pelo tempo de expiração. O prazo de validade deve ser 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 [en]

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

Determina se um tipo de recurso oferece suporte a zonas para o local ou região especificados. Esta função suporta apenas recursos zonais. Os serviços redundantes de zona retornam uma matriz vazia. Para obter mais informações, consulte Serviços do Azure que dão suporte a zonas de disponibilidade.

No Bicep, use a função pickZones .

Parâmetros

Parâmetro	Necessário	Type	Description
providerNamespace	Sim	string	O namespace do provedor de recursos para o tipo de recurso para verificar o suporte à zona.
resourceType	Sim	string	O tipo de recurso para verificar o suporte de zona.
localização	Sim	string	A região para verificar o suporte da zona.
númerodeZonas	Não	integer	O número de zonas lógicas a serem retornadas. A predefiniçã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 com várias zonas, o valor deve ser menor ou igual ao número de zonas suportadas.
offset	Não	integer	O deslocamento da zona lógica inicial. A função retorna um erro se o deslocamento mais numberOfZones exceder o número de zonas suportadas.

Valor devolvido

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

[
    "1"
]

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

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

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

[
]

Observações

Há diferentes categorias para as Zonas de Disponibilidade do Azure - zonal e com redundância de zona. A pickZones função pode ser usada para retornar uma zona de disponibilidade para um recurso zonal. Para serviços redundantes de zona (ZRS), a função retorna uma matriz vazia. Os recursos zonais normalmente têm uma zones propriedade no nível superior da definição de recurso. Para determinar a categoria de suporte para zonas de disponibilidade, consulte Serviços do Azure que dão suporte a zonas de disponibilidade.

Para determinar se uma determinada região ou local do Azure dá suporte a zonas de disponibilidade, chame a pickZones função com um tipo de recurso zonal, como Microsoft.Network/publicIPAddresses. Se a resposta não estiver vazia, a região oferece suporte a zonas de disponibilidade.

exemplo de pickZones

O modelo a seguir mostra três resultados para usar a 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 retorna três matrizes.

Nome	Tipo	valor
suportado	matriz	[ "1" ]
notSupportedRegion	matriz	[]
notSupportedType	matriz	[]

Você pode usar a resposta de pickZones para determinar se deve fornecer null para zonas ou atribuir máquinas virtuais a zonas diferentes. 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 pickZones função 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')]"
    }
  }
]

fornecedores

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

No Bicep, a função de provedores é preterida.

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

referência

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 tempo de execução de um recurso. A saída e o reference comportamento da função dependem muito de como cada provedor de recursos (RP) implementa suas respostas PUT e GET. Para retornar uma matriz de objetos que representam os estados de tempo de execução de uma coleção de recursos, consulte referências.

O bíceps 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, recomenda-se usar o nome simbólico para o recurso. Veja a referência.

Parâmetros

Parâmetro	Necessário	Type	Description
resourceName/resourceIdentifier ou symbolicName/resourceIdentifier	Sim	string	Nos modelos sem nomes simbólicos, especifique o nome ou identificador exclusivo de um recurso. Ao fazer referência a 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 identificador exclusivo de um recurso. Ao fazer referência a um recurso no modelo atual, forneça apenas o nome simbólico do recurso como parâmetro. Ao fazer referência a um recurso implantado anteriormente, forneça a ID do recurso.
apiVersion	Não	string	Versão da API do recurso especificado. Esse parâmetro é necessário quando o recurso não é provisionado dentro do mesmo modelo. Normalmente, no formato, aaaa-mm-dd. Para obter versões de API válidas para seu recurso, consulte Referência de modelo.
'Completo'	Não	string	Valor que especifica se o objeto de recurso completo deve ser retornado. Se você não especificar `'Full'`, somente o objeto de propriedades do recurso será retornado. O objeto completo inclui valores como o ID do recurso e o local.

Valor devolvido

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 'Full' argumento. Para ver as propriedades de um tipo de recurso, retorne o objeto na seção de saídas, conforme mostrado no exemplo.

Observações

A função de referência recupera o estado de tempo de execução de um recurso implantado anteriormente 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 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 recursos que não fazem 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"
          ]
        }
      }
    ],
    ...

Utilizações válidas

A reference função só pode ser usada na seção de saídas de um modelo ou objeto de implantação e propriedades de uma definição de recurso. Ele não pode ser usado para propriedades de recurso como type, location namee outras propriedades de nível superior da definição de recurso. Quando usado com iteração de propriedade, você pode usar a reference função para input porque a expressão é atribuída à propriedade de recurso.

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

Para usar a reference função ou qualquer list* função 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 modelo vinculado em vez de aninhado.

Se você usar a reference função em um recurso implantado condicionalmente, a função será avaliada mesmo que o recurso não seja implantado. Você receberá um erro se a reference função se referir a um recurso que não existe. Use a if função para garantir que a função só seja avaliada 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 reference função, você declara implicitamente que um recurso depende de outro recurso se o recurso referenciado for provisionado dentro do mesmo modelo e você se referir ao recurso por seu nome (não ID do recurso). Você não precisa usar também a dependsOn propriedade. A função não é avaliada até que o recurso referenciado tenha concluído 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]"

"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 o ID do recurso e apiVersiono .

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

Para evitar ambiguidade sobre qual recurso você está referenciando, você pode fornecer 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 combinar segmentos do tipo e 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/myExt está correto Microsoft.Compute/virtualMachines/extensions/myVM/myExt não está correto

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

Obtenha 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 fazer referência ao 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 de 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 do locatário para uma identidade gerenciada 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 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 properties 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":"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 é implantada neste modelo. A conta de armazenamento já existe dentro da 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 references função funciona de forma semelhante a reference. Em vez de retornar um objeto que apresenta o estado de tempo de execução de um recurso, a references função retorna uma matriz de objetos que representam os estados de tempo de execução de uma coleção de recursos. Esta função requer a versão 2.0 do idioma do modelo ARM e com o nome simbólico ativado:

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

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

Parâmetros

Parâmetro	Necessário	Type	Description
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 `references` função não suporta a referência de recursos externos ao modelo atual.
'Completo', 'Propriedades'	Não	string	Valor que especifica se deve retornar uma matriz dos objetos de recurso completos. O valor predefinido é `'Properties'`. Se você não especificar `'Full'`, somente os objetos de propriedades dos recursos serão retornados. O objeto completo inclui valores como o ID do recurso e o local.

Valor devolvido

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

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

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

Utilizações válidas

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

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

Para usar a references função ou qualquer list* função 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 modelo vinculado em vez de aninhado.

Dependência implícita

Usando a references função, você declara implicitamente que um recurso depende de outro recurso. Você não precisa usar também a dependsOn propriedade. A função não é avaliada até que o recurso referenciado tenha concluído 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

Consulte a função de escopo resourceGroup.

No Bicep, use a função de escopo do grupo de recursos.

resourceId

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

Retorna o identificador exclusivo de um recurso. Você usa essa função quando o nome do recurso é ambíguo ou não é provisionado dentro do mesmo modelo. O formato do identificador retornado varia com base no fato de a implantação ocorrer no escopo de um grupo de recursos, assinatura, grupo de gerenciamento ou locatário.

No Bicep, use a função resourceId .

Parâmetros

Parâmetro	Necessário	Type	Description
subscriptionId	Não	string (em formato GUID)	O valor padrão é a assinatura atual. Especifique esse valor quando precisar recuperar um recurso em outra assinatura. Forneça esse valor somente 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 precisar recuperar um recurso em outro grupo de recursos. Forneça esse valor somente ao implantar no escopo de um grupo de recursos.
resourceType	Sim	string	Tipo de recurso, incluindo namespace do provedor de recursos.
nome_do_recurso1	Sim	string	Nome do recurso.
nome_do_recurso2	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 devolvido

O ID do recurso é retornado em diferentes formatos em escopos diferentes:

Âmbito do grupo de recursos:

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

Âmbito da subscrição:

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

Grupo de gerenciamento ou escopo do locatário:

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

Para evitar confusões, 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 projetada para o escopo.

Para recursos no nível de assinatura, use a função subscriptionResourceId .
Para recursos de nível de grupo de gerenciamento, use a função managementGroupResourceId . Use a função extensionResourceId para fazer referência a um recurso que é implementado como uma extensão de um grupo de gerenciamento. Por exemplo, definições de política personalizadas que são implantadas em um grupo de gerenciamento são extensões do grupo de gerenciamento. Use a função tenantResourceId para fazer referência a recursos implantados no locatário, mas disponíveis em seu grupo de gerenciamento. Por exemplo, as definições de política internas são implementadas como recursos no nível do locatário.
Para recursos de nível de locatário, use a função tenantResourceId . Use tenantResourceId para definições de política internas porque elas são implementadas no nível do locatário.

Observações

O número de parâmetros fornecidos varia com base no facto de o recurso ser um recurso pai ou filho e se o recurso está na mesma subscrição ou grupo de recursos.

Para obter a ID do recurso para 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 do recurso para 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 do recurso para um recurso no mesmo grupo de recursos de assinatura, mas diferente, forneça o nome do grupo de recursos.

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

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

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

Muitas vezes, 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 externos 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 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 padrão é:

Nome	Tipo	valor
sameRGOutput	String	/subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft.Storage/storageAccounts/examplestorage
diferenteRGOutput	String	/subscriptions/{current-sub-id}/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage
diferenteSuboutput	String	/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage
nestedResourceOutput	String	/subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft.SQL/servers/serverName/databases/databaseName

subscrição

Consulte a função de escopo da assinatura.

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

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	Necessário	Type	Description
subscriptionId	Não	string (em formato GUID)	O valor padrão é a assinatura atual. Especifique esse valor quando precisar recuperar um recurso em outra assinatura.
resourceType	Sim	string	Tipo de recurso, incluindo namespace do provedor de recursos.
nome_do_recurso1	Sim	string	Nome do recurso.
nome_do_recurso2	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 devolvido

O identificador é retornado no seguinte formato:

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

Observações

Use essa função para obter a ID do recurso para 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 por 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 subscriptionResourceId função para obter o ID do 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 managementGroupResourceId .

Parâmetros

Parâmetro	Necessário	Type	Description
managementGroupResourceId	Não	string (em formato GUID)	O valor padrão é o grupo de gerenciamento atual. Especifique esse valor quando precisar recuperar um recurso em outro grupo de gerenciamento.
resourceType	Sim	string	Tipo de recurso, incluindo namespace do provedor de recursos.
nome_do_recurso1	Sim	string	Nome do recurso.
nome_do_recurso2	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 devolvido

O identificador é retornado no seguinte formato:

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

Observações

Use essa função para obter a ID do recurso para recursos que são implantados no grupo de gerenciamento em vez de um grupo de recursos. A ID retornada difere do valor retornado pela função resourceId por não incluir uma ID de assinatura e um valor de grupo de recursos.

Exemplo de managementGroupResourceID

O modelo a seguir cria e atribui uma definição de política. Ele usa a managementGroupResourceId função para obter o ID do recurso para a definição da 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	Necessário	Type	Description
resourceType	Sim	string	Tipo de recurso, incluindo namespace do provedor de recursos.
nome_do_recurso1	Sim	string	Nome do recurso.
nome_do_recurso2	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 devolvido

O identificador é retornado no seguinte formato:

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

Observações

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

Exemplo de tenantResourceId

As definições de política internas são recursos no nível do locatário. Para implantar uma atribuição de política que faça referência a uma definição de política interna, 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": "2022-06-01",
      "properties": {
        "scope": "[subscriptionResourceId('Microsoft.Resources/resourceGroups', resourceGroup().name)]",
        "policyDefinitionId": "[tenantResourceId('Microsoft.Authorization/policyDefinitions', parameters('policyDefinitionID'))]"
      }
    }
  ]
}

Próximos passos

Para obter uma descrição das seções em um modelo ARM, consulte Compreender a estrutura e a sintaxe dos modelos ARM.
Para mesclar vários modelos, consulte Usando modelos vinculados e aninhados ao implantar recursos do Azure.
Para iterar um número especificado de vezes ao criar um tipo de recurso, consulte Iteração de recurso em modelos ARM.
Para ver como implantar o modelo que você criou, consulte Implantar recursos com modelos ARM e Azure PowerShell.

Partilhar via

Funções de recurso para modelos ARM

extensionResourceId

Parâmetros

Valor devolvido

Exemplo de extensionResourceId

lista*

Parâmetros

Utilizações válidas

Implementações

Valor devolvido

Observações

Exemplo de lista

pickZones [en]

Parâmetros

Valor devolvido

Observações

exemplo de pickZones

fornecedores

referência

Parâmetros

Valor devolvido

Observações

Utilizações válidas

Dependência implícita

Nome do recurso, Nome simbólico ou identificador

Obtenha identidade gerenciada

Exemplo de referência

Referências

Parâmetros

Valor devolvido

Utilizações válidas

Dependência implícita

Exemplo de referência

resourceGroup

resourceId

Parâmetros

Valor devolvido

Observações

Exemplo de ID de recurso

subscrição

subscriptionResourceId

Parâmetros

Valor devolvido

Observações

exemplo de subscriptionResourceID

managementGroupResourceId

Parâmetros

Valor devolvido

Observações

Exemplo de managementGroupResourceID

tenantResourceId

Parâmetros

Valor devolvido

Observações

Exemplo de tenantResourceId

Próximos passos

Comentários

Recursos adicionais