Выходные данные в Bicep

В этой статье описывается, как определять выходные значения в файле Bicep. Выходные данные используются, когда нужно возвратить данные из развернутых ресурсов. В Bicep-файле ограничено 64 выходными данными. Дополнительные сведения см. в разделе Ограничения шаблона.

Определение выходных данных

Для определения выходного значения используется следующий синтаксис:

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

Выходные данные могут иметь то же имя, что и параметр, переменная, модуль или ресурс. Каждое выходное значение должно разрешаться в одном из типов данных или определяемом пользователем выражении типа данных.

В примере ниже показано, как вернуть свойство из развернутого ресурса. В примере publicIP — это символическое имя общедоступного IP-адреса, развернутого в файле Bicep. В выходное значение записывается полное доменное имя для общедоступного IP-адреса.

output hostname string = publicIP.properties.dnsSettings.fqdn

В следующем примере показано, как вернуть выходные данные различных типов.

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

Если необходимо вывести свойство с дефисом в имени, вместо нотации с точками заключите имя в квадратные скобки. Например, используйте функцию ['property-name'] вместо .property-name.

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

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

В следующем примере показано, как использовать выражение типа:

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

output out 'a' | 'b' = foo

Дополнительные сведения см. в разделе "Определяемые пользователем типы данных".

Использование декораторов

Декораторы записываются в формате @expression и помещаются над объявлениями выходных данных. В следующей таблице показаны доступные декораторы для выходных данных.

Декораторы находятся в пространстве имен sys. Если вам важно, чтобы декоратор не путался с другими элементами с таким же именем, добавьте к нему префикс sys. Например, если в файле Bicep есть параметр с именем description, при использовании оформителя description необходимо добавить к имени пространство имен sys.

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

Description

Чтобы добавить объяснение, добавьте описание в выходные объявления. Например:

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

Текст в формате Markdown можно использовать для текста описания.

Дискриминатор

См . тип данных с пользовательским тегом объединения.

Ограничения для целочисленных параметров

Можно задать минимальные и максимальные значения для целых выходных данных. Вы можете установить один или оба этих предела.

var thisMonth = 3

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

Ограничения длины

Можно указать минимальную и максимальную длину выходных данных строк и массивов. Вы можете установить один или оба этих предела. Для строк длина указывает количество символов. Для массивов она указывает количество элементов.

В следующем примере объявляется два выходных данных. Один из выходных данных — это имя учетной записи хранения, которое должно содержать 3–24 символов. Другие выходные данные — это массив, который должен содержать из 1–5 элементов.

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

Метаданные

Если у вас есть настраиваемые свойства, которые необходимо применить к выходным данным, добавьте декоратор метаданных. В метаданных определите объект с настраиваемыми именами и значениями. Объект, заданный для метаданных, может содержать свойства с любым именем и типом.

Этот декоратор может использоваться для отслеживания сведений о выходных данных, которые не имеет смысла добавлять в описание.

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

Когда вы предоставляете декоратор с свойством @metadata() , который конфликтует с другим декоратором, этот декоратор всегда имеет приоритет над всем в декораторе @metadata() . Таким образом, конфликтующее свойство в значении @metadata() является избыточным и будет заменено. Дополнительные сведения см. в разделе "Нет конфликтующих метаданных".

Запечатанный

См. сведения об уровне ошибок с повышенными привилегиями.

Условный вывод

Если возвращаемое значение зависит от условия развертывания, используйте ? оператор.

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

Обычно условный вывод используется при условном развертывании ресурса. В примере ниже показано, как условно возвратить идентификатор ресурса для общедоступного IP-адреса в зависимости от того, был ли развернут новый адрес.

Чтобы задать в Bicep условный вывод, используйте оператор ?. В примере ниже в зависимости от условия возвращается либо URL-адрес конечной точки, либо пустая строка.

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

Динамическое число выходных значений

В некоторых сценариях при создании шаблона неизвестно число экземпляров значения, которое необходимо возвратить. Вы можете возвратить переменное число значений с помощью выражения for.

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

В следующем примере выполняется перебор массива.

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

Дополнительные сведения о циклах см. в статье Интерактивные циклы в Bicep.

Выходные значения модулей

Чтобы получить выходное значение из модуля, используйте нижеуказанный синтаксис.

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

В примере ниже показано, как задать IP-адрес в подсистеме балансировки нагрузки, получив значение из модуля.

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

Получение выходных значений

После успешного развертывания выходные значения автоматически возвращаются в его результатах.

Чтобы получить выходные значения из журнала развертывания, можно использовать Azure CLI или скрипт Azure PowerShell.

(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

Сортировка объектов в выходных данных

В JSON объект представляет собой неупорядоченную коллекцию из нуля или более пар "ключ-значение". Упорядочение может быть разным в зависимости от реализации. Например функция Bicep items() сортирует объекты в алфавитном порядке. В других местах можно сохранить исходное упорядочение. Из-за этого недетерминированного, избегайте принятия каких-либо предположений о упорядочении ключей объектов при написании кода, который взаимодействует с параметрами развертывания и выходными данными.

Следующие шаги

• Дополнительные сведения о доступных свойствах для выходных значений см. в статье Общие сведения о структуре и синтаксисе Bicep.