Saídas no Bíceps

Este artigo descreve como definir valores de saída em um arquivo Bicep. Você utiliza resultados 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 tipos de dados definidos pelo usuário no Bicep.

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

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:

Os decoradores estão no sys namespace. 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ê deverá adicionar o sys namespace 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

Descrição

Para adicionar uma 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 : ''

Texto formatado em Markdown pode ser usado para o texto de descrição.

Discriminador

Consulte Tipo de dados de união com marcação personalizada.

Restrições de números inteiros

Você pode definir valores mínimos e máximos para saídas inteiras e 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 das saídas é um nome de conta de armazenamento que deve ter entre 3 e 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 este decorador para rastrear informações sobre a saída que não faz sentido acrescentar à 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 se fornece a um @metadata() decorador uma propriedade que conflita com outro decorador, esse decorador sempre tem precedência sobre qualquer coisa no decorador @metadata(). Por sua vez, a propriedade conflitante dentro do @metadata() valor é redundante e será substituída. Para obter mais informações, consulte Regra de Linter - sem metadados conflitantes.

Selado

Consulte Elevar nível de erro.

Saídas seguras

Com o Bicep versão 0.35.1 e posterior, você pode marcar saídas de cadeia de caracteres ou objetos como seguras. Quando uma saída é decorada com @secure(), o Azure Resource Manager trata o valor de saída como confidencial, impedindo que seja registado ou mostrado no histórico de implementação, no portal do Azure ou nos resultados da linha de comando.

@secure()
output demoPassword string

@secure()
output demoSecretObject object

O @secure() decorador é válido apenas para saídas do tipo string ou objeto, pois elas se alinham com os tipos secureString e secureObject em modelos ARM. Para passar matrizes ou números com segurança, envolva-os em um secureObject ou serialize-os como um secureString.

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, baseado em se um novo foi implantado.

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 que depende 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 usar a for expressão para retornar um número variável de valores.

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.

Resultados dos 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 recuperar um valor de um módulo para definir o endereço IP em um balanceador de carga:

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 resultados da implantação mostram automaticamente os valores de saída.

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

(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

Classificação de objetos em saídas

Em JSON, um objeto é uma coleção não ordenada de zero ou mais pares de chaves ou valores. A ordenação pode ser diferente dependendo das implementações. Por exemplo, a função Bicep items() classifica os objetos em ordem alfabética. Em outros lugares, você pode preservar o pedido original. 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 e saídas de implantação.

Próximos passos

Para saber mais sobre as propriedades disponíveis para saídas, consulte Estrutura e sintaxe do arquivo Bicep.