Funções de recurso para modelos ARM

  • Artigo

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

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, locationnamee 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 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/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