Funções de recurso para Bicep

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.

O this namespace

O this namespace fornece funções para a descoberta do estado do recurso em tempo de execução dentro de uma definição de recurso. Essas funções permitem que seu template adapte sua configuração com base em que um recurso já existe no ambiente.

• this.exists(): Retorna um valor bool indicando se o recurso já existe.
• this.existingResource(): Retorna a representação do objeto do recurso se ele existir, ou nulo se não existir.

existe

this.exists()

Retorna um valor bool indicando se o recurso já existe no Azure. Essa função é avaliada durante a implantação e é destinada a ser usada em atribuições de propriedades de recursos para lidar com lógica condicional sem exigir declarações de recursos separadas existentes.

Namespace: this

Exemplo

resource stg 'Microsoft.Storage/storageAccounts@2026-04-01' = {
  name: 'mystorageaccount'
  location: 'eastus'
  sku: {
    name: 'Standard_LRS'
  }
  kind:  'StorageV2'
  properties:{
    accessTier: this.exists() ? this.existingResource()!.properties.accessTier : 'Cold'
  }
}

existingResource

this.existingResource()

Retorna a representação do objeto do recurso, se ele existir ou null não. Essa função se combina com this.exists(). While exists() retorna um booleano simples, existingResource() retorna o objeto de recurso real. Você pode acessar propriedades aninhadas com segurança usando o operador nulo que perdoa (!) ou o operador de navegação segura (.?).

Namespace: this

Exemplo

resource stg 'Microsoft.Storage/storageAccounts@2026-04-01' = {
  name: 'mystorageaccount'
  location: 'eastus'
  sku: {
    name: 'Standard_LRS'  }
  kind:  'StorageV2'
  properties:{
    accessTier: this.existingResource().?properties.accessTier ?? 'Cold'
  }
}

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 você aplica a outro recurso para aumentar suas capacidades.

Namespace: az.

O primeiro argumento deve ser o ID de recurso totalmente qualificado do recurso ao qual o recurso de extensão se aplica. Esse requisito é especialmente importante quando você implanta um recurso em nível de locatário a partir de um escopo menor, como uma assinatura ou grupo de recursos. Um valor que se resolve no escopo do tenant pode falhar quando a implantação começa em um escopo inferior.

Você pode usar a extensionResourceId função nos arquivos do Bicep, mas normalmente não precisa dela. Em vez disso, use o nome simbólico para o recurso e acesse a propriedade id. A id propriedade retorna o ID de recurso totalmente qualificado.

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 você aplica o recurso de extensão a um recurso, o ID do recurso é retornado no seguinte formato:

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

Quando você aplica o recurso de extensão a um grupo de recursos, o formato é:

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

Quando você aplica o recurso de extensão a uma assinatura, o formato é:

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

Quando você aplica o recurso de extensão a um grupo de gestão, 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 de 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 de um Azure Key Vault. Use essa função para passar um segredo para um parâmetro de cadeia de caracteres seguro de um módulo de Bicep.

Você só pode usar a função getSecret de dentro da seção params de um módulo. Você só pode usá-lo com um recurso Microsoft.KeyVault/vaults.

module sql './sql.bicep' = {
  name: 'deploySQL'
  params: {
    adminPassword: keyVault.getSecret('vmAdminPassword')
  }
}

Você receberá um erro se tentar usar essa função em qualquer outra parte do arquivo Bicep. Um erro também é exibido, quando você usa essa função com interpolação de cadeia de caracteres, mesmo na seção params.

Use a função apenas com um parâmetro de módulo que tenha o @secure() decorador.

O cofre de chaves deve ter enabledForTemplateDeployment definido como true. O usuário que está implantando o arquivo Bicep deve ter acesso ao segredo. Para obter mais informações, consulte Use Azure Key Vault para passar o valor do parâmetro seguro durante Bicep implantação.

Um qualificador de namespace não é necessário porque a função é usada com um tipo de recurso.

Parâmetros

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. Bicep atualmente não dá suporte a conclusões e validação para funções de list*.

Com Bicep CLI versão 0.4.X ou superior, você chama a função de lista usando o operador accessor. Por exemplo, storageAccount.listKeys().

Um qualificador de namespace não é necessário porque a função é usada com um tipo de recurso.

Parâmetros

Usos válidos

Use as list funções nas propriedades de uma definição de recurso. Não use uma list função que exponha informações sensíveis na outputs seção de um arquivo Bicep. Os valores de saída são armazenados no histórico de implantação e um usuário malicioso pode recuperá-los.

Quando você usa uma list função com um loop iterativo, pode usá-la porque input a expressão é atribuída à propriedade de recurso. Você não pode usá-lo com count porque a contagem precisa ser determinada antes que a list função 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.

A use-recognized-resource-type regra linter sinaliza qualquer recurso referenciado que use um tipo de recurso não reconhecido ou inválido.

Valor retornado

O objeto retornado varia de acordo com a função list que você usa. Por exemplo, a listKeys função 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 outputs seção mostrada no arquivo Bicep de exemplo.

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

A tabela a seguir mostra possíveis usos das list* funções.

Para determinar quais tipos de recursos possuem 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 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 managementGroupResourceId função está disponível nos 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 o ID de recurso para 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 obter mais informações, consulte Azure serviços que dão suporte a zonas de disponibilidade.

Namespace: az.

Parâmetros

Valor retornado

Uma matriz com as zonas com suporte. Quando você usa os valores padrão para offset e numberOfZones, um tipo de recurso e região que suporta zonas retorna o seguinte array:

[
  "1"
]

Quando você define o numberOfZones parâmetro para 3, ele retorna:

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

Quando o tipo de recurso ou região não suporta zonas, a função retorna um array vazio.

[
]

Comentários

Azure Zonas de Disponibilidade se dividem em duas categorias - zonal e redundante por zona. Use a pickZones função para retornar uma zona de disponibilidade para um recurso zonal. 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 Azure serviços que dão suporte a zonas de disponibilidade.

Para determinar se uma determinada região Azure ou local dá suporte a zonas de disponibilidade, chame a função pickZones com um tipo de recurso zonal, como 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 de 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.

Use a resposta de pickZones para decidir se fornece null para as zonas ou se atribui máquinas virtuais a diferentes zonas.

Provedores

A função do provedor está obsoleta no Bicep. Não a utilize. Se você usou essa função para obter uma versão da API para o provedor de recursos, forneça uma versão específica da API no 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. Você pode usá-lo fora do 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 reference função dependem fortemente de como cada provedor de recursos (RP) implementa suas respostas PUT e GET.

Namespace: az.

Arquivos Bicep fornecem acesso à função de referência, embora normalmente você não precise dela. Em vez disso, use o nome simbólico do recurso. Você só pode usar a função de referência dentro do properties objeto de um recurso. Você não pode usá-lo para propriedades de nível superior como name ou location. A mesma regra geralmente se aplica a referências que usam o nome simbólico. No entanto, para propriedades como name, você pode gerar um template sem usar a função de referência. Você sabe o suficiente sobre o nome do recurso para emitir o nome diretamente. Essas são propriedades em tempo de compilação. Bicep validação pode identificar qualquer uso incorreto 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 você não implantou no modelo, use a existing palavra-chave:

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 referenciar um recurso que está aninhado dentro de um recurso pai, use o acessor 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á. A use-recognized-resource-type regra linter sinaliza qualquer recurso referenciado que use um tipo de recurso não reconhecido ou inválido.

ID do recurso

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

Retorna o identificador exclusivo de um recurso.

Namespace: az.

A resourceId função está disponível nos 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.

Use essa função quando o nome do recurso for ambíguo ou não for provisionado dentro do 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 do recurso de um recurso que não é 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.

roleDefinitions

roleDefinitions(roleName)

Retorna informações sobre a definição de função especificada, incluindo id e roleDefinitionId. É um auxiliar baseado em nome para Azure atribuições de função RBAC. Em vez de exigir que você codifique o GUID de uma definição personalizada ou de função embutida (como Contribuidor, Leitor e outros), ele permite que você forneça o nome de exibição do papel personalizado ou embutido, e a função resolve as informações correspondentes de definição de função no momento da implantação.

Namespace: az.

Parâmetros

Valor retornado

Um objeto que representa a definição de função, incluindo id e roleDefinitionId.

Exemplos

O código Bicep a seguir cria uma atribuição determinística de função RBAC no Azure que concede a um principal especificado o papel incorporado de Leitor de Dados de Blob de Armazenamento no escopo de implantação, resolvendo a definição do papel pelo nome no momento da implantação.

@description('Specifies the role definition ID used in the role assignment.')
param roleDefinitionName string = 'Storage Blob Data Reader'

@description('Specifies the principal ID assigned to the role.')
param principalId string

var roleAssignmentName= guid(principalId, roleDefinitionName, resourceGroup().id)
resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: roleAssignmentName
  properties: {
    roleDefinitionId: roleDefinitions(roleDefinitionName).id
    principalId: principalId
  }
}

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 o ID de recurso para recursos que são implantados na assinatura , em vez de um grupo de recursos. A ID retornada difere do valor retornado pela função resourceId 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 lógica de disponibilidade (por exemplo, 1, 2, ou 3) que corresponde a uma zona física de disponibilidade para uma assinatura específica em uma determinada região do Azure.

Namespace: az

Parâmetros

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 suportada, a função retorna uma string vazia ('').

Comentários

• A toLogicalZone função recupera o mapeamento de zona lógica com base na configuração de zona da assinatura na região especificada.
• Zonas lógicas são identificadores padronizados (por exemplo, 1, 2, 3) usados em configurações de recursos para garantir atribuições de zona consistentes em serviços de Azure.
• Identificadores físicos de zona são específicos de cada região e podem variar entre assinaturas. Use a toPhysicalZone funçã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 Azure serviços 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:

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:

toLogicalZones

toLogicalZones(subscriptionId, location, physicalZones)

Retorna as zonas de disponibilidade lógica (por exemplo, 1, 2 ou 3) correspondentes a zonas de disponibilidade física para uma assinatura especificada em uma determinada região de Azure. Para converter uma única zona física, use a toLogicalZone função.

Namespace: az

Parâmetros

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 suportada, a função retorna uma cadeia vazia ('').

Comentários

A função toLogicalZones mapeia nomes de zona física para seus equivalentes de zona lógica para uma assinatura e região Azure especificadas. Esse mapeamento é útil para configurar ou consultar recursos com base em zonas lógicas dentro de uma região do Azure. A função requer uma ID de assinatura válida, um local de 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 pode retornar uma string vazia para aquela 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:

toPhysicalZone

toPhysicalZone(subscriptionId, location, logicalZone)

Retorna o identificador da zona de disponibilidade física, como um identificador específico do data center, como westus2-az1, que corresponde a uma zona lógica de disponibilidade para uma assinatura específica em uma determinada região do Azure.

Namespace: az

Parâmetros

Valor retornado

Uma string que representa o identificador da zona de disponibilidade física, como westus2-az1, que corresponde à zona lógica especificada na região e assinatura dadas. Se a zona lógica for inválida ou não suportada, a função retorna uma cadeia vazia ('').

Comentários

• A toPhysicalZone funçã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 de data center que podem variar entre assinaturas, enquanto zonas lógicas, como 1, 2, 3, são padronizadas para configurações de recursos.
• Use a toLogicalZone função para reverter esse mapeamento e converter uma zona física para 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 Azure serviços 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 físicos de zona, como registro, auditoria ou alinhamento de zonas entre assinaturas em implantações multirregiõ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):

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:

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 de Azure. Para converter uma única zona lógica, use a toPhysicalZone função.

Namespace: az

Parâmetros

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 suportada, a função retorna uma cadeia vazia ('').

Comentários

A função toPhysicalZones mapeia nomes de zona lógica para seus equivalentes de zona física para uma assinatura e região Azure especificadas. Esse mapeamento é útil para implantar ou configurar recursos em zonas físicas específicas dentro de uma região do Azure. A função requer uma ID de assinatura válida, um local de 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 pode retornar uma string 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):

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, consulte loops Iterative em Bicep.