Funciones de recursos para Bicep

En este artículo se describen las funciones de Bicep para obtener valores de recursos.

Para obtener valores de la implementación actual, consulte Funciones con valores de implementación.

El espacio de nombres this

El this espacio de nombres proporciona funciones para el descubrimiento del estado del recurso en tiempo de ejecución dentro de una definición de recurso. Estas funciones permiten que tu plantilla adapte su configuración en función de si un recurso ya existe en el entorno.

• this.exists(): Devuelve un valor bool que indica si el recurso existe actualmente.
• this.existingResource(): Devuelve la representación del objeto del recurso si existe, o nulo si no existe.

existe

this.exists()

Devuelve un valor bool que indica si el recurso existe actualmente en Azure. Esta función se evalúa durante el despliegue y está destinada a usarse dentro de asignaciones de propiedades de recursos para manejar lógica condicional sin requerir declaraciones de recursos existentes separadas.

Espacio de nombres: esto

Ejemplo

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'
  }
}

Recurso existente

this.existingResource()

Devuelve la representación del objeto del recurso si existe, o null si no. Esta función se empareja con this.exists(). While exists() devuelve un booleano simple, existingResource() devuelve el objeto de recurso real. Puedes acceder de forma segura a propiedades anidadas usando el operador nulo que perdona (!) o el operador de navegación segura (.?).

Espacio de nombres: esto

Ejemplo

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], ...)

Devuelve el id. de recurso de un recurso de extensión. Un recurso de extensión es un tipo de recurso que aplicas a otro recurso para añadir a sus capacidades.

Espacio de nombres: az.

El primer argumento debe ser el ID de recurso completamente cualificado del recurso al que se aplica el recurso de extensión. Este requisito es especialmente importante cuando se despliega un recurso a nivel de inquilino desde un alcance menor, como una suscripción o un grupo de recursos. Un valor que se resuelve en el alcance del inquilino puede fallar cuando el despliegue comienza desde un alcance inferior.

Puedes usar la extensionResourceId función en los archivos de Bicep, pero normalmente no la necesitas. En su lugar, use el nombre simbólico del recurso y acceda a la propiedad id. La id propiedad devuelve el ID de recurso totalmente cualificado.

El formato básico del identificador de recurso devuelto por esta función es:

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

El segmento de ámbito varía según el recurso que se está ampliando.

Cuando aplicas el recurso de extensión a un recurso, el ID del recurso se devuelve en el siguiente formato:

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

Cuando aplicas el recurso de extensión a un grupo de recursos, el formato es:

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

Cuando aplicas el recurso de extensión a una suscripción, el formato es:

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

Cuando aplicas el recurso de extensión a un grupo de gestión, el formato es:

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

Una definición de directiva personalizada implementada en un grupo de administración se implementa como recurso de extensión. Para crear y asignar una directiva, implemente el siguiente archivo Bicep en un grupo de administración.

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
  }
}

Las definiciones de directivas integradas son recursos del nivel de inquilino. Para obtener un ejemplo de implementación de una definición de directiva integrada, consulte tenantResourceId.

getSecret

keyVaultName.getSecret(secretName)

Devuelve un secreto de un Azure Key Vault. Use esta función para pasar un secreto a un parámetro de cadena segura de un módulo de Bicep.

Solo puede usar la getSecret función desde la params sección de un módulo. Solo puede usarlo con un recurso Microsoft.KeyVault/vaults.

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

Aparece un error si intenta usar esta función en cualquier otra parte del archivo Bicep. También se produce un error si usa esta función con interpolación de cadenas, incluso cuando se utiliza en la sección de parámetros.

Usa la función solo con un parámetro de módulo que tenga el @secure() decorador.

El almacén de claves debe tener enabledForTemplateDeployment establecido en true. El usuario que implementa el archivo Bicep debe tener acceso al secreto. Para obtener más información, consulte Use Azure Key Vault para pasar el valor de parámetro seguro durante la implementación de Bicep.

No es necesario un calificador de espacio de nombres porque la función se usa con un tipo de recurso.

Parámetros

Valor devuelto

Valor del secreto para el nombre del secreto.

Ejemplo

El siguiente archivo Bicep se usa como módulo. Tiene un parámetro adminPassword definido con el decorador @secure().

param sqlServerName string
param adminLogin string

@secure()
param adminPassword string

resource sqlServer 'Microsoft.Sql/servers@2024-11-01-preview' = {
  ...
}

El siguiente archivo Bicep consume el archivo Bicep anterior como módulo. El archivo Bicep hace referencia a un almacén de claves existente y llama a la función getSecret para recuperar el secreto del almacén de claves y, a continuación, pasa el valor como parámetro al 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])

Puede llamar a una función de lista para cualquier tipo de recurso con una operación que comience por list. Algunos usos habituales son list, listKeys, listKeyValue y listSecrets.

La sintaxis de esta función varía según el nombre de la operación de la lista. Los valores devueltos también varían según la operación. Bicep no admite actualmente finalizaciones ni validación para funciones de list*.

Con Bicep CLI versión 0.4.X o posterior, llame a la función list mediante el operador accessor. Por ejemplo, storageAccount.listKeys().

No es necesario un calificador de espacio de nombres porque la función se usa con un tipo de recurso.

Parámetros

Usos válidos

Utiliza las list funciones en las propiedades de una definición de recurso. No utilices una list función que exponga información sensible en la outputs sección de un archivo Bicep. Los valores de salida se almacenan en el historial de despliegue y un usuario malicioso podría recuperarlos.

Cuando usas una list función con un bucle iterativo, puedes usarla porque input la expresión se asigna a la propiedad de recurso. No puedes usarlo con count porque el recuento debe determinarse antes de que la list función se resuelva.

Si usa una función list con un recurso que se implementa de forma condicional, se puede evaluar la función incluso si el recurso no está implementado. Se genera un error si la función list hace referencia a un recurso que no existe. Use el operador de expresión condicional ?: para asegurarse de que la función solo se evalúa cuando se implementa el recurso.

La use-recognized-resource-type regla linter marca cualquier recurso referenciado que utilice un tipo de recurso no reconocido o inválido.

Valor devuelto

El objeto devuelto varía según la función list que use. Por ejemplo, la listKeys función para una cuenta de almacenamiento devuelve el siguiente formato:

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

Otras funciones list tienen otros formatos de devolución. Para ver el formato de una función, inclúyela en la outputs sección mostrada en el archivo de ejemplo de Bicep.

Ejemplo de lista

En el ejemplo siguiente se implementa una cuenta de almacenamiento y, después, se llama a listKeys en ella. La clave se utiliza cuando se configura un valor para los scripts de implementación.

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
    }
    ...
  }
}

En el ejemplo siguiente se muestra una función list que toma un parámetro. En este caso, la función es listAccountSas. Pase un objeto para la hora de expiración. Dicha hora debe 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

Implementaciones

La siguiente tabla muestra posibles usos de las list* funciones.

Para determinar qué tipos de recursos tienen una operación de lista, utilice las siguientes opciones:

• Vea las operaciones de API de REST para un proveedor de recursos y busque operaciones List. Por ejemplo, las cuentas de almacenamiento tienen una operación listKeys.

• Use el cmdlet de PowerShell Get-​AzProvider​Operation. En el ejemplo siguiente se obtienen todas las operaciones List para cuentas de almacenamiento:

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

• Use el siguiente comando CLI de Azure para filtrar solo las operaciones de lista:

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

managementGroupResourceId

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

Devuelve el identificador único de un recurso implementado en el nivel de grupo de administración.

Espacio de nombres: az.

La managementGroupResourceId función está disponible en archivos Bicep, pero normalmente no la necesitas. En su lugar, use el nombre simbólico del recurso y acceda a la propiedad id.

El identificador se devuelve con el formato siguiente:

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

Observaciones

Utiliza esta función para obtener el ID de recurso de los recursos que se despliegan en el grupo de gestión en lugar de en un grupo de recursos. El id. devuelto difiere del valor devuelto por la función resourceId en que no incluye un valor de id. de subscripción ni de grupo de recursos.

Ejemplo de managementGroupResourceID

La siguiente plantilla crea y asigna una definición de directiva. Usa la función managementGroupResourceId para obtener el id. de recurso de la definición de directiva.

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 si un tipo de recurso admite zonas para una región. Esta función solo admite recursos zonales. Los servicios con redundancia de zona devuelven una matriz vacía. Para obtener más información, consulte servicios Azure que admiten zonas de disponibilidad.

Espacio de nombres: az.

Parámetros

Valor devuelto

Matriz con las zonas admitidas. Cuando usas los valores por defecto para offset y numberOfZones, un tipo de recurso y una región que soporta zonas devuelve el siguiente array:

[
  "1"
]

Cuando estableces el numberOfZones parámetro en 3, devuelve:

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

Cuando el tipo de recurso o la región no soporta zonas, la función devuelve un array vacío.

[
]

Observaciones

Azure Availability Zones se dividen en dos categorías: zonal y redundante por zona. Utiliza la pickZones función para devolver una zona de disponibilidad para un recurso zonal. En el caso de servicios con redundancia de zona (ZRS), la función devuelve una matriz vacía. Los recursos zonales suelen tener una propiedad zones en el nivel superior de la definición del recurso. Para determinar la categoría de compatibilidad con zonas de disponibilidad, consulte Azure servicios que admiten zonas de disponibilidad.

Para determinar si una región o ubicación de Azure determinada admite zonas de disponibilidad, llame a la función pickZones con un tipo de recurso zonal, como Microsoft.Network/publicIPAddresses. Si la respuesta no está vacía, la región admite zonas de disponibilidad.

Ejemplo de pickZones

El siguiente archivo Bicep muestra tres resultados para usar la función 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')

La salida de los ejemplos anteriores devuelve tres matrices.

Utiliza la respuesta de pickZones para decidir si proporcionar nulo para zonas o asignar máquinas virtuales a diferentes zonas.

Proveedores

La función de los proveedores está obsoleta en Bicep. No lo uses. Si has usado esta función para obtener una versión de API para el proveedor de recursos, proporciona una versión específica de API en tu archivo Bicep. El uso de una versión de API devuelta dinámicamente puede interrumpir la plantilla si las propiedades cambian entre versiones.

La operación de proveedores sigue estando disponible a través de la API de REST. Puedes usarlo fuera de un archivo Bicep para obtener información sobre un proveedor de recursos.

Espacio de nombres: az.

referencia

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

Devuelve un objeto que representa el estado de ejecución de un recurso. La salida y el comportamiento de la reference función dependen en gran medida de cómo cada proveedor de recursos (RP) implementa sus respuestas PUT y GET.

Espacio de nombres: az.

Los archivos Bicep permiten acceder a la función de referencia, aunque normalmente no la necesitas. En su lugar, utiliza el nombre simbólico del recurso. Solo puedes usar la función de referencia dentro del properties objeto de un recurso. No puedes usarlo para propiedades de nivel superior como name o location. La misma regla generalmente se aplica a referencias que usan el nombre simbólico. Sin embargo, para propiedades como name, puedes generar una plantilla sin usar la función de referencia. Sabes lo suficiente sobre el nombre del recurso como para emitir el nombre directamente. Estas son propiedades en tiempo de compilación. Bicep validación puede identificar cualquier uso incorrecto del nombre simbólico.

En el ejemplo siguiente se implementa una cuenta de almacenamiento. Las dos primeras salidas proporcionan los mismos 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 obtener una propiedad de un recurso existente que no desplegaste en la plantilla, usa la existing palabra clave:

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 un recurso que está anidado dentro de un recurso padre, utiliza el accesorio anidado (::). Esta sintaxis solo se usa cuando se accede al recurso anidado desde fuera del recurso primario.

vNet1::subnet1.properties.addressPrefix

Si intenta hacer referencia a un recurso que no existe, se produce el error NotFound y se produce un error en la implementación. La use-recognized-resource-type regla linter marca cualquier recurso referenciado que utilice un tipo de recurso no reconocido o inválido.

identificador de recurso

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

Devuelve el identificador único de un recurso.

Espacio de nombres: az.

La resourceId función está disponible en archivos Bicep, pero normalmente no la necesitas. En su lugar, use el nombre simbólico del recurso y acceda a la propiedad id.

Utiliza esta función cuando el nombre del recurso sea ambiguo o no esté provisionado dentro del mismo archivo Bicep. El formato del identificador devuelto varía en función de si la implementación se produce en el ámbito de un grupo de recursos, una suscripción, un grupo de administración o un inquilino.

Por ejemplo:

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 obtener el identificador de recurso de un recurso que no se implementa en el archivo Bicep, use la palabra clave existente.

param storageAccountName string

resource storageAccount 'Microsoft.Storage/storageAccounts@2025-06-01' existing = {
  name: storageAccountName
}

output storageID string = storageAccount.id

Para obtener más información, consulte la función resourceId de plantilla JSON.

definiciones de roles

roleDefinitions(roleName)

Devuelve información sobre la definición de roles especificada, incluidos id y roleDefinitionId. Es un asistente basado en nombres para Azure asignaciones de roles de RBAC. En lugar de requerir que codifiques el GUID de una definición de rol personalizada o integrada (como Contributor, Reader y otros), te permite proporcionar el nombre de visualización del rol personalizado o incorporado, y la función resuelve la información correspondiente de definición de rol en el momento del despliegue.

Espacio de nombres: az.

Parámetros

Valor devuelto

Objeto que representa la definición de roles, incluidos id y roleDefinitionId.

Ejemplos

El siguiente código Bicep crea una asignación determinista de rol RBAC en Azure que otorga a un principal especificado el rol integrado de Lector de Datos de Blob de Almacenamiento en el ámbito de despliegue al resolver la definición del rol por nombre en el momento del despliegue.

@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 obtener más información, consulte la función resourceId de plantilla JSON.

subscriptionResourceId

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

Devuelve el identificador único de un recurso implementado en el nivel de suscripción.

Espacio de nombres: az.

La función subscriptionResourceId está disponible en archivos Bicep, pero normalmente no lo necesita. En su lugar, use el nombre simbólico del recurso y acceda a la propiedad id.

El identificador se devuelve con el formato siguiente:

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

Observaciones

Utiliza esta función para obtener el ID de recurso de los recursos que se despliegan en la suscripción en lugar de en un grupo de recursos. El identificador devuelto difiere del valor devuelto por la función resourceId en que no incluye un valor de grupo de recursos.

Ejemplo de subscriptionResourceId

El siguiente archivo Bicep asigna un rol integrado. Puede implementarlo en un grupo de recursos o en una suscripción. Usa la función subscriptionResourceId para obtener el id. de recurso de los recursos integrados.

@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], ...)

Devuelve el identificador único de un recurso implementado en el nivel de inquilino.

Espacio de nombres: az.

La función tenantResourceId está disponible en archivos Bicep, pero normalmente no lo necesita. En su lugar, use el nombre simbólico del recurso y acceda a la propiedad id.

El identificador se devuelve con el formato siguiente:

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

Las definiciones de directivas integradas son recursos del nivel de inquilino. Para implementar una asignación de directiva que hace referencia a una definición de directiva integrada, use la función 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)

Devuelve la zona de disponibilidad lógica (por ejemplo, 1, 2, o 3) que corresponde a una zona física de disponibilidad para una suscripción especificada en una región de Azure dada.

Espacio de nombres: az

Parámetros

Valor devuelto

Cadena que representa la zona de disponibilidad lógica (por ejemplo, 1, 2o 3) que corresponde a la zona física especificada en la región y la suscripción especificadas. Si la zona física es inválida o no está soportada, la función devuelve una cadena vacía ('').

Observaciones

• La toLogicalZone función recupera la asignación de zona lógica en función de la configuración de zona de la suscripción en la región especificada.
• Las zonas lógicas son identificadores estandarizados (por ejemplo, 1, 2, 3) usados en configuraciones de recursos para garantizar asignaciones de zona coherentes en Azure servicios.
• Los identificadores de zonas físicas son específicos de cada región y pueden variar entre suscripciones. Use la toPhysicalZone función para invertir esta asignación.
• La función requiere que la región admita zonas de disponibilidad. Para obtener una lista de las regiones admitidas, consulte Azure services that support availability zones.
• Si la zona física no existe o no está asignada para la suscripción, la función devuelve una cadena vacía.
• Esta función es útil para alinear implementaciones de zona física con configuraciones de zona lógica en plantillas, especialmente para escenarios entre suscripciones o de varias regiones.

Ejemplos

En el ejemplo siguiente se recupera la zona lógica de una zona física en Oeste de EE. UU. 2 para una suscripción específica:

param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param physicalZone string = 'westus2-az1'

output logicalZone string = toLogicalZone(subscriptionId, 'westus2', physicalZone)

Resultado esperado:

En el ejemplo siguiente se usa toLogicalZone para configurar una máquina virtual con la zona lógica correcta:

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)

Devuelve las zonas de disponibilidad lógicas (por ejemplo, 1, 2 o 3) correspondientes a zonas de disponibilidad física para una suscripción especificada en una región de Azure determinada. Para convertir una sola zona física, use la toLogicalZone función .

Espacio de nombres: az

Parámetros

Valor devuelto

Matriz de nombres de zona lógica correspondientes a las zonas físicas proporcionadas (por ejemplo, 1, 2o 3). Si una zona física es inválida o no está soportada, la función devuelve una cadena vacía ('').

Observaciones

La función toLogicalZones asigna nombres de zona física a sus equivalentes de zona lógica para una suscripción y región de Azure especificadas. Esta asignación es útil para configurar o consultar recursos basándose en zonas lógicas dentro de una región de Azure. La función requiere un identificador de suscripción válido, una ubicación de Azure compatible y una matriz de nombres de zona física. Si una zona física es inválida o no está disponible en la ubicación especificada, la función puede devolver una cadena vacía para esa zona o generar un error, dependiendo del contexto.

Ejemplos

En el ejemplo siguiente se recuperan las zonas lógicas de una lista de zonas físicas de Oeste de EE. UU. 2 para una suscripción 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)

Devuelve el identificador de zona de disponibilidad física, como un identificador específico del centro de datos como westus2-az1, que corresponde a una zona lógica de disponibilidad para una suscripción específica en una región de Azure dada.

Espacio de nombres: az

Parámetros

Valor devuelto

Una cadena que representa el identificador físico de la zona de disponibilidad, como westus2-az1, que corresponde a la zona lógica especificada en la región y suscripción dadas. Si la zona lógica es inválida o no está soportada, la función devuelve una cadena vacía ('').

Observaciones

• La toPhysicalZone función recupera la asignación de zona física en función de la configuración de zona de la suscripción en la región especificada.
• Las zonas físicas son identificadores específicos de cada centro de datos que pueden variar entre suscripciones, mientras que las zonas lógicas, como 1, 2, 3, están estandarizadas para configuraciones de recursos.
• Utiliza la toLogicalZone función para invertir esta correspondencia y convertir una zona física a su equivalente lógico.
• La función requiere que la región admita zonas de disponibilidad. Para obtener una lista de las regiones admitidas, consulte Azure services that support availability zones.
• Si la zona lógica no existe o no está asignada para la suscripción, la función devuelve una cadena vacía.
• Esta función es útil para escenarios que requieren identificadores físicos de zona, como registros, auditorías o alineación de zonas entre suscripción en despliegues multirregión.

Ejemplos

En el ejemplo siguiente se recupera la zona física de una zona lógica en Oeste de EE. UU. 2 para una suscripción específica:

param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param logicalZone string = '1'

output physicalZone string = toPhysicalZone(subscriptionId, 'westus2', logicalZone)

Salida esperada (suponiendo que la zona 1 lógica se asigne a westus2-az1):

En el ejemplo siguiente se usa toPhysicalZone para registrar la zona física de una implementación 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)

Devuelve los identificadores de zona de disponibilidad física (por ejemplo, un identificador específico del centro de datos, como westus2-az1) correspondiente a zonas de disponibilidad lógicas para una suscripción especificada en una región de Azure determinada. Para convertir una sola zona lógica, use la toPhysicalZone función .

Espacio de nombres: az

Parámetros

Valor devuelto

Matriz de nombres de zona física (por ejemplo, westus2-az1, westus2-az2 ) correspondientes a las zonas lógicas proporcionadas. Si una zona lógica es inválida o no está soportada, la función devuelve una cadena vacía ('').

Observaciones

La función />

Ejemplos

En el ejemplo siguiente se recuperan las zonas físicas de una lista de zonas lógicas de Oeste de EE. UU. 2 para una suscripción específica:

param subscriptionId string = '12345678-1234-1234-1234-1234567890ab'
param logicalZones array = ['1', '2', '3']

output physicalZones array = toPhysicalZones(subscriptionId, 'westus2', logicalZones)

Salida esperada (suponiendo que la zona 1 lógica se asigna a westus2-az1, la zona 1 lógica se asigna a westus2-az1y la zona 3 lógica se asigna a westus2-az3):

Pasos siguientes

• Para obtener valores de la implementación actual, consulte Funciones con valores de implementación.
• Para iterar un número especificado de veces al crear un tipo de recurso, consulte bucles Iterative en Bicep.