Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Este artigo descreve as funções bicep para obter valores de recurso.
Para obter valores da implantação atual, consulte Funções de valor de implantação.
extensionResourceId
extensionResourceId(resourceId, 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.
Namespace: az.
A função extensionResourceId está disponível em arquivos Bicep, mas, normalmente, você não precisa dela. Em vez disso, use o nome simbólico para o recurso e acesse a propriedade id.
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 que está sendo estendido.
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 é:
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}
Quando o recurso de extensão é aplicado a uma assinatura, o formato é:
/subscriptions/{subscriptionId}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}
Quando o recurso de extensão é aplicado a um grupo de gerenciamento, o formato é:
/providers/Microsoft.Management/managementGroups/{managementGroupName}/providers/{extensionResourceProviderNamespace}/{extensionResourceType}/{extensionResourceName}
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 arquivo Bicep a seguir em um grupo de gerenciamento.
targetScope = 'managementGroup'
@description('An array of the allowed locations, all other locations will be denied by the created policy.')
param allowedLocations array = [
'australiaeast'
'australiasoutheast'
'australiacentral'
]
resource policyDefinition 'Microsoft.Authorization/policyDefinitions@2025-03-01' = {
name: 'locationRestriction'
properties: {
policyType: 'Custom'
mode: 'All'
parameters: {}
policyRule: {
if: {
not: {
field: 'location'
in: allowedLocations
}
}
then: {
effect: 'deny'
}
}
}
}
resource policyAssignment 'Microsoft.Authorization/policyAssignments@2025-03-01' = {
name: 'locationAssignment'
properties: {
policyDefinitionId: policyDefinition.id
}
}
As definições de políticas internas são recursos em nível de locatário. Para obter um exemplo de implantação de uma definição de política interna, consulte tenantResourceId.
getSecret
keyVaultName.getSecret(secretName)
Retorna um segredo do Azure Key Vault. Use esta função para passar um segredo para um parâmetro de cadeia de caracteres seguro de um módulo Bicep.
Observação
A função az.getSecret(subscriptionId, resourceGroupName, keyVaultName, secretName, secretVersion) pode ser usada em arquivos .bicepparam para recuperar segredos do cofre de chaves. Para obter mais informações, consulte getSecret.
Você só pode usar a função getSecret de dentro da seção params de um módulo. Você só pode usá-la com um recurso Microsoft.KeyVault/vaults.
module sql './sql.bicep' = {
name: 'deploySQL'
params: {
adminPassword: keyVault.getSecret('vmAdminPassword')
}
}
Quando você tenta usar essa função em qualquer outra parte do arquivo Bicep, um erro é exibido. Um erro também é exibido, quando você usa essa função com interpolação de cadeia de caracteres, mesmo na seção params.
A função pode ser usada apenas com um parâmetro de módulo que possui o decorador @secure().
O cofre de chaves deve ter enabledForTemplateDeployment definido como true. O usuário implantando o arquivo Bicep deve ter acesso ao segredo. Para obter mais informações, confira Usar o Azure Key Vault para transmitir um valor de parâmetro seguro durante a implantação do Bicep.
Um qualificador de namespace não é necessário porque a função é usada com um tipo de recurso.
Parâmetros
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| nome_secreto | Sim | corda | O nome do segredo armazenado em um cofre de chaves. |
Valor retornado
O valor do segredo para o nome do segredo.
Exemplo
O arquivo Bicep a seguir é usado como um módulo. Ele tem um parâmetro adminPassword definido com o decorador @secure().
param sqlServerName string
param adminLogin string
@secure()
param adminPassword string
resource sqlServer 'Microsoft.Sql/servers@2024-11-01-preview' = {
...
}
O arquivo Bicep a seguir consome o arquivo Bicep anterior como um módulo. O arquivo Bicep faz referência a um cofre de chaves existente e chama a função getSecret para recuperar o segredo do cofre de chaves e, em seguida, passa o valor como um parâmetro para o módulo.
param sqlServerName string
param adminLogin string
param subscriptionId string
param kvResourceGroup string
param kvName string
resource keyVault 'Microsoft.KeyVault/vaults@2025-05-01' existing = {
name: kvName
scope: resourceGroup(subscriptionId, kvResourceGroup )
}
module sql './sql.bicep' = {
name: 'deploySQL'
params: {
sqlServerName: sqlServerName
adminLogin: adminLogin
adminPassword: keyVault.getSecret('vmAdminPassword')
}
}
lista*
resourceName.list([apiVersion], [functionValues])
Você pode chamar uma função de lista para qualquer tipo de recurso com uma operação que comece com list. Alguns usos comuns são list, listKeys, listKeyValue e listSecrets.
A sintaxe dessa função varia de acordo com o nome da operação de lista. Os valores retornados também variam de acordo com a operação. Atualmente, o bícep não oferece suporte para conclusões e validação para funções list*.
Com a CLI do Bicep versão 0.4.X ou superior, você chama a função da lista usando o operador acessador. Por exemplo, storageAccount.listKeys().
Um qualificador de namespace não é necessário porque a função é usada com um tipo de recurso.
Parâmetros
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| apiVersion | Não | corda | Se você não fornecer esse parâmetro, a versão da API para o recurso será usada. Forneça apenas uma versão de API personalizada quando precisar que a função seja executada com uma versão específica. Use o formato aaaa-mm-dd. |
| functionValues | Não | objeto | Um objeto que tem valores para a função. Fornecer apenas este objeto para funções que dão suporte ao recebimento de um objeto com valores de parâmetro, como listAccountSas em uma conta de armazenamento. Um exemplo de passar valores de função é mostrado neste artigo. |
Usos válidos
As funções list podem ser usadas nas propriedades de uma definição de recurso. Não use uma função list que exponha informações confidenciais na seção de saídas de um arquivo Bicep. 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 umloop iterativo, você pode usar as funções list 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.
Se você usar a função list em um recurso implantado condicionalmente, a função será avaliada mesmo que o recurso não seja implantado. Você receberá um erro se a função list se referir a um recurso que não existe. Use o operador expressão condicional ?: para garantir que a função só seja avaliada quando o recurso estiver sendo implantado.
Valor retornado
O objeto retornado varia de acordo com a função de lista 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 o exemplo de arquivo Bicep.
Exemplo de lista
O seguinte exemplo implanta uma conta de armazenamento e chama listKeys nessa conta de armazenamento. A chave é usada ao definir um valor para scripts de implantação.
resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' = {
name: 'dscript${uniqueString(resourceGroup().id)}'
location: location
kind: 'StorageV2'
sku: {
name: 'Standard_LRS'
}
}
resource dScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
name: 'scriptWithStorage'
location: location
...
properties: {
azCliVersion: '2.0.80'
storageAccountSettings: {
storageAccountName: storageAccount.name
storageAccountKey: storageAccount.listKeys().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.
param accountSasProperties object {
default: {
signedServices: 'b'
signedPermission: 'r'
signedExpiry: '2020-08-20T11:00:00Z'
signedResourceTypes: 's'
}
}
...
sasToken: storageAccount.listAccountSas('2021-04-01', accountSasProperties).accountSasToken
Implementações
Os possíveis usos de list* são mostrados na tabela a seguir.
| 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/workspaces/experiments/jobs | listoutputfiles |
| Microsoft.BotService/botServices/channels | listChannelWithKeys |
| Microsoft.Cache/redis | listKeys |
| Microsoft.CognitiveServices/accounts | listKeys |
| 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/factories/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/serviços de provisionamento | listkeys |
| Microsoft.DevTestLab/labs | ListVhds |
| Microsoft.DevTestLab/labs/schedules | ListApplicable |
| Microsoft.DevTestLab/labs/users/serviceFabrics | ListApplicableSchedules |
| Microsoft.DevTestLab/labs/virtualMachines | ListApplicableSchedules |
| Microsoft.DocumentDB/databaseAccounts | listKeys |
| Microsoft.DocumentDB/databaseAccounts/notebookWorkspaces | listConnectionInfo |
| Microsoft.RegistrodeDomínio | listDomainRecommendations |
| 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/Databases | ListPrincipals |
| Microsoft.LabServices/labs/users | lista |
| Microsoft.LabServices/labs/virtualMachines | lista |
| 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/repetições | 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 | lista |
| Microsoft.OperationalInsights/workspaces | listKeys |
| Microsoft.PolicyInsights/remediações | listDeployments |
| Microsoft.RedHatOpenShift/openShiftClusters | listCredentials |
| Microsoft.Relay/namespaces/disasterRecoveryConfigs/authorizationRules | listkeys |
| Microsoft.Search/searchServices | listAdminKeys |
| Microsoft.Search/searchServices | listQueryKeys |
| 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/backups | lista |
| Microsoft.Web/sites/config | lista |
| microsoft.web/sites/functions | listkeys |
| microsoft.web/sites/functions | listsecrets |
| microsoft.web/sites/hybridconnectionnamespaces/relays | listkeys |
| microsoft.web/sites | listsyncfunctiontriggerstatus |
| microsoft.web/sites/slots/functions | listsecrets |
| microsoft.web/sites/slots/backups | lista |
| Microsoft.Web/sites/slots/config | lista |
| microsoft.web/sites/slots/functions | listsecrets |
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 OperationUse 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')]"
managementGroupResourceId
managementGroupResourceId(resourceType, resourceName1, [resourceName2], ...)
Retorna o identificador exclusivo de um recurso implantado no nível do grupo de gerenciamento.
Namespace: az.
A função managementGroupResourceId está disponível em arquivos Bicep, mas, normalmente, você não precisa dela. Em vez disso, use o nome simbólico para o recurso e acesse a propriedade id.
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 é diferente do valor retornado pela função resourceId, pois não inclui uma ID da assinatura e um valor de grupo de recursos.
exemplo de managementGroupResourceID
O modelo a seguir cria e atribui uma definição de política. Ele usa a função managementGroupResourceId para obter a ID de recurso para definição de política.
targetScope = 'managementGroup'
@description('Target Management Group')
param targetMG string
@description('An array of the allowed locations, all other locations will be denied by the created policy.')
param allowedLocations array = [
'australiaeast'
'australiasoutheast'
'australiacentral'
]
var mgScope = tenantResourceId('Microsoft.Management/managementGroups', targetMG)
var policyDefinitionName = 'LocationRestriction'
resource policyDefinition 'Microsoft.Authorization/policyDefinitions@2025-03-01' = {
name: policyDefinitionName
properties: {
policyType: 'Custom'
mode: 'All'
parameters: {}
policyRule: {
if: {
not: {
field: 'location'
in: allowedLocations
}
}
then: {
effect: 'deny'
}
}
}
}
resource location_lock 'Microsoft.Authorization/policyAssignments@2025-03-01' = {
name: 'location-lock'
properties: {
scope: mgScope
policyDefinitionId: managementGroupResourceId('Microsoft.Authorization/policyDefinitions', policyDefinitionName)
}
dependsOn: [
policyDefinition
]
}
pickZones
pickZones(providerNamespace, resourceType, location, [numberOfZones], [offset])
Determina se um tipo de recurso dá suporte a zonas para uma região. 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.
Namespace: az.
Parâmetros
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| providerNamespace | Sim | corda | O namespace do provedor de recursos para o tipo de recurso para verificar se há suporte para zona. |
| tipoDeRecurso | Sim | corda | O tipo de recurso a ser verificar se há suporte para zona. |
| local | Sim | corda | A região a ser verificada quanto ao suporte à zona. |
| numberOfZones | Não | inteiro | O número de zonas lógicas para retornar. O padrão é 1. O número deve ser um número inteiro positivo de 1 a 3. Use 1 para recursos de zona única. Para recursos de várias zonas, o valor deve ser menor ou igual ao número de zonas com suporte. |
| deslocamento | Não | inteiro | O deslocamento da zona lógica inicial. A função retornará um erro se offset mais numberOfZones exceder o número de zonas com suporte. |
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.
[
]
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 arquivo Bicep a seguir mostra três resultados para usar a função pickZones.
output supported array = pickZones('Microsoft.Compute', 'virtualMachines', 'westus2')
output notSupportedRegion array = pickZones('Microsoft.Compute', 'virtualMachines', 'westus')
output notSupportedType array = pickZones('Microsoft.Cdn', 'profiles', 'westus2')
A saída dos exemplos anteriores retorna três matrizes.
| Nome | Tipo | Valor |
|---|---|---|
| com suporte | conjunto | [ "1" ] |
| notSupportedRegion | conjunto | [] |
| notSupportedType | conjunto | [] |
Você pode usar a resposta de pickZones para determinar se deve fornecer null para zonas ou atribuir máquinas virtuais a diferentes zonas.
Provedores
A função providers foi preterida no Bicep. 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 forneça uma versão de API específica em seu arquivo Bicep. O uso de uma versão de API retornada dinamicamente pode quebrar seu modelo se as propriedades mudam entre as versões.
A operação providers ainda está disponível por meio da API REST. Ela pode ser usada fora de um arquivo Bicep para obter informações sobre um provedor de recursos.
Namespace: az.
referência
reference(resourceName 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.
Namespace: az.
Os arquivos do Bicep fornecem acesso à função de referência, ainda que normalmente ela seja desnecessária. Em vez disso, é recomendável usar o nome simbólico do recurso. A função de referência só pode ser utilizada dentro do objeto properties de um recurso e não pode ser empregada para propriedades de nível superior, como name ou location. O mesmo se aplica, em geral, às referências que usam o nome simbólico. Entretanto, para propriedades como name, é possível gerar um modelo sem utilizar a função de referência. Informações suficientes sobre o nome do recurso são conhecidas pela emissão direta do nome. Isso é conhecido como propriedades de tempo de compilação. A validação do Bicep pode identificar qualquer utilização incorreta do nome simbólico.
O exemplo a seguir implanta uma conta de armazenamento. As duas primeiras saídas fornecem os mesmos resultados.
param storageAccountName string = uniqueString(resourceGroup().id)
param location string = resourceGroup().location
resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' = {
name: storageAccountName
location: location
kind: 'Storage'
sku: {
name: 'Standard_LRS'
}
}
output storageObjectSymbolic object = storageAccount.properties
output storageObjectReference object = reference('storageAccount')
output storageName string = storageAccount.name
output storageLocation string = storageAccount.location
Para obter uma propriedade de um recurso existente que não está implantado no modelo, use a palavra-chave existing:
param storageAccountName string
resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' existing = {
name: storageAccountName
}
// use later in template as often as needed
output blobAddress string = storageAccount.properties.primaryEndpoints.blob
Para fazer referência a um recurso que está aninhado dentro de um recurso pai, use o acessador aninhado ( :: ). Você só usa essa sintaxe quando está acessando o recurso aninhado de fora do recurso pai.
vNet1::subnet1.properties.addressPrefix
Se você tentar referenciar um recurso que não existe, você obterá o erro NotFound e a implantação falhará.
ID do recurso
resourceId([subscriptionId], [resourceGroupName], resourceType, resourceName1, [resourceName2], ...)
Retorna o identificador exclusivo de um recurso.
Namespace: az.
A função resourceId está disponível em arquivos Bicep, mas, normalmente, você não precisa dela. Em vez disso, use o nome simbólico para o recurso e acesse a propriedade id.
Você pode usar essa função quando o nome do recurso é ambíguo ou não provisionado no mesmo arquivo Bicep. O formato do identificador retornado varia dependendo de se a implantação ocorre no escopo de um grupo de recursos, de assinatura, de um grupo de gerenciamento ou do locatário.
Por exemplo:
param storageAccountName string
param location string = resourceGroup().location
resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' = {
name: storageAccountName
location: location
kind: 'Storage'
sku: {
name: 'Standard_LRS'
}
}
output storageID string = storageAccount.id
Para obter a ID de recurso de um recurso que não está implantado no arquivo Bicep, use a palavra-chave existente.
param storageAccountName string
resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' existing = {
name: storageAccountName
}
output storageID string = storageAccount.id
Para obter mais informações, consulte a Função resourceId do modelo JSON.
subscriptionResourceId
subscriptionResourceId([subscriptionId], resourceType, resourceName1, [resourceName2], ...)
Retorna o identificador exclusivo de um recurso implantado no nível da assinatura.
Namespace: az.
A função subscriptionResourceId está disponível em arquivos Bicep, mas, normalmente, você não precisa dela. Em vez disso, use o nome simbólico para o recurso e acesse a propriedade id.
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 função resourceId ao não incluir um valor de grupo de recursos.
Exemplo de subscriptionResourceID
O arquivo Bicep a seguir atribui uma função interna. Você pode implantá-lo em um grupo de recursos ou assinatura. Ele usa a função subscriptionResourceId para obter a ID de recurso para funções internas.
@description('Principal Id')
param principalId string
@allowed([
'Owner'
'Contributor'
'Reader'
])
@description('Built-in role to assign')
param builtInRoleType string
var roleDefinitionId = {
Owner: {
id: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8e3af657-a8ff-443c-a75c-2fe8c4bcb635')
}
Contributor: {
id: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'b24988ac-6180-42a0-ab88-20f7382dd24c')
}
Reader: {
id: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', 'acdd72a7-3385-48ef-bd42-f606fba81ae7')
}
}
resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
name: guid(resourceGroup().id, principalId, roleDefinitionId[builtInRoleType].id)
properties: {
roleDefinitionId: roleDefinitionId[builtInRoleType].id
principalId: principalId
}
}
tenantResourceId
tenantResourceId(resourceType, resourceName1, [resourceName2], ...)
Retorna o identificador exclusivo de um recurso implantado no nível do locatário.
Namespace: az.
A função tenantResourceId está disponível em arquivos Bicep, mas, normalmente, você não precisa dela. Em vez disso, use o nome simbólico para o recurso e acesse a propriedade id.
O identificador é retornado no seguinte formato:
/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
As definições de políticas internas são recursos em nível de locatário. Para implantar uma atribuição de política que faz referência a uma definição de política interna, use a função tenantResourceId.
@description('Specifies the ID of the policy definition or policy set definition being assigned.')
param policyDefinitionID string = '0a914e76-4921-4c19-b460-a2d36003525a'
@description('Specifies the name of the policy assignment, can be used defined or an idempotent name as the defaultValue provides.')
param policyAssignmentName string = guid(policyDefinitionID, resourceGroup().name)
resource policyAssignment 'Microsoft.Authorization/policyAssignments@2025-03-01' = {
name: policyAssignmentName
properties: {
scope: subscriptionResourceId('Microsoft.Resources/resourceGroups', resourceGroup().name)
policyDefinitionId: tenantResourceId('Microsoft.Authorization/policyDefinitions', policyDefinitionID)
}
}
toLogicalZone
toLogicalZone(subscriptionId, location, physicalZone)
Retorna a zona de disponibilidade lógica (por exemplo, 1, 2ou 3) correspondente a uma zona de disponibilidade física para uma assinatura especificada em uma determinada região do Azure.
Namespace: az
Parâmetros
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| ID de assinatura | Sim | corda | A ID da assinatura do Azure (por exemplo, 12345678-1234-1234-1234-1234567890ab). |
| local | Sim | corda | A região do Azure que dá suporte a zonas de disponibilidade (por exemplo, westus2). |
| physicalZone | Sim | corda | O identificador de zona de disponibilidade física (por exemplo, um identificador específico do data center como westus2-az1). |
Valor retornado
Uma cadeia de caracteres que representa a zona de disponibilidade lógica (por exemplo, 1, 2ou 3) que corresponde à zona física especificada na região e assinatura fornecidas. Se a zona física for inválida ou não tiver suporte, uma cadeia de caracteres vazia ('') será retornada.
Comentários
- A
toLogicalZonefunção recupera o mapeamento de zona lógica com base na configuração de zona da assinatura na região especificada. - As zonas lógicas são identificadores padronizados (por exemplo,
1, ,2)3usados em configurações de recursos para garantir atribuições de zona consistentes nos serviços do Azure. - Os identificadores de zona física são específicos da região e podem variar entre assinaturas. Use a
toPhysicalZonefunção para reverter esse mapeamento. - A função requer que a região dê suporte a zonas de disponibilidade. Para obter uma lista de regiões com suporte, consulte os serviços do Azure que dão suporte a zonas de disponibilidade.
- Se a zona física não existir ou não for mapeada para a assinatura, a função retornará uma cadeia de caracteres vazia.
- Essa função é útil para alinhar implantações de zona física com configurações de zona lógica em modelos, especialmente para cenários entre assinaturas ou várias regiões.
Exemplos
O exemplo a seguir recupera a zona lógica de uma zona física no Oeste dos EUA 2 para uma assinatura específica:
param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param physicalZone string = 'westus2-az1'
output logicalZone string = toLogicalZone(subscriptionId, 'westus2', physicalZone)
Resultado esperado:
| Nome | Tipo | Valor |
|---|---|---|
| logicalZone | fio | 1 |
O exemplo a seguir usa toLogicalZone para configurar uma máquina virtual com a zona lógica correta:
param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param physicalZone string = 'westus2-az1'
param location string = 'westus2'
var logicalZone = toLogicalZone(subscriptionId, location, physicalZone)
resource vm 'Microsoft.Compute/virtualMachines@2025-04-01' = {
name: 'myVM'
location: location
zones: logicalZone != '' ? [logicalZone] : []
properties: {
// VM properties
}
}
output logicalZone string = logicalZone
Resultado esperado:
| Nome | Tipo | Valor |
|---|---|---|
| logicalZone | fio | 1 |
toLogicalZones
toLogicalZones(subscriptionId, location, physicalZones)
Retorna as zonas de disponibilidade lógica (por exemplo, 1, 2ou 3) correspondentes a zonas de disponibilidade física para uma assinatura especificada em uma determinada região do Azure. Para converter uma única zona física, use a toLogicalZone função.
Namespace: az
Parâmetros
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| ID de assinatura | Sim | corda | A ID da assinatura do Azure (por exemplo, 12345678-1234-1234-1234-1234567890ab). |
| local | Sim | corda | A região do Azure que dá suporte a zonas de disponibilidade (por exemplo, westus2). |
| physicalZones | Sim | conjunto | Uma matriz de nomes de zona física para converter em zonas lógicas (por exemplo, um identificador específico do data center, como westus2-az1... westus2-az2). |
Valor retornado
Uma matriz de nomes de zona lógica correspondentes às zonas físicas fornecidas (por exemplo, 1, 2ou 3). Se uma zona física for inválida ou não tiver suporte, uma cadeia de caracteres vazia ('') será retornada.
Comentários
A toLogicalZones função mapeia nomes de zona física para seus equivalentes de zona lógica para uma assinatura e região do Azure especificadas. Isso é útil para configurar ou consultar recursos com base em zonas lógicas em uma região do Azure. A função requer uma ID de assinatura válida, um local do Azure com suporte e uma matriz de nomes de zona física. Se uma zona física for inválida ou não estiver disponível no local especificado, a função poderá retornar uma cadeia de caracteres vazia para essa zona ou gerar um erro, dependendo do contexto.
Exemplos
O exemplo a seguir recupera as zonas lógicas para uma lista de zonas físicas no Oeste dos EUA 2 para uma assinatura específica:
param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param physicalZones array = ['westus2-az1', 'westus2-az2', 'westus2-az3']
output logicalZones array = toLogicalZones(subscriptionId, 'westus2', physicalZones)
Resultado esperado:
| Nome | Tipo | Valor |
|---|---|---|
| logicalZone | conjunto | ["1","2","3"] |
toPhysicalZone
toPhysicalZone(subscriptionId, location, logicalZone)
Retorna o identificador de zona de disponibilidade física (por exemplo, um identificador específico do data center como westus2-az1) correspondente a uma zona de disponibilidade lógica para uma assinatura especificada em uma determinada região do Azure.
Namespace: az
Parâmetros
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| ID de assinatura | Sim | corda | A ID da assinatura do Azure (por exemplo, 12345678-1234-1234-1234-1234567890ab). |
| local | Sim | corda | A região do Azure que dá suporte a zonas de disponibilidade (por exemplo, westus2). |
| logicalZone | Sim | corda | A zona de disponibilidade lógica (por exemplo, 1, 2ou 3). |
Valor retornado
Uma cadeia de caracteres que representa o identificador de zona de disponibilidade física (por exemplo, westus2-az1) que corresponde à zona lógica especificada na região e assinatura fornecidas. Se a zona lógica for inválida ou não tiver suporte, uma cadeia de caracteres vazia ('') será retornada.
Comentários
- A
toPhysicalZonefunção recupera o mapeamento de zona física com base na configuração de zona da assinatura na região especificada. - Zonas físicas são identificadores específicos do data center que podem variar entre assinaturas, enquanto zonas lógicas (por exemplo,
1, ,2,3) são padronizadas para configurações de recursos. - Use a
toLogicalZonefunção para reverter esse mapeamento, convertendo uma zona física em seu equivalente lógico. - A função requer que a região dê suporte a zonas de disponibilidade. Para obter uma lista de regiões com suporte, consulte os serviços do Azure que dão suporte a zonas de disponibilidade.
- Se a zona lógica não existir ou não for mapeada para a assinatura, a função retornará uma cadeia de caracteres vazia.
- Essa função é útil para cenários que exigem identificadores de zona física, como registro em log, auditoria ou alinhamento de zona entre assinaturas em implantações de várias regiões.
Exemplos
O exemplo a seguir recupera a zona física de uma zona lógica no Oeste dos EUA 2 para uma assinatura específica:
param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param logicalZone string = '1'
output physicalZone string = toPhysicalZone(subscriptionId, 'westus2', logicalZone)
Saída esperada (supondo que a zona 1 lógica mapeia para westus2-az1):
| Nome | Tipo | Valor |
|---|---|---|
| physicalZone | fio | westus2-az1 |
O exemplo a seguir usa toPhysicalZone para registrar em log a zona física para uma implantação de máquina virtual:
param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param logicalZone string = '1'
param location string = 'westus2'
var physicalZone = toPhysicalZone(subscriptionId, location, logicalZone)
resource vm 'Microsoft.Compute/virtualMachines@2025-04-01' = {
name: 'myVM'
location: location
zones: [logicalZone]
properties: {
// VM properties
}
}
output physicalZone string = physicalZone
Resultado esperado:
| Nome | Tipo | Valor |
|---|---|---|
| physicalZone | fio | westus2-az1 |
toPhysicalZones
toPhysicalZones(subscriptionId, location, logicalZones)
Retorna os identificadores de zona de disponibilidade física (por exemplo, um identificador específico do data center como westus2-az1) correspondentes a zonas de disponibilidade lógica para uma assinatura especificada em uma determinada região do Azure. Para converter uma única zona lógica, use a toPhysicalZone função.
Namespace: az
Parâmetros
| Parâmetro | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| ID de assinatura | Sim | corda | A ID da assinatura do Azure (por exemplo, 12345678-1234-1234-1234-1234567890ab). |
| local | Sim | corda | A região do Azure que dá suporte a zonas de disponibilidade (por exemplo, westus2). |
| logicalZone | Sim | cadeia de caracteres[] | As zonas de disponibilidade lógica (por exemplo, 1, 2ou 3) a serem convertidas em zonas físicas. |
Valor retornado
Uma matriz de nomes de zona física (por exemplo, westus2-az1, westus2-az2 ) correspondente às zonas lógicas fornecidas. Se uma zona lógica for inválida ou não tiver suporte, uma cadeia de caracteres vazia ('') será retornada.
Comentários
A toPhysicalZones função mapeia nomes de zona lógica para seus equivalentes de zona física para uma assinatura e região do Azure especificadas. Isso é útil para implantar ou configurar recursos em zonas físicas específicas em uma região do Azure. A função requer uma ID de assinatura válida, um local do Azure com suporte e uma matriz de nomes de zona lógica. Se uma zona lógica for inválida ou não estiver disponível no local especificado, a função poderá retornar uma cadeia de caracteres vazia para essa zona ou gerar um erro, dependendo do contexto.
Exemplos
O exemplo a seguir recupera as zonas físicas para uma lista de zonas lógicas no Oeste dos EUA 2 para uma assinatura específica:
param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param logicalZones array = ['1', '2', '3']
output physicalZones array = toPhysicalZones(subscriptionId, 'westus2', logicalZones)
Saída esperada (supondo que a zona 1 lógica mapeia para westus2-az1, a zona 1 lógica é mapeada westus2-az1e a zona 3 lógica é mapeada para westus2-az3):
| Nome | Tipo | Valor |
|---|---|---|
| physicalZone | conjunto | ["westus2-az1","westus2-az2","westus2-az3"] |
Próximas etapas
- Para obter valores da implantação atual, consulte Funções de valor de implantação.
- Para iterar um número especificado de vezes ao criar um tipo de recurso, confira Loops iterativos no Bicep.