共用方式為

建立 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 檔案、Azure Resource Manager JSON 範本、Bicep 模組和範本規格。 例如：

using './main.bicep'
...

using './azuredeploy.json'
...

using 'br/public:avm/res/storage/storage-account:0.9.0' 
...

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'

產生參數檔案

您可以使用 VS Code 或 Bicep CLI 建立兩種方式的參數檔案。 這兩個工具都可讓您使用 Bicep 檔案來產生參數檔案。 請參閱 產生 VS Code 方法的參數檔案 和 產生 Bicep CLI 方法的參數檔案 。

建置 Bicep 參數檔案

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

使用參數檔案部署 Bicep 檔案

Azure CLI

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

您可以使用 Bicep 參數檔案搭配 Azure CLI 2.53.0 版或更新版本和 Bicep CLI 0.22.X 版或更高版本來部署 Bicep 檔案。 using使用 Bicep 參數檔案內的 語句，在指定--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 版或更新版本。

參數優先順序

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

雖然目前不支援外部 Bicep 參數檔案，但可以將 URI 提供給檔案，以使用外部 JSON 參數檔案。 使用外部參數檔案時，請提供外部檔案中的所有參數值，因為您無法內嵌或從本機檔案傳遞其他值，而且會忽略所有內嵌參數。

參數名稱衝突

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

下一步