Bicep 中的參數

發行項
10/16/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	當 use-define 數據類型的屬性名稱可能是錯字時，將 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 進行部署 (部分機器翻譯)。

共用方式為