Bicep 中的输出

2025-05-10

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

定义输出

定义输出值的语法为：

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

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

下面的示例展示了如何从已部署的资源返回属性。在此示例中， 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 编写，并放置在输出声明上方。下表显示了输出结果的可用修饰器：

修饰器	应用于	参数	说明
说明	全部	字符串	这提供了有关输出的说明。
鉴别器	物体	字符串	使用此修饰器来确保标识和管理正确的子类。有关详细信息，请参阅自定义标记的联合数据类型。
maxLength	数组、字符串	整数 (int)	这为字符串和数组输出提供最大长度，并且该值是非独占的。
maxValue	整数 (int)	整数 (int)	这将提供整数输出的最大值，并且该值是包含在内的。
元数据	全部	物体	这提供了要应用于输出的自定义属性，并可以包含与描述修饰器等效的描述属性。
minLength	数组、字符串	整数 (int)	这为字符串和数组输出提供最小长度，并且该值是非独占的。
minValue	整数 (int)	整数 (int)	这为整数输出提供最小值，并且该值是包含在内的。
密封	物体	无	如果 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() 冲突属性是冗余的，将被替换。有关详细信息，请参阅 Linter 规则 - 无冲突元数据。

已密封

请参阅提升错误级别。

安全输出

使用 Bicep 版本 0.35.1 及更高版本，可以将字符串或对象输出标记为安全。当输出被@secure()修饰时，Azure 资源管理器会将输出值视为敏感信息，从而阻止在部署历史记录、Azure门户或命令行输出中记录或显示这些值。

@secure()
output demoPassword string

@secure()
output demoSecretObject object

@secure()修饰器仅适用于字符串或对象的输出，因为这些输出与 ARM 模板中的 secureString 和 secureObject 类型保持一致。若要安全地传递数组或数字，请将它们包装在 secureObject 中，或将它们序列化为 secureString。

条件输出

当要返回的值取决于部署中的条件时，请使用 ? 运算符。

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 脚本从部署历史记录中获取输出值。

Azure 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 文件结构和语法。

通过