Output in Bicep

Questo articolo descrive come definire i valori di output in un file Bicep. Gli output vengono usati quando è necessario restituire valori dalle risorse distribuite. Sono limitati a 64 output in un file Bicep. Per altre informazioni, vedere Limiti dei modelli.

Definire gli output

La sintassi per la definizione di un valore di output è:

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

Un output può avere lo stesso nome di un parametro, di una variabile, di un modulo o di una risorsa. Ogni valore di output deve essere risolto in uno dei tipi di dati o in un'espressione di tipo di dati definita dall'utente.

Nell'esempio seguente viene illustrato come restituire una proprietà da una risorsa distribuita. Nell'esempio publicIP è il nome simbolico di un indirizzo IP pubblico distribuito nel file Bicep. Il valore di output ottiene il nome di dominio completo per l'indirizzo IP pubblico.

output hostname string = publicIP.properties.dnsSettings.fqdn

Nell'esempio seguente viene illustrato come restituire output di tipi diversi.

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()

Se è necessario restituire una proprietà con un trattino nel nome, usare le parentesi quadre intorno al nome anziché la notazione punto. Usare, ad esempio, ['property-name'] invece di .property-name.

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

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

L'esempio seguente illustra come usare l'espressione di tipo:

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

output out 'a' | 'b' = foo

Per altre informazioni, vedere Tipi di dati definiti dall'utente.

Usare elementi Decorator

Gli elementi Decorator vengono scritti nel formato @expression e vengono posizionati sopra le dichiarazioni di output. Nella tabella seguente vengono illustrati gli elementi Decorator disponibili per gli output.

I decorator si trovano nello spazio dei nomi sys. Se è necessario distinguere un decorator da un altro elemento con lo stesso nome, anteporre al decorator con sys. Ad esempio, se il file Bicep include un parametro denominato description, è necessario aggiungere lo spazio dei nomi sys quando si usa il decorator descrizione.

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

Descrizione

Per aggiungere una spiegazione, aggiungere una descrizione alle dichiarazioni di output. Ad esempio:

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

Il testo in formato Markdown può essere usato come testo dell'elemento description.

Discriminatore

Vedere Tipo di dati unione con tag personalizzati.

Vincoli sui numeri interi

È possibile impostare valori minimi e massimi per gli output integer. È possibile impostare uno o entrambi i vincoli.

var thisMonth = 3

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

Vincoli di lunghezza

È possibile specificare lunghezze minime e massime per gli output di stringa e matrice. È possibile impostare uno o entrambi i vincoli. Per le stringhe, la lunghezza indica il numero di caratteri. Per le matrici, la lunghezza indica il numero di elementi nell'array.

Nell'esempio seguente vengono dichiarati due output. Un output è per un nome di account di archiviazione che deve avere 3-24 caratteri. L'altro output è una matrice che deve avere da 1 a 5 elementi.

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

Metadati UFX

Se si dispone di proprietà personalizzate da applicare a un output, aggiungere un elemento Decorator di metadati. All'interno dei metadati definire un oggetto con i nomi e i valori personalizzati. L'oggetto definito per i metadati può contenere proprietà di qualsiasi nome e tipo.

È possibile usare questo elemento Decorator per tenere traccia delle informazioni sull'output che non ha senso aggiungere alla descrizione.

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

Quando si fornisce un decorator @metadata() con una proprietà in conflitto con un altro decorator, tale decorator ha sempre la precedenza su qualsiasi elemento nel decorator @metadata(). Pertanto, la proprietà in conflitto all'interno del valore @metadata() è ridondante e verrà sostituita. Per altre informazioni, vedere Nessun metadati in conflitto.

Sealed

Vedere Elevare il livello di errore.

Output condizionale

Quando il valore da restituire dipende da una condizione nella distribuzione, usare l'operatore ?.

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

In genere, si usa un output condizionale quando si ha distribuito un risorsa in modo condizionale. L'esempio seguente mostra come restituire in modo condizionale l'ID risorsa per un indirizzo IP pubblico in base al fatto che ne sia stato distribuito uno nuovo.

Per specificare un output condizionale in Bicep, usare l'operatore ?. Nell'esempio seguente viene restituito un URL dell'endpoint o una stringa vuota a seconda di una condizione.

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

Numero dinamico di output

In alcuni scenari non si conosce il numero di istanze di un valore che è necessario restituire durante la creazione del modello. È possibile restituire un numero variabile di valori usando l'espressione for.

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

Nell'esempio seguente viene iterazione su un array.

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

Per altre informazioni sui cicli, vedere Cicli iterativi in Bicep.

Output dai moduli

Per ottenere un valore di output da un modulo, usare la sintassi seguente:

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

L'esempio seguente illustra come impostare l'indirizzo IP in un servizio di bilanciamento del carico recuperando un valore da un modulo.

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

Ottenere i valori di output

Quando la distribuzione ha esito positivo, i valori di output vengono restituiti automaticamente nei risultati della distribuzione.

Per ottenere i valori di output dalla cronologia di distribuzione, è possibile usare l'interfaccia della riga di comando di Azure o lo script di 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

Ordinamento degli oggetti negli output

In JSON un oggetto è una raccolta non ordinata di zero o più coppie chiave/valore. L'ordinamento può variare, a seconda delle implementazioni. Ad esempio, la funzione Bicep items() dispone gli oggetti in ordine alfabetico. In altre posizioni, l'ordine originale può essere mantenuto. Dato questo non determinismo, è preferibile evitare di fare ipotesi sull'ordinamento delle chiavi oggetto durante la scrittura del codice, che interagisce con i parametri e gli output delle distribuzioni.

Passaggi successivi

• Per informazioni sulle proprietà disponibili per gli output, vedere Informazioni sulla struttura e la sintassi di Bicep.