Ausgaben in Bicep

Dieser Artikel beschreibt, wie Sie in einer Bicep-Datei Ausgabewerte definieren. Sie verwenden Ausgaben, wenn Werte von den bereitgestellten Ressourcen zurückgegeben werden müssen. Die Anzahl der Ausgaben in einer Bicep-Datei ist auf 64 beschränkt. Weitere Informationen finden Sie unter Vorlagengrenzwerte.

Definieren der Ausgaben

Die Syntax zum Definieren eines Ausgabewerts lautet:

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

Eine Ausgabe darf nicht denselben Namen wie ein Parameter, eine Variable, ein Modul oder eine Ressource haben. Jeder Ausgabewert muss zu einem der Datentypen oder in einen benutzerdefinierten Datentypausdruck aufgelöst werden.

Im folgenden Beispiel wird gezeigt, wie Sie eine Eigenschaft von einer bereitgestellten Ressource zurückgeben lassen. Im Beispiel ist publicIP der symbolische Name einer öffentlichen IP-Adresse, die in der Bicep-Datei bereitgestellt wird. Der Ausgabewert erhält den vollqualifizierten Domänennamen für die öffentliche IP-Adresse.

output hostname string = publicIP.properties.dnsSettings.fqdn

Im nächsten Beispiel wird veranschaulicht, wie Ausgaben verschiedener Typen zurückgegeben werden.

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

Wenn Sie eine Eigenschaft ausgeben müssen, die einen Bindestrich im Namen aufweist, setzen Sie den Namen in eckige Klammern, anstatt die Punktnotation zu verwenden. Verwenden Sie z. B. ['property-name'] statt .property-name.

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

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

Das folgende Beispiel zeigt, wie Typausdrücke verwendet wird:

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

output out 'a' | 'b' = foo

Weitere Informationen finden Sie unter Benutzerdefinierte Datentypen.

Verwenden von Decorator-Elementen

Decorator-Elemente werden im Format @expression geschrieben und oberhalb von Ausgabedeklarationen platziert. In der folgenden Tabelle werden die für die Ausgabe verfügbaren Decorator-Elemente gezeigt.

Decorators befinden sich im sys-Namespace. Wenn Sie diesen Decorator von einem anderen Element gleichen Namens unterscheiden müssen, stellen Sie dem Decorator sys voran. Zum Beispiel, wenn Ihre Bicep Datei einen Parameter mit dem Namen description enthält, müssen Sie den sys Namespace hinzufügen, wenn Sie den description Dekorator verwenden.

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

Beschreibung

Um eine Erklärung hinzuzufügen, fügen Sie Ausgabedeklarationen eine Beschreibung hinzu. Zum Beispiel:

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

Mit Markdown formatierter Text kann für den Beschreibungstext verwendet werden.

Diskriminator

Siehe Benutzerdefinierter markierter Union-Datentyp.

Ganzzahlige Einschränkungen

Sie können die minimalen und maximalen Werte für die ganzzahlige Ausgabe festlegen. Sie können eine oder beide Einschränkungen festlegen.

var thisMonth = 3

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

Längenbeschränkungen

Sie können die minimale und maximale Länge für die Zeichenfolge- und Array-Ausgabe angeben. Sie können eine oder beide Einschränkungen festlegen. Bei Zeichenfolgen gibt die Länge die Anzahl der Zeichen an. Bei Arrays gibt die Länge die Anzahl der Elemente im Array an.

Im folgenden Beispiel werden zwei Ausgaben deklariert. Eine Ausgabe bezieht sich auf den Namen eines Speicherkontos, der 3–24 Zeichen enthalten muss. Die andere Ausgabe ist ein Array, das 1–5 Elemente aufweisen muss.

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

Metadaten

Wenn Sie benutzerdefinierte Eigenschaften haben, die Sie auf eine Ausgabe anwenden möchten, fügen Sie einen Metadaten-Decorator hinzu. Definieren Sie innerhalb der Metadaten ein Objekt mit den benutzerdefinierten Namen und Werten. Das Objekt, das Sie für die Metadaten definieren, kann Eigenschaften eines beliebigen Namens und Typs enthalten.

Sie können diesen Decorator verwenden, um Informationen über die Ausgabe nachzuverfolgen, bei denen es nicht sinnvoll wäre, sie in die Beschreibung aufzunehmen.

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

Wenn Sie ein @metadata()-Decorator-Element mit einer Eigenschaft bereitstellen, die mit einem anderen Decorator-Element in Konflikt steht, hat dieses Decorator-Element immer Vorrang vor allen Elementen im @metadata()-Decorator-Element. Daher ist die in Konflikt stehende Eigenschaft innerhalb des Werts @metadata() redundant und wird ersetzt. Weitere Informationen finden Sie unter Keine widersprüchlichen Metadaten.

Versiegelt

Siehe Erhöhen der Fehlerebene.

Bedingte Ausgabe

Wenn der zurückzugebende Wert von einer Bedingung in der Bereitstellung abhängt, verwenden Sie den ?-Operator.

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

In der Regel verwenden Sie eine bedingte Ausgabe, wenn Sie eine Ressource bedingt bereitgestellt haben. Das folgende Beispiel zeigt, wie die Ressourcen-ID für eine öffentliche IP-Adresse abhängig davon zurückgegeben wird, ob eine neue Ressourcen-ID bereitgestellt wurde.

Um eine bedingte Ausgabe in Bicep anzugeben, verwenden Sie den ?-Operator. Im folgenden Beispiel wird entweder eine Endpunkt-URL oder eine leere Zeichenfolge zurückgegeben, abhängig von einer Bedingung.

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

Dynamische Anzahl von Ausgaben

In einigen Szenarien wissen Sie nicht, wie viele Instanzen eines Werts beim Erstellen der Vorlage zurückgegeben werden müssen. Sie können eine variable Anzahl von Werten zurückgeben, indem Sie den for-Ausdruck verwenden.

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

Im folgenden Beispiel wird ein Array durchlaufen.

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

Weitere Informationen zu Schleifen finden Sie unter Iterative Schleifen in Bicep.

Ausgaben von Modulen

Um von einem Modul einen Ausgabewert zu erhalten, verwenden Sie die folgende Syntax:

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

Das folgende Beispiel zeigt, wie Sie die IP-Adresse für einen Lastenausgleich festlegen, indem Sie einen Wert aus einem Modul abrufen.

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

Abrufen von Ausgabewerten

Bei erfolgreicher Bereitstellung werden die Ausgabewerte automatisch in den Ergebnissen der Bereitstellung zurückgegeben.

Sie können ein Azure CLI- oder Azure PowerShell-Skript verwenden, um Ausgabewerte aus dem Bereitstellungsverlauf abzurufen.

(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

Objektsortierung in Ausgaben

In JSON ist ein Objekt eine nicht geordnete Auflistung von null oder mehr Schlüssel-Wert-Paaren. Die Reihenfolge kann je nach Implementierung unterschiedlich sein. Die Items()-Funktion von Bicep sortiert die Objekte beispielsweise in alphabetischer Reihenfolge. An anderen Stellen kann die ursprüngliche Reihenfolge beibehalten werden. Aufgrund dieses Nicht-Determinismus sollten Sie beim Schreiben von Code, der mit den Parametern und Ausgaben der Bereitstellung interagiert, keine Annahmen über die Reihenfolge der Objektschlüssel anstellen.

Nächste Schritte

• Weitere Informationen zu den verfügbaren Eigenschaften für Ausgaben finden Sie unter Grundlegendes zur Struktur und Syntax von Bicep.