Funções de recurso para modelos ARM
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
name
e 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]"
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 o ID do recurso e apiVersion
o .
"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/11111111-1111-1111-1111-11111111111/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.