Funções de recursos para modelos do ARM

  • Artigo
  • 24 minutos para ler

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

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

Para obter valores de âmbito de implementação, veja Funções de âmbito.

Dica

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

extensionResourceId

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

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

No Bicep, utilize a função extensionResourceId .

Parâmetros

Parâmetro Necessário Tipo Description
baseResourceId Yes string O ID do recurso ao qual o recurso de extensão é aplicado.
resourceType Yes string Tipo do recurso de extensão, incluindo o espaço de nomes do fornecedor de recursos.
resourceName1 Yes string Nome do recurso de extensão.
resourceName2 No string Próximo segmento de nome de recurso, se necessário.

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

Valor devolvido

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

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

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

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

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

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

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

É apresentado um exemplo de utilização desta função com um grupo de recursos na secção seguinte.

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

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

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

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

Na secção seguinte, é apresentado um exemplo de utilização desta função com um grupo de gestão.

exemplo extensionResourceId

O exemplo seguinte devolve o ID de recurso de 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 implementada num grupo de gestão é implementada como um recurso de extensão. Para criar e atribuir uma política, implemente o seguinte modelo num grupo de gestão.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "_generator": {
      "name": "bicep",
      "version": "0.5.6.12127",
      "templateHash": "1532257987028557958"
    }
  },
  "parameters": {
    "targetMG": {
      "type": "string",
      "metadata": {
        "description": "Target Management Group"
      }
    },
    "allowedLocations": {
      "type": "array",
      "defaultValue": [
        "australiaeast",
        "australiasoutheast",
        "australiacentral"
      ],
      "metadata": {
        "description": "An array of the allowed locations, all other locations will be denied by the created policy."
      }
    }
  },
  "variables": {
    "mgScope": "[tenantResourceId('Microsoft.Management/managementGroups', parameters('targetMG'))]",
    "policyDefinitionName": "LocationRestriction"
  },
  "resources": [
    {
      "type": "Microsoft.Authorization/policyDefinitions",
      "apiVersion": "2020-03-01",
      "name": "[variables('policyDefinitionName')]",
      "properties": {
        "policyType": "Custom",
        "mode": "All",
        "parameters": {},
        "policyRule": {
          "if": {
            "not": {
              "field": "location",
              "in": "[parameters('allowedLocations')]"
            }
          },
          "then": {
            "effect": "deny"
          }
        }
      }
    },
    {
      "type": "Microsoft.Authorization/policyAssignments",
      "apiVersion": "2020-03-01",
      "name": "location-lock",
      "properties": {
        "scope": "[variables('mgScope')]",
        "policyDefinitionId": "[extensionResourceId(variables('mgScope'), 'Microsoft.Authorization/policyDefinitions', variables('policyDefinitionName'))]"
      },
      "dependsOn": [
        "[extensionResourceId(managementGroup().id, 'Microsoft.Authorization/policyDefinitions', variables('policyDefinitionName'))]"
      ]
    }
  ]
}

As definições de política incorporadas são recursos ao nível do inquilino. Para obter um exemplo de implementação de uma definição de política incorporada, veja tenantResourceId.

list*

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

A sintaxe desta função varia consoante o nome das operações de lista. Cada implementação devolve valores para o tipo de recurso que suporta uma operação de lista. O nome da operação tem de começar e list pode ter um sufixo. Algumas utilizações comuns são list, listKeys, listKeyValuee listSecrets.

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

Parâmetros

Parâmetro Necessário Tipo Description
resourceName ou resourceIdentifier Yes string Identificador exclusivo do recurso.
apiVersion Yes string Versão da API do estado do runtime de recursos. Normalmente, no formato yyyy-mm-dd.
functionValues No objeto Um objeto que tem valores para a função. Forneça apenas este objeto para funções que suportem a receção de um objeto com valores de parâmetros, como listAccountSas numa conta de armazenamento. Neste artigo, é apresentado um exemplo de valores de função de transmissão.

Utilizações válidas

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

Quando utilizado com a iteração de propriedades, pode utilizar as funções de lista para input porque a expressão está atribuída à propriedade do recurso. Não pode utilizá-los porque count a contagem tem de ser determinada antes de a função de lista ser resolvida.

Implementações

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

Tipo de recurso Nome da função
Microsoft.Addons/supportProviders listsupportplaninfo
Microsoft.AnalysisServices/servers listGatewayStatus
Microsoft.ApiManagement/service/authorizationServers listSecrets
Microsoft.ApiManagement/service/gateways listKeys
Microsoft.ApiManagement/service/identityProviders listSecrets
Microsoft.ApiManagement/service/namedValues listValue
Microsoft.ApiManagement/service/openidConnectProviders listSecrets
Microsoft.ApiManagement/service/subscriptions listSecrets
Microsoft.AppConfiguration/configurationStores ListKeys
Microsoft.AppPlatform/Spring listTestKeys
Microsoft.Automation/automationAccounts listKeys
Microsoft.Batch/batchAccounts listKeys
Microsoft.BatchAI/áreas de trabalho/experimentações/tarefas listoutputfiles
Microsoft.BotService/botServices/channels listChannelWithKeys
Microsoft.Cache/redis listKeys
Microsoft.CognitiveServices/accounts listKeys
Microsoft.ContainerRegistry/registries listBuildSourceUploadUrl
Microsoft.ContainerRegistry/registries listCredentials
Microsoft.ContainerRegistry/registries listUsages
Microsoft.ContainerRegistry/registries/agentpools listQueueStatus
Microsoft.ContainerRegistry/registries/buildTasks listSourceRepositoryProperties
Microsoft.ContainerRegistry/registries/buildTasks/steps listBuildArguments
Microsoft.ContainerRegistry/registries/taskruns listDetails
Microsoft.ContainerRegistry/registries/webhooks listEvents
Microsoft.ContainerRegistry/registries/runs listLogSasUrl
Microsoft.ContainerRegistry/registries/tasks listDetails
Microsoft.ContainerService/managedClusters listClusterAdminCredential
Microsoft.ContainerService/managedClusters listClusterMonitoringUserCredential
Microsoft.ContainerService/managedClusters listClusterUserCredential
Microsoft.ContainerService/managedClusters/accessProfiles listCredential
Microsoft.DataBox/jobs listCredentials
Microsoft.DataFactory/datafactories/gateways listauthkeys
Microsoft.DataFactory/factorys/integrationruntimes listauthkeys
Microsoft.DataLakeAnalytics/accounts/storageAccounts/Containers listSasTokens
Microsoft.DataShare/accounts/shares listSynchronizations
Microsoft.DataShare/accounts/shareSubscriptions listSourceShareSynchronizationSettings
Microsoft.DataShare/accounts/shareSubscriptions listSynchronizationDetails
Microsoft.DataShare/accounts/shareSubscriptions listSynchronizations
Microsoft.Devices/iotHubs listKeys
Microsoft.Devices/iotHubs/iotHubKeys listKeys
Microsoft.Devices/provisioningServices/keys listKeys
Microsoft.Devices/provisioningServices listKeys
Microsoft.DevTestLab/labs ListVhds
Microsoft.DevTestLab/labs/schedules ListApplicable
Microsoft.DevTestLab/labs/users/serviceFabrics ListApplicableSchedules
Microsoft.DevTestLab/labs/virtualMachines ListApplicableSchedules
Microsoft.DocumentDB/databaseAccounts listConnectionStrings
Microsoft.DocumentDB/databaseAccounts listKeys
Microsoft.DocumentDB/databaseAccounts/notebookWorkspaces listConnectionInfo
Microsoft.DomainRegistration/topLevelDomains listAgreements
Microsoft.EventGrid/domains listKeys
Microsoft.EventGrid/topics listKeys
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/users list
Microsoft.LabServices/labs/virtualMachines list
Microsoft.Logic/integrationAccounts/agreements listContentCallbackUrl
Microsoft.Logic/integrationAccounts/assemblies listContentCallbackUrl
Microsoft.Logic/integrationAccounts listCallbackUrl
Microsoft.Logic/integrationAccounts listKeyVaultKeys
Microsoft.Logic/integrationAccounts/maps listContentCallbackUrl
Microsoft.Logic/integrationAccounts/partners listContentCallbackUrl
Microsoft.Logic/integrationAccounts/schemas listContentCallbackUrl
Microsoft.Logic/workflows listCallbackUrl
Microsoft.Logic/workflows listSwagger
Microsoft.Logic/workflows/runs/actions listExpressionTraces
Microsoft.Logic/workflows/runs/actions/repetitions listExpressionTraces
Microsoft.Logic/workflows/triggers listCallbackUrl
Microsoft.Logic/workflows/versions/triggers listCallbackUrl
Microsoft.MachineLearning/webServices listkeys
Microsoft.MachineLearning/Workspaces listworkspacekeys
Microsoft.MachineLearningServices/workspaces/computes listKeys
Microsoft.MachineLearningServices/workspaces/computes listNodes
Microsoft.MachineLearningServices/workspaces listKeys
Microsoft.Maps/accounts listKeys
Microsoft.Media/mediaservices/assets listContainerSas
Microsoft.Media/mediaservices/assets listStreamingLocators
Microsoft.Media/mediaservices/streamingLocators listContentKeys
Microsoft.Media/mediaservices/streamingLocators listPaths
Microsoft.Network/applicationSecurityGroups listIpConfigurations
Microsoft.NotificationHubs/Namespaces/authorizationRules listkeys
Microsoft.NotificationHubs/Namespaces/NotificationHubs/authorizationRules listkeys
Microsoft.OperationalInsights/workspaces list
Microsoft.OperationalInsights/workspaces listKeys
Microsoft.PolicyInsights/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.ServiceBus/namespaces/topics/authorizationRules listKeys
Microsoft.SignalRService/SignalR listKeys
Microsoft.Storage/storageAccounts listAccountSas
Microsoft.Storage/storageAccounts listKeys
Microsoft.Storage/storageAccounts listServiceSas
Microsoft.StorSimple/managers/devices listFailoverSets
Microsoft.StorSimple/managers/devices listFailoverTargets
Microsoft.StorSimple/managers listActivationKey
Microsoft.StorSimple/managers listPublicEncryptionKey
Microsoft.Synapse/workspaces/integrationRuntimes listAuthKeys
Microsoft.Web/connectionGateways ListStatus
microsoft.web/connections listconsentlinks
Microsoft.Web/customApis listWsdlInterfaces
microsoft.web/locations listwsdlinterfaces
microsoft.web/apimanagementaccounts/apis/connections listconnectionkeys
microsoft.web/apimanagementaccounts/apis/connections listSecrets
microsoft.web/sites/cópias de segurança list
Microsoft.Web/sites/configuração list
microsoft.web/sites/funções listKeys
microsoft.web/sites/funções listSecrets
microsoft.web/sites/hybridconnectionnamespaces/relays listKeys
microsoft.web/sites listsyncfunctiontriggerstatus
microsoft.web/sites/slots/functions listSecrets
microsoft.web/sites/slots/backups list
Microsoft.Web/sites/slots/config list
microsoft.web/sites/slots/functions listSecrets

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

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

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

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

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

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

Valor devolvido

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

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

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

Observações

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

Se utilizar uma list função num recurso que é implementado condicionalmente, a função é avaliada mesmo que o recurso não esteja implementado. Receberá um erro se a list função se referir a um recurso que não existe. Utilize a if função para se certificar de que a função só é avaliada quando o recurso está a ser implementado. Veja a função if para um modelo de exemplo que utiliza if e list com um recurso implementado condicionalmente.

Exemplo de lista

O exemplo seguinte utiliza listKeys ao definir um valor para scripts de implementação.

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

O exemplo seguinte mostra uma list função que utiliza um parâmetro. Neste caso, a função é listAccountSas. Transmita um objeto durante o tempo de expiração. O tempo de expiração tem de ser no futuro.

"parameters": {
  "accountSasProperties": {
    "type": "object",
    "defaultValue": {
      "signedServices": "b",
      "signedPermission": "r",
      "signedExpiry": "2020-08-20T11:00:00Z",
      "signedResourceTypes": "s"
    }
  }
},
...
"sasToken": "[listAccountSas(parameters('storagename'), '2018-02-01', parameters('accountSasProperties')).accountSasToken]"

pickZones

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

Determina se um tipo de recurso suporta zonas para a localização ou região especificada. Esta função só suporta recursos zonais. Os serviços com redundância entre zonas devolvem uma matriz vazia. Para obter mais informações, veja Serviços do Azure que suportam Zonas de Disponibilidade.

No Bicep, utilize a função pickZones .

Parâmetros

Parâmetro Necessário Tipo Description
providerNamespace Yes string O espaço de nomes do fornecedor de recursos para o tipo de recurso para verificar a existência de suporte de zona.
resourceType Yes string O tipo de recurso para verificar a existência de suporte de zona.
localização Yes string A região a verificar a existência de suporte de zona.
numberOfZones No número inteiro O número de zonas lógicas a devolver. A predefinição é 1. O número tem de ser um número inteiro positivo de 1 a 3. Utilize 1 para recursos de zona única. Para recursos com várias zonas, o valor tem de ser menor ou igual ao número de zonas suportadas.
offset No número inteiro O desvio da zona lógica inicial. A função devolve um erro se o desvio mais numberOfZones exceder o número de zonas suportadas.

Valor devolvido

Uma matriz com as zonas suportadas. Ao utilizar os valores predefinidos para offset e numberOfZones, um tipo de recurso e uma região que suportam zonas devolvem a seguinte matriz:

[
    "1"
]

Quando o numberOfZones parâmetro está definido como 3, devolve:

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

Quando o tipo de recurso ou região não suporta zonas, é devolvida uma matriz vazia. Também é devolvida uma matriz vazia para serviços com redundância entre zonas.

[
]

Observações

Existem diferentes categorias para o Azure Zonas de Disponibilidade - zonal e com redundância entre zonas. A pickZones função pode ser utilizada para devolver uma zona de disponibilidade para um recurso zonal. Para serviços com redundância entre zonas (ZRS), a função devolve uma matriz vazia. Normalmente, os recursos zonais têm uma zones propriedade no nível superior da definição do recurso. Para determinar a categoria de suporte para zonas de disponibilidade, veja Serviços do Azure que suportam Zonas de Disponibilidade.

Para determinar se uma determinada região ou localização do Azure suporta 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 suporta zonas de disponibilidade.

exemplo de pickZones

O modelo seguinte mostra três resultados para utilizar 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')]"
    }
  }
}

O resultado dos exemplos anteriores devolve três matrizes.

Nome Tipo Valor
Suportado matriz [ "1" ]
notSupportedRegion matriz []
notSupportedType matriz []

Pode utilizar a resposta de pickZones para determinar se deve fornecer um valor nulo para zonas ou atribuir máquinas virtuais a diferentes zonas. O exemplo seguinte define um valor para a zona com base na disponibilidade das 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 pode utilizar a pickZones função para determinar se pretende ativar a redundância entre zonas para georreplicação. Transmita o tipo de recurso Microsoft.Storage/storageAccounts para determinar se pretende ativar a redundância entre zonas.

"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 fornecedores foi preterida nos modelos do ARM. Já não recomendamos que o utilize. Se utilizou esta função para obter uma versão da API para o fornecedor de recursos, recomendamos que forneça uma versão específica da API no seu modelo. A utilização de uma versão de API devolvida dinamicamente pode interromper o modelo se as propriedades forem alteradas entre versões.

No Bicep, a função de fornecedores foi preterida.

A operação de fornecedores ainda está disponível através da API REST. Pode ser utilizado fora de um modelo do ARM para obter informações sobre um fornecedor de recursos.

referência

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

Devolve um objeto que representa o estado de runtime de um recurso.

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

Parâmetros

Parâmetro Necessário Tipo Description
resourceName ou resourceIdentifier Yes string Nome ou identificador exclusivo de um recurso. Ao referenciar um recurso no modelo atual, forneça apenas o nome do recurso como um parâmetro. Quando referenciar um recurso implementado anteriormente ou quando o nome do recurso for ambíguo, indique o ID do recurso.
apiVersion No string Versão da API do recurso especificado. Este parâmetro é necessário quando o recurso não é aprovisionado no mesmo modelo. Normalmente, no formato yyyy-mm-dd. Para obter versões de API válidas para o recurso, veja referência de modelo.
'Completo' No string Valor que especifica se pretende devolver o objeto de recurso completo. Se não especificar 'Full', só é devolvido o objeto de propriedades do recurso. O objeto completo inclui valores como o ID de recurso e a localização.

Valor devolvido

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

Observações

A função de referência obtém o estado do runtime de um recurso implementado anteriormente ou de um recurso implementado no modelo atual. Este artigo mostra exemplos para ambos os cenários.

Normalmente, utiliza a reference função para devolver um valor específico de um objeto, como o URI do ponto final do blob ou o nome de domínio completamente 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]"
  }
}

Utilize 'Full' quando precisar de valores de recursos que não façam 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": "2019-09-01",
  "name": "vaultName",
  "properties": {
    "tenantId": "[subscription().tenantId]",
    "accessPolicies": [
      {
        "tenantId": "[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')), '2019-03-01', 'Full').identity.tenantId]",
        "objectId": "[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')), '2019-03-01', 'Full').identity.principalId]",
        "permissions": {
          "keys": [
            "all"
          ],
          "secrets": [
            "all"
          ]
        }
      }
    ],
    ...

Utilizações válidas

A reference função só pode ser utilizada na secção de saídas de um modelo ou objeto de implementação e propriedades de uma definição de recurso. Não pode ser utilizado para propriedades de recursos, como type, locationnamee outras propriedades de nível superior da definição de recurso. Quando utilizado com a iteração de propriedades, pode utilizar a reference função para input porque a expressão é atribuída à propriedade do recurso.

Não pode utilizar a reference função para definir o valor da count propriedade num ciclo de cópia. Pode utilizar para definir outras propriedades no ciclo. A referência está bloqueada para a propriedade count porque essa propriedade tem de ser determinada antes de a reference função ser resolvida.

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

Se utilizar a reference função num recurso que está implementado condicionalmente, a função é avaliada mesmo que o recurso não esteja implementado. Receberá um erro se a reference função se referir a um recurso que não existe. Utilize a if função para se certificar de que a função só é avaliada quando o recurso está a ser implementado. Veja a função if de um modelo de exemplo que utiliza if e reference com um recurso implementado condicionalmente.

Dependência implícita

Ao utilizar a reference função, declara implicitamente que um recurso depende de outro recurso se o recurso referenciado estiver aprovisionado no mesmo modelo e se fizer referência ao recurso pelo respetivo nome (e não pelo ID do recurso). Também não precisa de utilizar a dependsOn propriedade . A função não é avaliada até que o recurso referenciado tenha concluído a implementação.

Nome ou identificador do recurso

Ao referenciar um recurso implementado no mesmo modelo, indique o nome do recurso.

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

Ao referenciar um recurso que não está implementado no mesmo modelo, forneça o ID do recurso e apiVersion.

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

Para evitar ambiguidades sobre o recurso que está a referenciar, pode fornecer um identificador de recurso completamente qualificado.

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

Ao construir uma referência completamente qualificada a um recurso, a ordem para combinar segmentos do tipo e do nome não é simplesmente uma concatenação dos dois. Em vez disso, depois do espaço de nomes, utilize 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, utilize as resourceId() funções descritas neste documento em vez da concat() função .

Obter identidade gerida

As identidades geridas dos recursos do Azure são tipos de recursos de extensão que são criados implicitamente para alguns recursos. Uma vez que a identidade gerida não está explicitamente definida no modelo, tem de referenciar o recurso ao qual a identidade é aplicada. Utilize 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 o ID principal de uma identidade gerida que é aplicada a uma máquina virtual, utilize:

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

Em alternativa, para obter o ID de inquilino de uma identidade gerida que é aplicada a um conjunto de dimensionamento de máquinas virtuais, utilize:

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

Exemplo de referência

O exemplo seguinte implementa 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"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2021-04-01",
      "name": "[parameters('storageAccountName')]",
      "location": "[resourceGroup().location]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "tags": {},
      "properties": {
      }
    }
  ],
  "outputs": {
    "referenceOutput": {
      "type": "object",
      "value": "[reference(parameters('storageAccountName'))]"
    },
    "fullReferenceOutput": {
      "type": "object",
      "value": "[reference(parameters('storageAccountName'), '2021-04-01', 'Full')]"
    }
  }
}

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

{
   "creationTime": "2017-10-09T18:55:40.5863736Z",
   "primaryEndpoints": {
     "blob": "https://examplestorage.blob.core.windows.net/",
     "file": "https://examplestorage.file.core.windows.net/",
     "queue": "https://examplestorage.queue.core.windows.net/",
     "table": "https://examplestorage.table.core.windows.net/"
   },
   "primaryLocation": "southcentralus",
   "provisioningState": "Succeeded",
   "statusOfPrimary": "available",
   "supportsHttpsTrafficOnly": false
}

O objeto completo está no seguinte formato:

{
  "apiVersion":"2021-04-01",
  "location":"southcentralus",
  "sku": {
    "name":"Standard_LRS",
    "tier":"Standard"
  },
  "tags":{},
  "kind":"Storage",
  "properties": {
    "creationTime":"2017-10-09T18:55:40.5863736Z",
    "primaryEndpoints": {
      "blob":"https://examplestorage.blob.core.windows.net/",
      "file":"https://examplestorage.file.core.windows.net/",
      "queue":"https://examplestorage.queue.core.windows.net/",
      "table":"https://examplestorage.table.core.windows.net/"
    },
    "primaryLocation":"southcentralus",
    "provisioningState":"Succeeded",
    "statusOfPrimary":"available",
    "supportsHttpsTrafficOnly":false
  },
  "subscriptionId":"<subscription-id>",
  "resourceGroupName":"functionexamplegroup",
  "resourceId":"Microsoft.Storage/storageAccounts/examplestorage",
  "referenceApiVersion":"2021-04-01",
  "condition":true,
  "isConditionTrue":true,
  "isTemplateResource":false,
  "isAction":false,
  "provisioningOperation":"Read"
}

O modelo de exemplo seguinte faz referência a uma conta de armazenamento que não está implementada neste modelo. A conta de armazenamento já existe na mesma subscrição.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storageResourceGroup": {
      "type": "string"
    },
    "storageAccountName": {
      "type": "string"
    }
  },
  "resources": [],
  "outputs": {
    "ExistingStorage": {
      "type": "object",
      "value": "[reference(resourceId(parameters('storageResourceGroup'), 'Microsoft.Storage/storageAccounts', parameters('storageAccountName')), '2021-04-01')]"
    }
  }
}

resourceGroup

Veja a função de âmbito resourceGroup.

No Bicep, utilize a função de âmbito resourcegroup .

resourceId

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

Devolve o identificador exclusivo de um recurso. Esta função é utilizada quando o nome do recurso é ambíguo ou não é aprovisionado no mesmo modelo. O formato do identificador devolvido varia consoante a implementação aconteça no âmbito de um grupo de recursos, subscrição, grupo de gestão ou inquilino.

No Bicep, utilize a função resourceId .

Parâmetros

Parâmetro Necessário Tipo Description
subscriptionId No cadeia (no formato GUID) O valor predefinido é a subscrição atual. Especifique este valor quando precisar de obter um recurso noutra subscrição. Forneça apenas este valor ao implementar no âmbito de um grupo de recursos ou subscrição.
resourceGroupName No string O valor predefinido é o grupo de recursos atual. Especifique este valor quando precisar de obter um recurso noutro grupo de recursos. Forneça apenas este valor ao implementar no âmbito de um grupo de recursos.
resourceType Yes string Tipo de recurso, incluindo o espaço de nomes do fornecedor de recursos.
resourceName1 Yes string Nome do recurso.
resourceName2 No string Segmento de nome de recurso seguinte, se necessário.

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

Valor devolvido

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

  • Âmbito do grupo de recursos:

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

  • Âmbito da subscrição:

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

  • Âmbito do grupo de gestão ou inquilino:

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

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

Observações

O número de parâmetros que fornece varia consoante o recurso seja um recurso principal ou subordinado e se o recurso está na mesma subscrição ou grupo de recursos.

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

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

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

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

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

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

Para obter o ID de recurso de um recurso numa subscrição e grupo de recursos diferente, indique o ID da subscrição e o nome do grupo de recursos.

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

Muitas vezes, tem de utilizar esta função ao utilizar uma conta de armazenamento ou uma rede virtual num grupo de recursos alternativo. O exemplo seguinte mostra como um recurso de um grupo de recursos externos pode ser facilmente utilizado:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string"
    },
    "virtualNetworkName": {
      "type": "string"
    },
    "virtualNetworkResourceGroup": {
      "type": "string"
    },
    "subnet1Name": {
      "type": "string"
    },
    "nicName": {
      "type": "string"
    }
  },
  "variables": {
    "subnet1Ref": "[resourceId(parameters('virtualNetworkResourceGroup'), 'Microsoft.Network/virtualNetworks/subnets', parameters('virtualNetworkName'), parameters('subnet1Name'))]"
  },
  "resources": [
    {
      "type": "Microsoft.Network/networkInterfaces",
      "apiVersion": "2021-02-01",
      "name": "[parameters('nicName')]",
      "location": "[parameters('location')]",
      "properties": {
        "ipConfigurations": [
          {
            "name": "ipconfig1",
            "properties": {
              "privateIPAllocationMethod": "Dynamic",
              "subnet": {
                "id": "[variables('subnet1Ref')]"
              }
            }
          }
        ]
      }
    }
  ]
}

Exemplo de ID de Recurso

O exemplo seguinte devolve o ID de recurso de uma conta de armazenamento no grupo de recursos:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "sameRGOutput": {
      "type": "string",
      "value": "[resourceId('Microsoft.Storage/storageAccounts','examplestorage')]"
    },
    "differentRGOutput": {
      "type": "string",
      "value": "[resourceId('otherResourceGroup', 'Microsoft.Storage/storageAccounts','examplestorage')]"
    },
    "differentSubOutput": {
      "type": "string",
      "value": "[resourceId('11111111-1111-1111-1111-111111111111', 'otherResourceGroup', 'Microsoft.Storage/storageAccounts','examplestorage')]"
    },
    "nestedResourceOutput": {
      "type": "string",
      "value": "[resourceId('Microsoft.SQL/servers/databases', 'serverName', 'databaseName')]"
    }
  }
}

O resultado do exemplo anterior com os valores predefinidos é:

Nome Tipo Valor
sameRGOutput String /subscriptions/{current-sub-id}/resourceGroups/examplegroup/providers/Microsoft.Storage/storageAccounts/examplestorage
differentRGOutput String /subscriptions/{current-sub-id}/resourceGroups/otherResourceGroup/providers/Microsoft.Storage/storageAccounts/examplestorage
differentSubOutput String /subscriptions/11111111-1111-1111-1111-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

Veja a função de âmbito da subscrição.

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

subscriptionResourceId

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

Devolve o identificador exclusivo de um recurso implementado ao nível da subscrição.

No Bicep, utilize a função subscriptionResourceId .

Parâmetros

Parâmetro Necessário Tipo Description
subscriptionId No cadeia (no formato GUID) O valor predefinido é a subscrição atual. Especifique este valor quando precisar de obter um recurso noutra subscrição.
resourceType Yes string Tipo de recurso, incluindo o espaço de nomes do fornecedor de recursos.
resourceName1 Yes string Nome do recurso.
resourceName2 No string Segmento de nome de recurso seguinte, se necessário.

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

Valor devolvido

O identificador é devolvido no seguinte formato:

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

Observações

Utilize esta função para obter o ID de recurso dos recursos que são implementados na subscrição em vez de um grupo de recursos. O ID devolvido difere do valor devolvido pela função resourceId ao não incluir um valor de grupo de recursos.

subscriptionResourceID exemplo

O modelo seguinte atribui uma função incorporada. Pode implementá-lo num grupo de recursos ou numa subscrição. Utiliza a subscriptionResourceId função para obter o ID de recurso para funções incorporadas.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "principalId": {
      "type": "string",
      "metadata": {
        "description": "The principal to assign the role to"
      }
    },
    "builtInRoleType": {
      "type": "string",
      "allowedValues": [
        "Owner",
        "Contributor",
        "Reader"
      ],
      "metadata": {
        "description": "Built-in role to assign"
      }
    },
    "roleNameGuid": {
      "type": "string",
      "defaultValue": "[newGuid()]",
      "metadata": {
        "description": "A new GUID used to identify the role assignment"
      }
    }
  },
  "variables": {
    "Owner": "[subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8e3af657-a8ff-443c-a75c-2fe8c4bcb635')]",
    "Contributor": "[subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b24988ac-6180-42a0-ab88-20f7382dd24c')]",
    "Reader": "[subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'acdd72a7-3385-48ef-bd42-f606fba81ae7')]"
  },
  "resources": [
    {
      "type": "Microsoft.Authorization/roleAssignments",
      "apiVersion": "2020-10-01-preview",
      "name": "[parameters('roleNameGuid')]",
      "properties": {
        "roleDefinitionId": "[variables(parameters('builtInRoleType'))]",
        "principalId": "[parameters('principalId')]"
      }
    }
  ]
}

managementGroupResourceId

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

Devolve o identificador exclusivo de um recurso implementado ao nível do grupo de gestão.

No Bicep, utilize a função managementGroupResourceId .

Parâmetros

Parâmetro Necessário Tipo Description
managementGroupResourceId No cadeia (no formato GUID) O valor predefinido é o grupo de gestão atual. Especifique este valor quando precisar de obter um recurso noutro grupo de gestão.
resourceType Yes string Tipo de recurso, incluindo o espaço de nomes do fornecedor de recursos.
resourceName1 Yes string Nome do recurso.
resourceName2 No string Segmento de nome de recurso seguinte, se necessário.

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

Valor devolvido

O identificador é devolvido no seguinte formato:

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

Observações

Utilize esta função para obter o ID de recurso dos recursos que são implementados no grupo de gestão em vez de um grupo de recursos. O ID devolvido difere do valor devolvido pela função resourceId ao não incluir um ID de subscrição e um valor de grupo de recursos.

managementGroupResourceID exemplo

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "targetMG": {
      "type": "string",
      "metadata": {
        "description": "Target Management Group"
      }
    },
    "allowedLocations": {
      "type": "array",
      "defaultValue": [
        "australiaeast",
        "australiasoutheast",
        "australiacentral"
      ],
      "metadata": {
        "description": "An array of the allowed locations, all other locations will be denied by the created policy."
      }
    }
  },
  "functions": [],
  "variables": {
    "mgScope": "[tenantResourceId('Microsoft.Management/managementGroups', parameters('targetMG'))]",
    "policyDefinitionName": "LocationRestriction"
  },
  "resources": [
    {
      "type": "Microsoft.Authorization/policyDefinitions",
      "apiVersion": "2020-03-01",
      "name": "[variables('policyDefinitionName')]",
      "properties": {
        "policyType": "Custom",
        "mode": "All",
        "parameters": {},
        "policyRule": {
          "if": {
            "not": {
              "field": "location",
              "in": "[parameters('allowedLocations')]"
            }
          },
          "then": {
            "effect": "deny"
          }
        }
      }
    },
    {
      "type": "Microsoft.Authorization/policyAssignments",
      "apiVersion": "2020-03-01",
      "name": "location-lock",
      "properties": {
        "scope": "[variables('mgScope')]",
        "policyDefinitionId": "[managementGroupResourceId('Microsoft.Authorization/policyDefinitions', variables('policyDefinitionName'))]"
      },
      "dependsOn": [
        "[format('Microsoft.Authorization/policyDefinitions/{0}', variables('policyDefinitionName'))]"
      ]
    }
  ]
}

tenantResourceId

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

Devolve o identificador exclusivo de um recurso implementado ao nível do inquilino.

No Bicep, utilize a função tenantResourceId .

Parâmetros

Parâmetro Necessário Tipo Description
resourceType Yes string Tipo de recurso, incluindo o espaço de nomes do fornecedor de recursos.
resourceName1 Yes string Nome do recurso.
resourceName2 No string Segmento de nome de recurso seguinte, se necessário.

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

Valor devolvido

O identificador é devolvido no seguinte formato:

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

Observações

Utilize esta função para obter o ID de recurso de um recurso implementado no inquilino. O ID devolvido difere dos valores devolvidos por outras funções de ID de recurso ao não incluir valores de grupo de recursos ou subscrição.

tenantResourceId exemplo

As definições de política incorporadas são recursos ao nível do inquilino. Para implementar uma atribuição de política que faça referência a uma definição de política incorporada, utilize a tenantResourceId função.

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

Passos seguintes