Funções de recurso para modelos do ARM

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

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

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

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

extensionResourceId

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

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

No Bicep, use a extensionResourceId função.

Parâmetros

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

Valor retornado

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

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

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

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

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

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

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

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

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

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

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

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

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

Exemplo de extensionResourceId

O exemplo a seguir retorna a ID 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'))]"
      ]
    }
  ]
}

Definições de política internas são recursos de nível de locatário. Para obter um exemplo de implantação de uma definição de política interna, consulte tenantResourceId.

lista*

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

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

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

Parâmetros

Usos válidos

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

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

Implementações

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

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

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

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

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

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

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

Valor retornado

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

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

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

Comentários

Especifique o recurso usando o nome do recurso ou a resourceId função. Ao usar uma função list 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 se o recurso não for implantado. Você receberá um erro se a função list se referir a um recurso que não existe. Use a função if para garantir que a função seja avaliada apenas quando o recurso estiver sendo implantado. Consulte a if função de um modelo de exemplo que usa if e list com um recurso implantado condicionalmente.

Exemplo de lista

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

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

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

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

pickZones

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

Determina se um tipo de recurso dá suporte a zonas para o local ou região especificado. Essa função só dá suporte a recursos de zona. Os serviços redundantes de zona retornam uma matriz vazia. Para mais informações, confira Serviços do Azure que dão suporte às zonas de disponibilidade.

No Bicep, use a pickZones função.

Parâmetros

Valor retornado

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

[
    "1"
]

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

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

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

[
]

Comentários

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

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

exemplo de pickZones

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

Você pode usar a resposta pickZones para determinar se deseja fornecer nulo 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 deseja habilitar a redundância de zona para a georeplicação. Passe o tipo de recurso Microsoft.Storage/storageAccounts para determinar se deseja habilitar a redundância de zona:

"resources": [
  {
    "type": "Microsoft.DocumentDB/databaseAccounts",
    "apiVersion": "2025-05-01-preview",
    "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')]"
    }
  }
]

Provedores

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

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

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

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

O Bicep fornece a reference função, mas, na maioria dos casos, a função não é necessária. Em vez disso, use o nome simbólico para o recurso. Consulte reference para obter mais informações.

Parâmetros

Valor retornado

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

Comentários

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

Normalmente, você usa a função reference para retornar um valor específico de um objeto, como o URI do ponto de extremidade de blob ou o nome de domínio totalmente qualificado.

"outputs": {
  "BlobUri": {
    "type": "string",
    "value": "[reference(resourceId('Microsoft.Storage/storageAccounts', parameters('storageAccountName'))).primaryEndpoints.blob]"
  },
  "FQDN": {
    "type": "string",
    "value": "[reference(resourceId('Microsoft.Network/publicIPAddresses', parameters('ipAddressName'))).dnsSettings.fqdn]"
  }
}

Use 'Full' quando precisar de valores de recurso que não fizerem parte do esquema de propriedades. Por exemplo, para definir políticas de acesso ao cofre de chaves, obtenha as propriedades de identidade de uma máquina virtual.

{
  "type": "Microsoft.KeyVault/vaults",
  "apiVersion": "2025-05-01",
  "name": "vaultName",
  "properties": {
    "tenantId": "[subscription().tenantId]",
    "accessPolicies": [
      {
        "tenantId": "[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')), '2019-03-01', 'Full').identity.tenantId]",
        "objectId": "[reference(resourceId('Microsoft.Compute/virtualMachines', variables('vmName')), '2019-03-01', 'Full').identity.principalId]",
        "permissions": {
          "keys": [
            "all"
          ],
          "secrets": [
            "all"
          ]
        }
      }
    ],
    ...

Usos válidos

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

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

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

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

Dependência implícita

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

Nome do recurso, nome simbólico ou identificador

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

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

Ao referenciar 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 referenciar um recurso que não é implantado no mesmo modelo, forneça a ID do recurso e apiVersion.

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

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

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

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

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

Por exemplo:

Microsoft.Compute/virtualMachines/myVM/extensions/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 funções resourceId() descritas neste documento, em vez da função concat().

Obter identidade gerenciada

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

O padrão é:

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

Por exemplo, para obter a ID da entidade de segurança para uma identidade gerenciada aplicada a uma máquina virtual, use:

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

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

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

Exemplo de referência

O exemplo a seguir implanta um recurso e faz referência a ele:

{
  "$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": "2025-06-01",
      "name": "[parameters('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "Storage",
      "tags": {},
      "properties": {
      }
    }
  ],
  "outputs": {
    "referenceOutput": {
      "type": "object",
      "value": "[reference(parameters('storageAccountName'))]"
    },
    "fullReferenceOutput": {
      "type": "object",
      "value": "[reference(parameters('storageAccountName'), '2022-09-01', 'Full')]"
    }
  }
}

O exemplo anterior retorna os dois objetos. O objeto de propriedades tem o seguinte formato:

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

O objeto completo tem o seguinte formato:

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

O modelo de exemplo a seguir faz referência a uma conta de armazenamento que não é implantada neste modelo. A conta de armazenamento já existe na mesma assinatura:

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

referências

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

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

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

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

Parâmetros

Valor retornado

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

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

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

Usos válidos

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

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

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

Dependência implícita

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

Exemplo de referência

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "Location for all resources."
      }
    },
    "numWorkers": {
      "type": "int",
      "defaultValue": 4,
      "metadata": {
        "description": "The number of workers"
      }
    }
  },
  "resources": {
    "containerWorkers": {
      "copy": {
        "name": "containerWorkers",
        "count": "[length(range(0, parameters('numWorkers')))]"
      },
      "type": "Microsoft.ContainerInstance/containerGroups",
      "apiVersion": "2025-09-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": "2025-09-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"
      },
      ...
    ]
  }
}

Grupo de recursos

Consulte a resourceGroup scope função.

No Bicep, use a resourceGroup scope função.

ID do recurso

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

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

No Bicep, use a resourceId função.

Parâmetros

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

Valor retornado

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

• Escopo do grupo de recursos:

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

• Escopo da assinatura:

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

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

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

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

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

Comentários

O número de parâmetros fornecidos varia de acordo com se o recurso for um recurso pai ou filho e se o recurso estiver na mesma assinatura ou grupo de recursos.

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

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

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

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

Para obter a ID de recurso de um recurso na mesma assinatura, mas em um grupo de recursos diferente, forneça o nome do grupo de recursos.

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

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

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

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

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

Exemplo de ID de recurso

O exemplo a seguir retorna a ID de recurso de uma conta de armazenamento no grupo de recursos:

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

A saída dos valores padrão do exemplo anterior é:

assinatura

Consulte a função desubscription escopo para obter mais informações.

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

subscriptionResourceId

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

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

No Bicep, use a subscriptionResourceId função.

Parâmetros

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

Valor retornado

O identificador é retornado no seguinte formato:

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

Comentários

Use essa função para obter a ID de recurso dos recursos que são implantados na assinatura, em vez de um grupo de recursos. A ID retornada difere do valor retornado pela resourceId função, pois não retorna 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 em uma assinatura. Ele usa a subscriptionResourceId função para obter a 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 para um recurso implantado no nível do grupo de gerenciamento.

No Bicep, use a managementGroupResourceId função.

Parâmetros

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

Valor retornado

O identificador é retornado no seguinte formato:

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

Comentários

Use essa função para obter a ID de recurso dos recursos que são implantados no grupo de gerenciamento, em vez de um grupo de recursos. A ID retornada difere do valor retornado pela resourceId função, pois não inclui uma ID de assinatura ou 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 função managementGroupResourceId para obter a ID de recurso para definição de política.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "targetMG": {
      "type": "string",
      "metadata": {
        "description": "Target Management Group"
      }
    },
    "allowedLocations": {
      "type": "array",
      "defaultValue": [
        "australiaeast",
        "australiasoutheast",
        "australiacentral"
      ],
      "metadata": {
        "description": "An array of the allowed locations, all other locations will be denied by the created policy."
      }
    }
  },
  "variables": {
    "mgScope": "[tenantResourceId('Microsoft.Management/managementGroups', parameters('targetMG'))]",
    "policyDefinitionName": "LocationRestriction"
  },
  "resources": [
    {
      "type": "Microsoft.Authorization/policyDefinitions",
      "apiVersion": "2025-03-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": "2025-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], ...)

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

No Bicep, use a tenantResourceId função.

Parâmetros

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

Valor retornado

O identificador é retornado no seguinte formato:

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

Comentários

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

Exemplo de tenantResourceId

Definições de política internas são recursos de nível de 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": "2025-03-01",
      "properties": {
        "scope": "[subscriptionResourceId('Microsoft.Resources/resourceGroups', resourceGroup().name)]",
        "policyDefinitionId": "[tenantResourceId('Microsoft.Authorization/policyDefinitions', parameters('policyDefinitionID'))]"
      }
    }
  ]
}

Próximas etapas

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