Share via

建立 Bicep 部署的參數檔案

  • 發行項

相對於在指令碼中將參數做為內嵌值傳遞，您可以使用具有 .bicepparam 檔案副檔名的 Bicep 參數檔案或包含參數值的 JSON 參數檔案。 本文說明如何建立參數檔案。

注意

Bicep 參數檔案僅支援 Bicep CLI 0.18.4 版或更新版本、Azure CLI 2.47.0 版或更新版本，以及 Azure PowerShell 9.7.1 版或更新版本。

單一 Bicep 檔案可以有多個相關聯的 Bicep 參數檔案。 不過，每個 Bicep 參數檔案都適用於一個特定的 Bicep 檔案。 此關聯性是使用 Bicep 參數檔案內的 using 陳述式建立。

您可以將 Bicep 參數檔案編譯為 JSON 參數檔案，以使用 Bicep 檔案進行部署。 請參閱 build-params。 您也可以將 JSON 參數檔案反向組譯為 Bicep 參數檔案。 請參閱 decompile-params。

參數檔案

參數檔案使用下列格式：

using '<path>/<file-name>.bicep'

param <first-parameter-name> = <first-value>
param <second-parameter-name> = <second-value>

您可以使用 using 語句 搭配 Bicep 檔案、ARM JSON 範本、Bicep 模組和範本規格。 例如：

using './main.bicep'
...

using './azuredeploy.json'
...

using 'br/public:storage/storage-account:3.0.1'
...

using 'br:myacr.azurecr.io/bicep/modules/storage:v1'
...

using 'ts:00000000-0000-0000-0000-000000000000/myResourceGroup/storageSpec:1.0'
...

如需詳細資訊，請參閱 using 語句。

您可以使用具有預設值的運算式。 例如：

using 'main.bicep'

param storageName = toLower('MyStorageAccount')
param intValue = 2 + 2

您可以將環境變數做為參數值參考。 例如：

using './main.bicep'

param intFromEnvironmentVariables = int(readEnvironmentVariable('intEnvVariableName'))

您可以定義和使用變數。 使用 .bicepparam 檔案中的變數需要 Bicep CLI 0.21.X 版或更高版本。 以下列出一些範例：

using './main.bicep'

var storagePrefix = 'myStorage'
param primaryStorageName = '${storagePrefix}Primary'
param secondaryStorageName = '${storagePrefix}Secondary'

using './main.bicep'

var testSettings = {
  instanceSize: 'Small'
  instanceCount: 1
}

var prodSettings = {
  instanceSize: 'Large'
  instanceCount: 4
}

param environmentSettings = {
  test: testSettings
  prod: prodSettings
}

值得注意的是，參數檔案會將參數值儲存為純文字。 基於安全性考量，不建議將此方法用於敏感值，例如密碼。 如果您必須傳遞具敏感性值的參數，請在金鑰保存庫中保留值。 不要將敏感值新增至您的參數檔案，請使用 getSecret 函式以進行擷取。 如需詳細資訊，請參閱在 Bicep 部署期間使用 Azure Key Vault 以傳遞安全的參數值。

參數類型格式

下列範例顯示不同參數類型的格式：字串、整數、布林值、陣列和物件。

using './main.bicep'

param exampleString = 'test string'
param exampleInt = 2 + 2
param exampleBool = true
param exampleArray = [
  'value 1'
  'value 2'
]
param exampleObject = {
  property1: 'value 1'
  property2: 'value 2'
}

使用 Bicep 語法來宣告物件和陣列。

File name

Bicep 參數檔案的檔案副檔名為 .bicepparam。

若要部署到不同的環境，您可以建立一個以上的參數檔案。 為參數檔案命名時，請識別其使用方式，例如開發和生產。 例如，使用 main.dev.bicepparam 和 main.prod.bicepparam 來部署資源。

定義參數值

若要判斷如何定義參數名稱和值，請開啟您的 Bicep 檔案。 查看 Bicep 檔案的參數區段。 下列範例顯示名為 main.bicep 的 Bicep 檔案中的參數。

@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

在參數檔案中，要注意的第一個詳細資料是每個參數的名稱。 參數檔案中的參數名稱必須符合 Bicep 檔案中的參數名稱。

using 'main.bicep'

param storagePrefix
param storageAccountType

using 陳述式會將 Bicep 參數檔案繫結至 Bicep 檔案。 如需詳細資訊，請參閱使用陳述式。

在 Visual Studio Code 中輸入關鍵詞 param 之後，它會提示您連結的 Bicep 檔案中可用的參數及其描述：

可用參數提示的螢幕快照。

將滑鼠停留在參數名稱上方時，您可以看到參數資料類型和描述。

參數數據類型和描述的螢幕快照。

注意參數類型。 參數檔案中的參數類型必須使用與 Bicep 檔案相同的類型。 在此範例中，這兩個參數類型都是字串。

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

檢查 Bicep 檔案中是否有具有預設值的參數。 如果參數具有預設值，您可在參數檔案中提供值，但並非必要。 參數檔案值會覆寫 Bicep 檔案的預設值。

using 'main.bicep'

param storagePrefix = '' // This value must be provided.
param storageAccountType = '' // This value is optional. Bicep will use default value if not provided.

檢查 Bicep 的允許值和任何限制，例如長度上限。 這些值會指定您可以為參數提供的值範圍。 在此範例中，storagePrefix 最多可以有 11 個字元，且 storageAccountType 必須指定允許值。

using 'main.bicep'

param storagePrefix = 'storage'
param storageAccountType = 'Standard_ZRS'

產生參數檔案

若要產生參數檔案，您有兩個選項：透過 Visual Studio Code 或使用 Bicep CLI。 這兩種方法都可讓您從 Bicep 檔案衍生參數檔案。 在 Visual Studio Code 中，請參閱產生參數檔案。 在 Bicep CLI 中，請參閱產生參數檔案。

建置 Bicep 參數檔案

在 Bicep CLI 中，您可以將 Bicep 參數檔案建置為 JSON 參數檔案。 如需詳細資訊，請參閱 建置參數檔案。

使用參數檔案部署 Bicep 檔案

Azure CLI

在 Azure CLI 中，您可以使用 Bicep 檔案部署來傳遞參數檔案。

透過 Azure CLI 2.53.0 版或更新版本，以及 Bicep CLI 0.22.X 版或更高版本，您可以使用 Bicep 參數檔案來部署 Bicep 檔案。 使用 Bicep 參數檔案內的 using 陳述式，在指定 --parameters 參數的 Bicep 參數檔案時，就不需要提供 --template-file 參數。

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam

您可以在相同的部署作業中使用內嵌參數和位置參數檔案。 例如：

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam \
  --parameters storageAccountType=Standard_LRS

如需詳細資訊，請參閱使用 Bicep 和 Azure CLI 部署資源。

Azure PowerShell

從 Azure PowerShell，使用 TemplateParameterFile 參數傳遞本機參數檔案。

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.bicepparam

您可以在相同的部署作業中使用內嵌參數和位置參數檔案。 例如：

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.bicepparam `
  -storageAccountType Standard_LRS

如需詳細資訊，請參閱使用 Bicep 和 Azure PowerShell 部署資源。 若要部署 .bicep 檔案，您需要 Azure PowerShell 5.6.0 版或更新版本。

參數優先順序

您可以在相同的部署作業中使用內嵌參數和本機參數檔案。 例如，您可以在部署期間指定本機參數檔案中的某些值，並新增其他內嵌值。 如果您同時為本機參數檔案和內嵌中的參數提供值，內嵌值的優先順序較高。

藉由提供檔案的 URI，就可以使用外部 JSON 參數檔案。 目前不支援外部 Bicep 參數檔案。 使用外部參數檔案時，您無法傳遞內嵌或本機檔案的其他值。 所有內嵌參數均會遭到忽略。 請提供外部檔案中的所有參數值。

參數名稱衝突

如果您的 Bicep 檔案包含的參數名稱與 PowerShell 命令中的其中一個參數一樣，PowerShell 會以加上後置 FromTemplate 的方式呈現您 Bicep 檔案中的參數。 例如，Bicep 檔案中名為 ResourceGroupName 的參數會與 New-AzResourceGroupDeployment Cmdlet 中的 ResourceGroupName 參數發生衝突。 系統會提示您提供 ResourceGroupNameFromTemplate 的值。 若要避免此混淆情形，請使用未用於部署命令的參數名稱。

下一步