Bicep 中的输出

项目
09/30/2024

本文介绍如何在 Bicep 文件中定义输出值。需要从部署的资源返回值时，可以使用输出。一个 Bicep 文件中最多可以有 64 个输出。有关详细信息，请参阅模板限制。

定义输出

定义输出值的语法为：

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

输出可以与参数、变量、模块或资源同名。每个输出值必须解析为其中一种数据类型或用户定义的数据类型表达式。

下面的示例展示了如何从已部署的资源返回属性。在示例中，publicIP 是在 Bicep 文件中部署的公共 IP 地址的符号名称。输出值获取公共 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 编写，并放置在输出声明上方。下表显示了输出的可用修饰器。

修饰器	应用于	参数	说明
说明	all	string	提供输出的说明。
鉴别器	object	string	使用此修饰器来确保标识和管理正确的子类。有关详细信息，请参阅自定义标记的联合数据类型。
maxLength	数组、字符串	int	字符串和数组输出的最大长度。最大值包含在内。
maxValue	int	int	整数输出的最大值。最大值包含在内。
metadata	all	object	要应用于输出的自定义属性。可以包含与说明修饰器等效的说明属性。
minLength	数组、字符串	int	字符串和数组输出的最小长度。最小值包含在内。
minValue	int	int	整数输出的最小值。最小值包含在内。
sealed	object	无	如果 use-define 数据类型的属性名称可能存在拼写错误，则将 BCP089 从警告提升为错误。有关详细信息，请参阅提升错误级别。

修饰器位于 sys 命名空间中。如果需要将修饰器与具有相同名称的其他项区分开来，请在修饰器前面加上 sys。例如，如果 Bicep 文件包含名为 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('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>

通常，如果你有条件地部署了某个资源，则可以使用条件输出。下面的示例显示如何根据是否部署了新的资源 ID 有条件地返回公共 IP 地址的资源 ID。

若要在 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 脚本。

PowerShell
Azure CLI

(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 的结构和语法。

通过