Freigeben über

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 benutzerdefinierten Datentypen in Bicep 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 für eine öffentliche IP-Adresse, die in der Bicep-Datei bereitgestellt wird. Der Ausgabewert ruft den vollqualifizierten Domänennamen für die öffentliche IP-Adresse ab:

output hostname string = publicIP.properties.dnsSettings.fqdn

Das nächste Beispiel zeigt, wie Ausgaben unterschiedlicher 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

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:

Dekorateur Anwenden auf Streitpunkt Beschreibung
Beschreibung alle Zeichenfolge Gibt Beschreibungen für die Ausgabe an.
Diskriminator Objekt Zeichenfolge Verwenden Sie dieses Decorator-Element, um sicherzustellen, dass die richtige Unterklasse identifiziert und verwaltet wird. Weitere Informationen finden Sie unter Benutzerdefinierter markierter Union-Datentyp.
MaxLength Array, Zeichenfolge INT Gibt die maximale Länge für Zeichenfolgen- und Arrayausgabe an; der Wert ist inklusiv.
maxValue INT INT Gibt den Maximalwert für die Ganzzahl an; der Wert ist inklusiv.
Metadaten alle Objekt Dies stellt benutzerdefinierte Eigenschaften bereit, die auf die Ausgabe angewendet werden sollen, und kann eine Beschreibungseigenschaft enthalten, die dem Beschreibungsdekorator entspricht.
minLength Array, Zeichenfolge INT Gibt die minimale Länge für Zeichenfolgen- und Arrayausgabe an; der Wert ist inklusiv.
minValue INT INT Gibt den Minimalwert für die Ganzzahl an; der Wert ist inklusiv.
versiegelt Objekt nichts Erhöhen Sie BCP089 von einer Warnung auf einen Fehler, wenn ein Eigenschaftenname eines benutzerdefinierten Datentyps wahrscheinlich einen Tippfehler enthält. Weitere Informationen finden Sie unter Erhöhen der Fehlerebene.
sicher String-Objekt nichts Markiert die Ausgabe als sicher. Der Wert für eine sichere Ausgabe wird nicht im Bereitstellungsverlauf gespeichert und nicht protokolliert. Weitere Informationen finden Sie unter Sichern von Zeichenfolgen und Objekten.

Dekoratoren sind im sys-Namespace. Wenn Sie diesen Decorator von einem anderen Element gleichen Namens unterscheiden müssen, stellen Sie dem Decorator sys voran. Wenn Ihre Bicep-Datei z. B. einen Parameter mit dem Namen description enthält, müssen Sie den sys-Namespace bei Verwendung der Beschreibungsdekoration hinzufügen.

@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 eine Beschreibung zu Ausgabedeklarationen 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

Weitere Informationen finden Sie unter Benutzerdefinierter markierter Union-Datentyp.

Ganzzahlige Einschränkungen

Sie können Mindest- und Höchstwerte für ganzzahlige Ausgaben und 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 aus 1 bis 5 Elementen bestehen 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. Wiederum ist die widersprüchliche Eigenschaft innerhalb des @metadata() Werts redundant und wird ersetzt. Weitere Informationen finden Sie unter Linter-Regel – keine widersprüchlichen Metadaten.

Versiegelt

Siehe Erhöhen der Fehlerebene.

Sichere Ergebnisse

Mit Bicep Version 0.35.1 und höher können Sie Zeichenfolgen- oder Objektausgabe als sicher markieren. Wenn eine Ausgabe mit @secure()versehen ist, behandelt Azure Resource Manager den Ausgabewert als vertraulich, verhindert, dass sie im Bereitstellungsverlauf, im Azure-Portal oder in Befehlszeilenausgaben protokolliert oder angezeigt wird.

@secure()
output demoPassword string

@secure()
output demoSecretObject object

Der @secure() Dekorateur ist nur für Ausgaben vom Typ Zeichenfolge oder Objekt gültig, da diese mit den SecureString - und secureObject-Typen in ARM-Vorlagen übereinstimmen. Um Arrays oder Zahlen sicher zu übergeben, schließen Sie sie in ein secureObject ein, oder serialisieren Sie sie als secureString.

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, die von einer Bedingung abhängt:

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 kennen Sie nicht die Anzahl der Instanzen eines Werts, die Sie beim Erstellen der Vorlage zurückgeben müssen. Sie können den for Ausdruck verwenden, um eine variable Anzahl von Werten zurückzugeben.

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 einen Wert aus einem Modul abrufen, um die IP-Adresse für einen Lastenausgleich festzulegen:

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

Wenn die Bereitstellung erfolgreich ist, zeigen die Ergebnisse der Bereitstellung automatisch die Ausgabewerte an.

Sie können das 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

Objektsortierung in Ausgaben

In JSON ist ein Objekt eine ungeordnete Auflistung von Null- oder mehr Schlüssel- oder Wertpaaren. Die Sortierung kann je nach Implementierung unterschiedlich sein. Beispielsweise sortiert die Bicep items() -Funktion die Objekte in alphabetischer Reihenfolge. An anderen Stellen können Sie die ursprüngliche Reihenfolge beibehalten. Vermeiden Sie aufgrund dieses Nichtdeterminismus beim Schreiben von Code, der mit Bereitstellungsparametern und Ausgaben interagiert, annahmen über die Anordnung von Objektschlüsseln.

Nächste Schritte

Informationen zu Eigenschaften, die für Ausgaben verfügbar sind, finden Sie unter Bicep-Dateistruktur und -syntax.