Bicep 中的輸出

發行項
11/09/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 撰寫，並置於輸出宣告上方。下表顯示輸出的可用裝飾專案。

裝飾項目	套用到	Argument	描述
description	全部	字串	提供輸出的描述。
discriminator	object	字串	使用此裝飾項目來確保識別和管理正確的子類別。如需詳細資訊，請參閱 [自訂標記的聯集資料類型]。
maxLength	陣列、字串	int	字串和數位輸出的最大長度。此值為內含。
maxValue	int	int	整數輸出的最大值。此值為內含。
中繼資料	全部	object	要套用至輸出的自訂屬性。可以包含相當於描述裝飾項目的描述屬性。
minLength	陣列、字串	int	字串和數位輸出的最小長度。此值為內含。
minValue	int	int	整數輸出的最小值。此值為內含。
sealed	object	none	當使用者定義資料類型的屬性名稱可能有拼字錯誤時，將 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>

一般來說，當您有條件地部署資源時，會使用條件式輸出。下列範例示範如何根據是否部署新的 IP 位址，有條件地傳回公用 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 指令碼。

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 的結構和語法。

共用方式為