Compartilhar via

Saídas no Bicep

  • 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ê tem um limite de 64 saídas em um arquivo Bicep. Para obter mais informações, confira 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 precisa 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 implantado no arquivo Bicep. O valor de saída obtém o nome de domínio totalmente qualificado para um endereço IP público.

output hostname string = publicIP.properties.dnsSettings.fqdn

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

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 da notação de ponto. Por exemplo, use ['property-name'] ao invés de .property-name.

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

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

O seguinte exemplo mostra como usar a expressão de tipo:

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

output out 'a' | 'b' = foo

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

Usar decoradores

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

Decorador Aplicar a Argumento Descrição
descrição all string Forneça descrições para a saída.
discriminator objeto string Use esse decorador para garantir que a subclasse correta seja identificada e gerenciada. Para obter mais informações, consulte Tipo de dados de união com marcas personalizadas.
maxLength matriz, cadeia de caracteres int Tamanho máximo de saídas do tipo matriz e cadeia de caracteres. O valor é inclusivo.
maxValue INT INT Valor máximo da saída do inteiro. Esse valor é inclusivo.
metadados all objeto Propriedades personalizadas a serem aplicadas à saída. Pode incluir uma propriedade de descrição que seja equivalente ao decorador da descrição.
minLength matriz, cadeia de caracteres int Tamanho mínimo de saídas do tipo matriz e cadeia de caracteres. O valor é inclusivo.
minValue INT INT Valor mínimo da saída do inteiro. Esse valor é inclusivo.
sealed objeto nenhum Eleve o BCP089 de aviso para erro quando um nome de propriedade de um tipo de dados definido pelo usuário for provavelmente um erro de digitação. Para obter mais informações, consulte Elevar nível de erro.

Os decoradores estão no namespace sys. Se você precisar diferenciar um decorador de outro item com o mesmo nome, preceda o decorador com sys. Por exemplo, se o arquivo Bicep incluir um parâmetro chamadodescription, você deverá 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

Descrição

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 por Markdown pode ser usado para o texto de descrição.

Discriminador

Consulte Tipo de dados de união marcados sob medida.

Restrições de inteiro

É possível definir valores mínimos e máximos para saídas do inteiro. É possível definir uma ou ambas as restrições.

var thisMonth = 3

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

Restrições de comprimento

É possível especificar comprimentos mínimos e máximos para saídas de cadeia de caracteres e matriz. É possível 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 dois destinos. Uma saída é usada para obter o nome da conta de armazenamento, que deverá ter de 3 a 24 caracteres. A outra é a matriz, que deverá ter entre 1 e 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 os valores personalizados. O objeto que você define para os metadados pode conter propriedades de qualquer nome e tipo.

Você pode usar esse decorador para controlar informações sobre a saída que não precisem ser adicionadas à 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 um decorador @metadata() com uma propriedade que entra em conflito com outro decorador, esse decorador sempre tem precedência sobre qualquer coisa no decorador @metadata(). Portanto, a propriedade conflitante no valor @metadata() é redundante e será substituída. Para obter mais informações, consulte Sem metadados conflitantes.

Selado

Consulte Elevar o 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 implementa condicionalmente um recurso. O exemplo a seguir mostra como retornar condicionalmente o 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 do 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, não é possível saber 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 expressão for.

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

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 for bem-sucedida, os valores de saída serão retornados automaticamente nos resultados da implantação.

Para obter os valores de saída do histórico de implantações, use a CLI do Azure ou um script do Azure PowerShell.

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

Classificação de objeto em saídas

No 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 items() do Bicep classifica os objetos na ordem alfabética. Em outros locais, a ordenação original pode ser preservada. Devido a esse não determinismo, evite fazer suposições sobre a ordem das chaves de objeto ao escrever códigos que interagem com parâmetros e saídas de implantações.

Próximas etapas