Partilhar via

Saídas no Bíceps

  • Artigo

Este artigo descreve como definir valores de saída em um arquivo Bicep. Você usa saídas quando precisa retornar valores dos recursos implantados. Você está limitado a 64 saídas em um arquivo Bicep. Para obter mais informações, consulte Limites de modelo.

Definir saídas

A sintaxe para definir um valor de saída é:

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

Uma saída pode ter o mesmo nome que um parâmetro, variável, módulo ou recurso. Cada valor de saída deve ser resolvido para um dos tipos de dados ou expressão de tipo de dados definida pelo usuário.

O exemplo a seguir mostra como retornar uma propriedade de um recurso implantado. No exemplo, publicIP é o nome simbólico de um endereço IP público que é implantado no arquivo Bicep. O valor de saída obtém o nome de domínio totalmente qualificado para o endereço IP público.

output hostname string = publicIP.properties.dnsSettings.fqdn

O próximo exemplo mostra como retornar saídas de diferentes tipos.

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 você precisar gerar uma propriedade que tenha um hífen no nome, use colchetes ao redor do nome em vez de notação de ponto. Por exemplo, use ['property-name'] em vez de .property-name.

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

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

O exemplo a seguir mostra como usar a expressão type:

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

output out 'a' | 'b' = foo

Para obter mais informações, consulte Tipos de dados definidos pelo usuário.

Use decoradores

Os decoradores são escritos no formato @expression e são colocados acima das declarações de saída. A tabela a seguir mostra os decoradores disponíveis para saídas.

Decorador Aplicar a Argumento Description
descrição todos string Forneça descrições para a saída.
discriminador objeto string Use este decorador para garantir que a subclasse correta seja identificada e gerenciada. Para obter mais informações, consulte Tipo de dados de união com tags personalizadas.
maxComprimento matriz, string número inteiro O comprimento máximo para saídas de cadeia de caracteres e matrizes. O valor é inclusivo.
maxValor número inteiro número inteiro O valor máximo para a saída inteira. Este valor é inclusivo.
metadados todos objeto Propriedades personalizadas a serem aplicadas à saída. Pode incluir uma propriedade description equivalente ao decorador de descrição.
minComprimento matriz, string número inteiro O comprimento mínimo para saídas de cadeia de caracteres e matrizes. O valor é inclusivo.
minValor número inteiro número inteiro O valor mínimo para a saída inteira. Este valor é inclusivo.
selado objeto nenhum Eleve o BCP089 de um aviso a um erro quando um nome de propriedade de um tipo de dados de definição de uso for provavelmente um erro de digitação. Para obter mais informações, consulte Elevar o nível de erro.

Os decoradores estão no namespace sys. Se você precisa diferenciar um decorador de outro item com o mesmo nome, prefacie o decorador com sys. Por exemplo, se o arquivo Bicep incluir um parâmetro chamado description, você deve adicionar o namespace sys ao usar o decorador de descrição .

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

Description

Para adicionar explicação, adicione uma descrição às declarações de saída. Por exemplo:

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

O texto formatado com marcação pode ser usado para o texto de descrição.

Discriminador

Consulte Tipo de dados de união com tags personalizadas.

Restrições de números inteiros

Você pode definir valores mínimos e máximos para saídas inteiras. Você pode definir uma ou ambas as restrições.

var thisMonth = 3

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

Restrições de comprimento

Você pode especificar comprimentos mínimos e máximos para saídas de cadeia de caracteres e matrizes. Você pode definir uma ou ambas as restrições. Para cadeias de caracteres, o comprimento indica o número de caracteres. Para matrizes, o comprimento indica o número de itens na matriz.

O exemplo a seguir declara duas saídas. Uma saída é para um nome de conta de armazenamento que deve ter de 3 a 24 caracteres. A outra saída é uma matriz que deve ter de 1 a 5 itens.

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

Metadados

Se você tiver propriedades personalizadas que deseja aplicar a uma saída, adicione um decorador de metadados. Dentro dos metadados, defina um objeto com os nomes e valores personalizados. O objeto definido para os metadados pode conter propriedades de qualquer nome e tipo.

Você pode usar esse decorador para rastrear informações sobre a saída que não fazem sentido adicionar à descrição.

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

Quando você fornece a um @metadata() decorador uma propriedade que entra em conflito com outro decorador, esse decorador sempre tem precedência sobre qualquer coisa no @metadata() decorador. Assim, a propriedade conflitante dentro do @metadata() valor é redundante e será substituída. Para obter mais informações, consulte Sem metadados conflitantes.

Selado

Consulte Elevar nível de erro.

Saída condicional

Quando o valor a ser retornado depender de uma condição na implantação, use o ? operador.

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

Normalmente, você usa uma saída condicional quando implanta condicionalmente um recurso. O exemplo a seguir mostra como retornar condicionalmente a ID do recurso para um endereço IP público com base na implantação de um novo.

Para especificar uma saída condicional no Bicep, use o ? operador . O exemplo a seguir retorna uma URL de ponto de extremidade ou uma cadeia de caracteres vazia, dependendo de uma condição.

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

Número dinâmico de saídas

Em alguns cenários, você não sabe o número de instâncias de um valor que precisa retornar ao criar o modelo. Você pode retornar um número variável de valores usando a for expressão.

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

O exemplo a seguir itera em uma matriz.

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

Para obter mais informações sobre loops, consulte Loops iterativos no Bicep.

Saídas de módulos

Para obter um valor de saída de um módulo, use a seguinte sintaxe:

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

O exemplo a seguir mostra como definir o endereço IP em um balanceador de carga recuperando um valor de um módulo.

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

Obter valores de saída

Quando a implantação é bem-sucedida, os valores de saída são retornados automaticamente nos resultados da implantação.

Para obter valores de saída do histórico de implantação, você pode usar a CLI do Azure ou o script do Azure PowerShell.

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

Classificação de objetos em saídas

Em JSON, um objeto é uma coleção não ordenada de zero ou mais pares chave/valor. A ordenação pode ser diferente dependendo das implementações. Por exemplo, a função Bicep items() classifica os objetos na ordem alfabética. Em outros lugares, o pedido original pode ser preservado. Devido a esse não-determinismo, evite fazer suposições sobre a ordenação de chaves de objeto ao escrever código, que interage com parâmetros de implantação e saídas.

Próximos passos