Compartir por

Salidas en Bicep

  • Artigo

En este artículo, se describe cómo definir valores de salida en un archivo de Bicep. Las salidas se usan cuando es necesario devolver valores de los recursos implementados. Está limitada a 64 salidas en un archivo Bicep. Para obtener más información, consulte Límites de plantilla.

Definir las salidas

La sintaxis para definir un valor de salida es:

output <name> <data-type or type-expression> = <value>

Una salida puede tener el mismo nombre que un parámetro, una variable, un módulo o un recurso. Cada valor de salida debe resolverse en uno de los tipos de datos o la expresión de tipo de datos definida por el usuario.

En el ejemplo siguiente se muestra cómo devolver una propiedad desde un recurso implementado. En el ejemplo, publicIP es el nombre simbólico de una dirección IP pública implementada en el archivo de Bicep. El valor de salida obtiene el nombre de dominio completo de la dirección IP pública.

output hostname string = publicIP.properties.dnsSettings.fqdn

En el ejemplo siguiente se muestra cómo devolver salidas de distintos tipos.

output stringOutput string = deployment().name
output integerOutput int = length(environment().authentication.audiences)
output booleanOutput bool = contains(deployment().name, 'demo')
output arrayOutput array = environment().authentication.audiences
output objectOutput object = subscription()

Si necesita generar una propiedad que tenga un guion en el nombre, use corchetes alrededor del nombre en lugar de la notación de puntos. Por ejemplo, use ['property-name'] en lugar de .property-name.

var user = {
  'user-name': 'Test Person'
}

output stringOutput string = user['user-name']

En el ejemplo siguiente se muestra cómo usar la expresión de tipo:

param foo 'a' | 'b' = 'a'

output out 'a' | 'b' = foo

Para obtener más información, consulte Tipos de datos definidos por el usuario.

Usar decoradores

Los decoradores se escriben en el formato @expression y se colocan encima de las declaraciones de salida. La siguiente tabla muestra los decoradores disponibles para las salidas.

Decorador Aplicar a Argumento Descripción
descripción all string Proporcione descripciones para la salida.
discriminator objeto string Use este decorador para asegurarse de que la subclase correcta se identifica y administra. Para obtener más información, vea Tipo de datos de unión etiquetado personalizado.
maxLength array, string int Longitud máxima de las salidas de cadena y matriz. El valor es inclusivo.
maxValue int int El valor máximo para la salida de enteros. Este valor es inclusivo.
metadata all objeto Propiedades personalizadas que se aplicarán a la salida. Pueden incluir una propiedad de descripción equivalente al decorador de la descripción.
minLength array, string int La longitud mínima para las salidas de cadenas y matrices. El valor es inclusivo.
minValue int int El valor mínimo para la salida de enteros. Este valor es inclusivo.
sealed objeto None Eleve BCP089 de una advertencia a un error cuando es probable que un nombre de propiedad de un tipo de datos use-define sea un error tipográfico. Para obtener más información, consulte Elevación del nivel de error.

Los decoradores están en el espacio de nombres sys. Si tiene que diferenciar un decorador de otro elemento con el mismo nombre, anteceda el decorador con sys. Por ejemplo, si el archivo de Bicep incluye un parámetro llamado description, debe agregar el espacio de nombres sys al usar el decorador description.

@sys.description('The name of the instance.')
param name string
@sys.description('The description of the instance to display.')
param description string

Descripción

Para añadir una explicación, añada una descripción a las declaraciones de salida. Por ejemplo:

@description('Conditionally output the endpoint.')
output endpoint string = deployStorage ? myStorageAccount.properties.primaryEndpoints.blob : ''

El texto con formato Markdown se puede usar para el texto de descripción.

Discriminador

Consulte Tipo de datos de unión con etiquetado personalizado.

Restricciones de enteros

Puede establecer valores mínimos y máximos para las salidas de cantidades enteras. Puede establecer una o las dos restricciones.

var thisMonth = 3

@minValue(1)
@maxValue(12)
output month int = thisMonth

Restricciones de longitud

Puede especificar longitudes mínimas y máximas para las salidas de cadenas y matrices. Puede establecer una o las dos restricciones. Para las cadenas, la longitud indica el número de caracteres. Para las matrices, la longitud indica el número de elementos de la matriz.

En el ejemplo siguiente declara dos salidas. Una salida es para un nombre de cuenta de almacenamiento que debe tener entre 3 y 24 caracteres. La otra salida es una matriz que debe tener de 1 a 5 elementos.

var accountName = uniqueString(resourceGroup().id)
var appNames = [
  'SyncSphere'
  'DataWhiz'
  'FlowMatrix'
]

@minLength(3)
@maxLength(24)
output storageAccountName string = accountName

@minLength(1)
@maxLength(5)
output applicationNames array = appNames

Metadatos

Si tiene propiedades personalizadas que desea aplicar a una salida, añada un decorador de metadatos. Dentro de los metadatos, defina un objeto con los nombres y valores personalizados. El objeto que defina para los metadatos puede contener propiedades de cualquier nombre y tipo.

Este decorador se puede utilizar para rastrear información sobre la salida que no tenga sentido añadir a la descripción.

var obj = {}
@description('Configuration values that are applied when the application starts.')
@metadata({
  source: 'database'
  contact: 'Web team'
})
output settings object = obj

Cuando se proporciona un decorador @metadata() con una propiedad que está en conflicto con otro decorador, ese decorador siempre tiene prioridad sobre cualquier elemento del decorador @metadata(). Por tanto, la propiedad en conflicto dentro del valor @metadata() es redundante y se reemplazará. Para obtener más información, consulte Regla de linter: no-conflicting-metadata.

Sellado

Consulte Elevación del nivel de error.

Salida condicional

Cuando el valor que se va a devolver depende de una condición de la implementación, use el operador ?.

output <name> <data-type> = <condition> ? <true-value> : <false-value>

Por norma general, se usa una salida condicional cuando se implementa condicionalmente un recurso. En el ejemplo siguiente, se muestra cómo se devuelve condicionalmente el identificador de recurso de una dirección IP pública en función de si se ha implementado una nueva.

Para especificar una salida condicional en Bicep, use el operador ?. En el ejemplo siguiente se devuelve una dirección URL de punto de conexión o una cadena vacía en función de una condición.

param deployStorage bool = true
param storageName string
param location string = resourceGroup().location

resource myStorageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' = if (deployStorage) {
  name: storageName
  location: location
  kind: 'StorageV2'
  sku:{
    name:'Standard_LRS'
    tier: 'Standard'
  }
  properties: {
    accessTier: 'Hot'
  }
}

output endpoint string = deployStorage ? myStorageAccount.properties.primaryEndpoints.blob : ''

Número dinámico de salidas

En algunos escenarios, no se conoce el número de instancias de un valor que se debe devolver al crear la plantilla. Puede devolver un número variable de valores mediante la expresión for.

output <name> <data-type> = [for <item> in <collection>: {
  ...
}]

En el ejemplo siguiente se recorre en iteración una matriz.

param nsgLocation string = resourceGroup().location
param orgNames array = [
  'Contoso'
  'Fabrikam'
  'Coho'
]

resource nsg 'Microsoft.Network/networkSecurityGroups@2023-11-01' = [for name in orgNames: {
  name: 'nsg-${name}'
  location: nsgLocation
}]

output deployedNSGs array = [for (name, i) in orgNames: {
  orgName: name
  nsgName: nsg[i].name
  resourceId: nsg[i].id
}]

Para más información sobre los bucles, consulte Bucles iterativos en Bicep.

Salidas de módulos

Para obtener un valor de salida de un módulo, use la sintaxis siguiente:

<module-name>.outputs.<property-name>

En el ejemplo siguiente, se muestra cómo establecer la dirección IP en un equilibrador de carga mediante la recuperación de un valor desde un módulo.

module publicIP 'modules/public-ip-address.bicep' = {
  name: 'public-ip-address-module'
}

resource loadBalancer 'Microsoft.Network/loadBalancers@2023-11-01' = {
  name: loadBalancerName
  location: location
  properties: {
    frontendIPConfigurations: [
      {
        name: 'name'
        properties: {
          publicIPAddress: {
            id: publicIP.outputs.resourceId
          }
        }
      }
    ]
    // ...
  }
}

Obtención de valores de salida

Cuando la implementación se realiza correctamente, los valores de salida se devuelven automáticamente en los resultados de la implementación.

Para obtener valores de salida del historial de implementación, puede usar la CLI de Azure o un script de Azure PowerShell.

(Get-AzResourceGroupDeployment `
  -ResourceGroupName <resource-group-name> `
  -Name <deployment-name>).Outputs.resourceID.value

Ordenación de objetos en salidas

En JSON, un objeto es una colección desordenada de cero o más pares clave-valor. El orden puede ser diferente en función de las implementaciones. Por ejemplo, la función Bicep items() ordena los objetos por orden alfabético. En otros lugares, se puede conservar la ordenación original. Debido a este no determinismo, evite realizar suposiciones sobre el orden de las claves de objeto al escribir código, que interactúa con los parámetros y salidas de implementación.

Pasos siguientes