建立 Bicep 部署的參數檔案

Bicep 參數檔案可讓您在個別檔案中定義參數值，並將其傳遞給您的 main.bicep。 它們非常適合因訂閱、環境或地區而異的價值。

主要優點包括：

  • 在基礎設施即程式碼（IaC）部署間維持一致性，同時促進彈性。
  • 支援成本優化，例如在不改變核心基礎設施的情況下調整非生產環境的適當規模。
  • 透過將參數檔案保留在原始碼控制中，並將適當的檔案傳給每個部署階段，來實現簡化的 CI/CD 管線。

附註

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

您可以使用下列任一方法:

  • 原生的 Bicep 參數檔 (.bicepparam 副檔名)，或
  • 一個標準的 JSON 參數檔。

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

若要部署到多個環境，請建立多個參數檔案。 當您使用多個參數檔案時，請根據檔案的使用方式加上標籤。 例如，若要部署資源，請將 main.dev.bicepparam 標籤用於開發，以及將 main.prod.bicepparam 標籤用於生產。

你可以把 Bicep 的參數檔案編譯成 JSON 參數檔，然後用 Bicep 檔案來部署。 如需詳細資訊，請參閱 build-params。 你也可以把 JSON 參數檔反編譯成 Bicep 參數檔。 如需詳細資訊，請參閱 decompile-params。

Warning

參數檔案會將參數值儲存為純文字。 出於安全考量，對於像密碼這類敏感值，請不要使用這種方法。 如果你需要傳遞一個敏感值的參數，就把該值放在金鑰保險庫裡。 不要將敏感值新增至您的參數檔案，請使用 getSecret 函式以進行擷取。 如需詳細資訊，請參閱在 Bicep 部署期間使用 Azure Key Vault 傳遞祕密作為參數。

定義參數檔案

參數檔案使用下列格式：

using '<path>/<file-name>.bicep' | using none
extends '<path>/<file-name>.bicepparam' 

type <user-defined-data-type-name> = <type-expression>

var <variable-name> <data-type> = <variable-value>

import {<symbol_name> [as <alias_name>], ...} from '<bicep_file_name>'

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

若要判斷如何定義參數名稱和值，請開啟您的 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 檔案。 你可以將多個參數檔案關聯到一個 Bicep 檔案。 每個參數檔案通常透過 using 陳述式 來連結到特定的 Bicep 檔案。

如果你不想把參數檔連結到特定的Bicep檔，請使用 using none。 Bicep CLI 版本 0.31.0 及以上版本支援 using none 功能。

如需詳細資訊，請參閱使用陳述式。

該 extends 語句繼承自基礎 .bicepparam 檔案的參數，允許參數值在當前參數檔案中重複使用並選擇性覆蓋。 欲了解更多資訊，請參閱 可擴充參數檔案。

當你在Visual Studio Code輸入關鍵字 param，系統會提示你連結Bicep檔案中可用的參數及其描述。

可用參數提示的螢幕擷取畫面。

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

參數資料類型和描述的螢幕擷取畫面。

檢閱參數類型，因為參數檔案中的參數類型必須使用與 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 uses default value if not provided.

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

using 'main.bicep'

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

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

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 語法來宣告物件和陣列。

您可使用運算式作為參數值。 例如：

using './main.bicep'

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

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

using './main.bicep'

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

您可以定義和使用變數。 您必須使用 Bicep CLI 0.21.X 版或更新版本，才能在 .bicepparam 檔案中使用變數。 請參閱下列範例：

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
}

你可以定義使用者自訂的資料型態。 例如：

using './main.bicep'

// Define a reusable type for tags with optional properties
type TagValues = {
  environment: 'dev' | 'test' | 'production'
  project: string
}

var tagsExample TagValues = {
  environment: 'dev'
  project: 'bicep-sample'
}

param tags = tagsExample

你也可以從 Bicep 檔案匯入變數、使用者自訂資料型態，以及使用者自訂函式。 欲了解更多資訊，請參閱 匯入。

可擴充參數檔案

詳情請參見 Extend 參數檔案。

產生與建置參數檔案

您可以使用 Visual Studio Code 或 Bicep CLI 來建立參數檔案。 這兩個工具都可讓您使用 Bicep 檔案來產生參數檔案。 請參閱產生參數檔案以了解 Visual Studio Code 方法，以及參閱參數檔案以了解 Bicep CLI 方法。

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

使用參數檔案部署 Bicep 檔案

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

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

以下範例展示了使用 Azure CLI 外部 JSON 參數檔的範例：

az deployment group create \
  --resource-group my-rg \
  --template-file main.bicep \
  --parameters https://storageaccount.blob.core.windows.net/templates/main.parameters.json

Azure CLI

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

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

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

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

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

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

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

相關內容

  • 上次更新時間：