Partager via

Sorties dans Bicep

Cet article explique comment définir des valeurs de sortie dans un fichier Bicep. Vous utilisez des sorties lorsque vous devez retourner des valeurs à partir de ressources déployées. Vous êtes limité à 64 sorties dans un fichier Bicep. Pour plus d’informations, consultez Limites du modèle.

Définir les sorties

La syntaxe permettant de définir une valeur de sortie est la suivante :

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

Une sortie peut avoir le même nom qu’un paramètre, une variable, un module ou une ressource. Chaque valeur de sortie doit être résolue en un des types de données ou des types de données définis par l’utilisateur dans Bicep.

L’exemple suivant montre comment renvoyer une propriété à partir d’une ressource déployée. Dans l’exemple, publicIP est le nom symbolique d’une adresse IP publique déployée dans le fichier Bicep. La valeur de sortie obtient le nom de domaine complet pour l’adresse IP publique :

output hostname string = publicIP.properties.dnsSettings.fqdn

L’exemple suivant montre comment retourner des sorties de différents types :

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 vous avez besoin de générer une propriété dont le nom comporte un trait d’union, utilisez des crochets autour du nom au lieu de la notation par points. Par exemple, utilisez ['property-name'] au lieu de .property-name.

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

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

L’exemple suivant montre comment utiliser une expression du type :

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

output out 'a' | 'b' = foo

Utiliser des éléments décoratifs

Les éléments décoratifs sont écrits au format @expression et sont placés au-dessus des déclarations de sorties. Le tableau suivant présente les décorateurs disponibles pour les sorties :

Élément décoratif S’applique à Raisonnement Descriptif
description tout ficelle Il fournit des descriptions pour la sortie.
discriminant objet ficelle Utilisez cet élément décoratif pour vous assurer que la sous-classe appropriée est identifiée et gérée. Pour plus d’informations, consultez Type de données union étiqueté personnalisé.
maxLength tableau, chaîne Int Cela fournit la longueur maximale des sorties de chaîne et de tableau, et la valeur est inclusive.
maxValue Int Int Cela fournit la valeur maximale pour la sortie entière et la valeur est inclusive.
métadonnées tout objet Cela fournit des propriétés personnalisées à appliquer à la sortie et peut inclure une propriété de description équivalente au décorateur de description.
minLength tableau, chaîne Int Cela fournit la longueur minimale des sorties de chaîne et de tableau, et la valeur est inclusive.
minValue Int Int Cela fournit la valeur minimale pour la sortie entière et la valeur est inclusive.
scellé objet Aucune Élever BCP089 d’avertissement à erreur lorsqu’un nom de propriété d’un type de données défini par l’utilisateur est probablement une faute de frappe. Pour plus d’informations, consultez Élever le niveau d’erreur.
sûr string, objet Aucune Marque la sortie comme sécurisée. La valeur d’une sortie sécurisée n’est pas enregistrée dans l’historique du déploiement et n’est pas journalisée. Pour plus d’informations, consultez Sécuriser les chaînes et les objets.

Les éléments décoratifs se trouvent dans l’espace de noms sys. Si vous devez différencier un élément décoratif d'un autre élément portant le même nom, faites précéder l’élément décoratif de sys. Par exemple, si votre fichier Bicep inclut un paramètre nommé description, vous devez ajouter l'espace de noms sys lors de l’utilisation du décorateur description.

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

Descriptif

Pour ajouter une explication, ajoutez une description aux déclarations de sortie. Par exemple :

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

Du texte au format Markdown peut être utilisé pour le texte de description.

Discriminant

Consultez Type de données d’union personnalisées.

Contraintes d’entier

Vous pouvez définir des valeurs minimales et maximales pour les sorties entières et une ou les deux contraintes.

var thisMonth = 3

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

Contraintes de longueur

Vous pouvez spécifier des longueurs minimale et maximale pour les sorties de chaîne et de tableau. Vous pouvez définir une contrainte ou les deux. Pour les chaînes, la longueur indique le nombre de caractères. Pour les tableaux, la longueur indique le nombre d’éléments dans le tableau.

L’exemple suivant déclare deux sorties. Une sortie est destinée à un nom de compte de stockage qui doit compter entre 3 et 24 caractères. L’autre sortie est un tableau qui doit comporter entre 1 et 5 éléments :

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

Métadonnées

Si vous disposez de propriétés personnalisées que vous souhaitez appliquer à une sortie, ajoutez un élément décoratif de métadonnées. Dans les métadonnées, définissez un objet avec des noms et valeurs personnalisés. L’objet que vous définissez pour les métadonnées peut contenir des propriétés de n’importe quel nom et type.

Vous pouvez utiliser cet élément décoratif pour suivre les informations relatives à la sortie qu'il n'est pas utile d'ajouter à la description.

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

Lorsque vous fournissez un @metadata() élément décoratif avec une propriété qui est en conflit avec un autre élément décoratif, cet élément décoratif est toujours prioritaire sur tout ce qui se passe dans @metadata() l’élément décoratif. À son tour, la propriété en conflit dans la @metadata() valeur est redondante et sera remplacée. Pour plus d’informations, consultez la règle Linter : aucune métadonnées en conflit.

Scellé

Consultez Élever le niveau d’erreur.

Sorties sécurisées

Avec Bicep version 0.35.1 et ultérieure, vous pouvez marquer les sorties de chaîne ou d’objet comme sécurisées. Lorsqu’une sortie est décorée, @secure()Azure Resource Manager traite la valeur de sortie comme sensible, ce qui l’empêche d’être journalisée ou affichée dans l’historique de déploiement, le portail Azure ou les sorties de ligne de commande.

@secure()
output demoPassword string

@secure()
output demoSecretObject object

Le @secure() décorateur est valide uniquement pour les sorties de type chaîne ou d’objet, car celles-ci s’alignent sur les types secureString et secureObject dans les modèles ARM. Pour passer des tableaux ou des nombres en toute sécurité, encapsulez-les dans un objet secureObject ou sérialisez-les en tant que secureString.

Sortie conditionnelle

Lorsque la valeur à retourner dépend d’une condition dans le déploiement, utilisez l’opérateur ?.

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

En général, vous utilisez une sortie conditionnelle quand vous avez déployé de manière conditionnelle une ressource. L’exemple suivant montre comment retourner de façon conditionnelle l’ID de ressource pour une adresse IP publique si une nouvelle a été déployée.

Pour spécifier une sortie conditionnelle dans Bicep, utilisez l'opérateur ?. L’exemple suivant retourne une URL de point de terminaison ou une chaîne vide qui dépend d’une condition :

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

Nombre dynamique de sorties

Dans certains scénarios, vous ne connaissez pas le nombre d’instances d’une valeur que vous devez retourner lors de la création du modèle. Vous pouvez utiliser l’expression for pour retourner un nombre variable de valeurs.

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

L’exemple suivant itère au sein d’un tableau :

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

Pour plus d’informations sur les boucles, consultez Boucles itératives dans Bicep.

Sorties des modules

Pour récupérer une valeur de sortie à partir d’un module, utilisez la syntaxe suivante :

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

L’exemple suivant montre comment récupérer une valeur à partir d’un module pour définir l’adresse IP sur un équilibreur de charge :

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

Obtenir des valeurs de sortie

Une fois le déploiement réussi, les résultats du déploiement affichent automatiquement les valeurs de sortie.

Vous pouvez utiliser l’interface de ligne de commande Azure ou le script Azure PowerShell pour obtenir des valeurs de sortie à partir de l’historique du déploiement.

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

Tri d’objets dans les sorties

Dans JSON, un objet est une collection non ordonnée de zéro ou plusieurs paires clé ou valeur. L’ordre peut être différent en fonction des implémentations. Par exemple, la fonction Bicep items() trie les objets par ordre alphabétique. Dans d’autres endroits, vous pouvez conserver l’ordre d’origine. En raison de ce nondéterminisme, évitez d’effectuer des hypothèses sur l’ordre des clés d’objet lorsque vous écrivez du code, qui interagit avec les paramètres de déploiement et les sorties.

Étapes suivantes

Pour en savoir plus sur les propriétés disponibles pour les sorties, consultez la structure et la syntaxe des fichiers Bicep.