Sorties dans Bicep

Cet article explique comment définir des valeurs de sortie dans un fichier Bicep. Vous utilisez des sorties quand vous devez retourner des valeurs à partir des 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 en expression du type de données définie par l’utilisateur.

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 types différents.

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

Pour plus d'informations, voir Type de données définis par l’utilisateur.

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 des sorties.

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 contient un paramètre nommé description, vous devez ajouter l’espace de noms sys lors de l’utilisation de l’élément décoratif description.

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

Description

Pour ajouter une explication, ajoutez une description aux déclarations de sorties. 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 de type entier. Vous pouvez définir une contrainte ou les deux.

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 compter 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. Par conséquent, la propriété en conflit dans la valeur @metadata() est redondante et sera remplacée. Pour plus d’informations, consultez Aucune métadonnée en conflit.

Scellé

Consultez Élever le niveau d’erreur.

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 renvoie une URL de point de terminaison ou une chaîne vide en fonction 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 retourner un nombre variable de valeurs à l’aide de l’expression for.

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 définir l’adresse IP sur un équilibreur de charge en récupérant une valeur à partir d’un module.

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 terminé, les valeurs de sortie sont automatiquement retournées dans les résultats du déploiement.

Pour obtenir des valeurs de sortie à partir de l’historique des déploiements, vous pouvez utiliser un script Azure CLI ou Azure PowerShell.

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

az deployment group show \
  -g <resource-group-name> \
  -n <deployment-name> \
  --query properties.outputs.resourceID.value

Tri d’objets dans les sorties

Dans JSON, un objet est une collection non ordonnée de zéro ou plus paires clé/valeur. L’ordre peut être différent selon les implémentations. Par exemple, la fonction Bicep items() trie les objets par ordre alphabétique. Dans d’autres endroits, l’ordre d’origine peut être conservé. En raison de ce non-déterminisme, évitez de faire des hypothèses sur l’ordre des clés des objets lors de l’écriture du code, ce qui interagit avec les paramètres et les sorties des déploiements.

Étapes suivantes

• Pour plus d’informations sur les propriétés disponibles pour les sorties, consultez Présentation de la structure et de la syntaxe de Bicep.