Bicep 中的參數

發行項
12/06/2024

本文說明如何在 Bicep 檔案中定義和使用參數。藉由提供不同的參數值，您可以針對不同的環境重複使用 Bicep 檔案。

Resource Manager 會在開始部署作業之前解析參數值。 Resource Manager 會在任何使用參數的地方，以已解析的值取代參數。

每個參數都必須設為其中一種資料類型。

Bicep 允許最多 256 個參數。如需詳細資訊，請參閱範本限制。

如需參數最佳做法，請參閱參數。

訓練資源

如果您比較想要透過逐步指導來了解參數，請參閱使用參數建立可重複使用的 Bicep 範本。

定義參數

每個參數都有名稱和資料類型。或者，您也可以提供參數的預設值。

@<decorator>(<argument>)
param <parameter-name> <parameter-data-type> = <default-value>

參數的名稱不可與相同範圍中的變數、資源、輸出或其他參數相同。

下列範例會顯示參數的基本宣告。

param demoString string
param demoInt int
param demoBool bool
param demoObject object
param demoArray array

.bicepparam 檔案 (機器翻譯) 中也會使用 param 關鍵字。在 .bicepparam 檔案中，您不需要指定資料類型，因為 Bicep 檔案中已經定義。

param <parameter-name> = <value>

如需詳細資訊，請參閱參數檔案 (機器翻譯)。

使用者定義型別運算式可用作 param 陳述式的類型子句。例如：

param storageAccountConfig {
  name: string
  sku: string
}

如需詳細資訊，請參閱使用者定義的資料類型 (機器翻譯)。

設定預設值

您可以指定參數的預設值。若部署期間未提供值，系統就會使用預設值。

param demoParam string = 'Contoso'

您可以使用具有預設值的運算式。運算式不能與其他參數屬性一起使用。您無法在參數區段中使用 reference 函式或任何 list 函式。這些函式會取得資源的執行階段狀態，而且在解析參數時無法在部署之前執行。

param location string = resourceGroup().location

您可以使用另一個參數以建立預設值。下列範本會從網站名稱建構主機方案名稱。

param siteName string = 'site${uniqueString(resourceGroup().id)}'
param hostingPlanName string = '${siteName}-plan'

output siteNameOutput string = siteName
output hostingPlanOutput string = hostingPlanName

不過，您無法將變數參考為預設值。

使用裝飾項目

參數會使用裝飾項目做為限制式或中繼資料。裝飾項目的格式為 @expression，並放置於參數的宣告上方。下表顯示參數的可用裝飾專案。

裝飾項目	套用到	Argument	描述
allowed	全部	陣列	使用此裝飾項目可確保使用者提供正確的值。此裝飾項目僅能在 `param` 陳述式上。若要宣告該屬性必須是 `type` 或 `output` 陳述式中一組預先定義的值之一，請使用等位型別語法。等位型別語法也可以在 `param` 陳述式使用。
description	全部	string	說明如何使用參數的文字。此描述內容會透過入口網站向使用者顯示。
discriminator	object	字串	使用此裝飾項目來確保識別和管理正確的子類別。如需詳細資訊，請參閱 [自訂標記的聯集資料類型]。
maxLength	陣列、字串	int	字串和陣列參數的最大長度。此值為內含。
maxValue	int	int	整數參數的最大值。此值為內含。
中繼資料	全部	object	要套用至參數的自訂屬性。可以包含相當於描述裝飾項目的描述屬性。
minLength	陣列、字串	int	字串和陣列參數的最小長度。此值為內含。
minValue	int	int	整數參數的最小值。此值為內含。
sealed	object	none	當使用者定義資料類型的屬性名稱可能有拼字錯誤時，將 BCP089 從警告提升為錯誤。如需詳細資訊，請參閱提升錯誤層級。
secure	字串、物件	none	將參數標示為安全。安全參數的值不會儲存在部署歷程記錄中，而且不會記錄。如需詳細資訊，請參閱安全字串和物件。

裝飾項目在 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

允許的值

您可以定義允許的參數值。您可以用陣列方式提供允許的值。如果傳入的參數值不是其中一個允許的值，則部署會在驗證期間失敗。

@allowed([
  'one'
  'two'
])
param demoEnum string

如果您為陣列參數定義允許的值，實際值可為允許值的任何子集。

描述

若要協助使用者了解所提供的值，請將描述新增至參數。當使用者透過入口網站部署範本時，系統會自動使用描述的文字作為該參數的提示。只有在文字提供的資訊比參數名稱所能推斷出的資訊更多時，才新增描述。

@description('Must be at least Standard_A3 to support 2 NICs.')
param virtualMachineSize string = 'Standard_DS1_v2'

Markdown 格式的文字可以用於描述文字：

@description('''
Storage account name restrictions:
- Storage account names must be between 3 and 24 characters in length and may contain numbers and lowercase letters only.
- Your storage account name must be unique within Azure. No two storage accounts can have the same name.
''')
@minLength(3)
@maxLength(24)
param storageAccountName string

若將游標停留在 VS Code 中的 storageAccountName 上，您會看到格式化的文字：

在 VSCode 中使用 Markdown 格式的文字

請確定文字遵循正確的 Markdown 格式設定，否則轉譯時可能無法正確顯示。

鑑別子

請參閱自定義標記聯集數據類型。

整數限制式

您可以設定整數參數的最小值和最大值。您可以設定一或兩個限制式。

@minValue(1)
@maxValue(12)
param month int

長度限制

您可以為字串和陣列參數指定最小和最大長度。您可以設定一或兩個限制式。若為字串，長度代表字元數。若為陣列，長度代表陣列中的項目數。

下列範例會宣告兩個參數。其中一個參數用來宣告儲存體帳戶的名稱必須具有 3-24 個字元。另一個參數則宣告陣列必須包含 1-5 個項目。

@minLength(3)
@maxLength(24)
param storageAccountName string

@minLength(1)
@maxLength(5)
param appNames array

中繼資料

如果您有想要套用至參數的自訂屬性，請新增中繼資料裝飾項目。在中繼資料內，使用自訂名稱和值定義物件。您為中繼資料定義的物件可以包含任何名稱和類型的屬性。

您可以使用此裝飾項目來追蹤參數的相關資訊，這些參數對於新增至描述並無意義。

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

若您提供的 @metadata() 裝飾項目含有的屬性與另一個裝飾項目衝突，該裝飾項目一律優先於 @metadata() 裝飾項目中任何元素，因此 @metadata() 值中的衝突屬性會變成多餘的，並受到取代。如需詳細資訊，請參閱沒有衝突的中繼資料 (機器翻譯)。

密封

請參閱提升錯誤層級。

安全參數

您可以將字串或物件參數標記為安全。安全參數的值不會儲存在部署歷程記錄中，而且不會記錄。

@secure()
param demoPassword string

@secure()
param demoSecretObject object

有數個與此裝飾項目相關的linter規則： Secure 參數預設值、巢狀部署中的安全參數、在參數中保護秘密。

使用參數

若要參照參數的值，請使用參數名稱。下列範例會針對金鑰保存庫名稱使用參數值。

param vaultName string = 'keyVault${uniqueString(resourceGroup().id)}'

resource keyvault 'Microsoft.KeyVault/vaults@2019-09-01' = {
  name: vaultName
  ...
}

使用對象作為參數

藉由將相關值以物件的方式傳遞，可以更輕鬆地進行組織。此方法也會減少範本中的參數數目。

下列範例顯示本身為物件的參數。預設值會顯示物件的預期屬性。在定義要部署的資源時，會用到這些屬性。

param vNetSettings object = {
  name: 'VNet1'
  location: 'eastus'
  addressPrefixes: [
    {
      name: 'firstPrefix'
      addressPrefix: '10.0.0.0/22'
    }
  ]
  subnets: [
    {
      name: 'firstSubnet'
      addressPrefix: '10.0.0.0/24'
    }
    {
      name: 'secondSubnet'
      addressPrefix: '10.0.1.0/24'
    }
  ]
}

resource vnet 'Microsoft.Network/virtualNetworks@2023-11-01' = {
  name: vNetSettings.name
  location: vNetSettings.location
  properties: {
    addressSpace: {
      addressPrefixes: [
        vNetSettings.addressPrefixes[0].addressPrefix
      ]
    }
    subnets: [
      {
        name: vNetSettings.subnets[0].name
        properties: {
          addressPrefix: vNetSettings.subnets[0].addressPrefix
        }
      }
      {
        name: vNetSettings.subnets[1].name
        properties: {
          addressPrefix: vNetSettings.subnets[1].addressPrefix
        }
      }
    ]
  }
}

下一步

若要了解參數的可用屬性，請參閱了解 Bicep 檔案的結構和語法。
若要瞭解如何以檔案的形式傳入參數值，請參閱建立 Bicep 參數檔案。
若要了解如何在部署時提供參數值，請參閱使用 Azure CLI 進行部署 (部分機器翻譯) 和使用 Azure PowerShell 進行部署 (部分機器翻譯)。

共用方式為