了解參數

8 分鐘

有了「參數」之後，您就能在部署時，將資訊提供給 Bicep 範本。您可以在範本中宣告參數，讓 Bicep 範本變得有彈性，而且可以重複使用。

裝飾項目可讓您將限制式與中繼資料附加至參數，藉此協助您範本的使用者，了解其必須提供哪些資訊。

在此單元中，您將學習參數與裝飾項目。

宣告參數

在 Bicep 範本中，您可以使用 param 關鍵字宣告參數。雖然將這些宣告置於檔案最上方比較理想，但是為了讓您的 Bicep 程式碼更易於閱讀，也可以將其置於範本檔案中的任何位置。

以下是宣告參數的方式：

param environmentName string

讓我們看看每一部分的功能：

param 指出您要宣告參數的 Bicep。
environmentName 代表參數的名稱。雖然參數名稱沒有限制，但建議您使用範本使用者易於了解的名稱。在相同的範本中，您也可以使用該名稱代表參數。參數名稱必須是唯一的。在同一個 Bicep 檔案中，參數名稱與變數或資源不得相同。

提示

針對參數宣告使用最佳做法命名慣例。好的命名慣例可讓您的範本更易於閱讀及理解。請務必使用清楚的描述性名稱，並且採用一致的命名策略。
string 代表參數的類型。

提示

請仔細思考您範本所使用的參數。請盡量為會隨不同部署而改變的設定使用參數。不會隨不同部署而改變的設定，可以使用變數與硬式編碼值。

新增預設值

您可以為範本中的參數指派預設值。若指派預設值，參數就變得有選擇性。若部署範本時，未指定參數的值，將會指派預設值。

以下是新增預設值的方式：

param environmentName string = 'dev'

參數 environmentName 獲指派 dev 的預設值。

您可以使用運算式作為預設值。以下是名為 location 的字串參數範例，其預設值設定為目前資源群組的位置：

param location string = resourceGroup().location

提示

請留意您使用的預設值。請確定使用者在使用預設值部署 Bicep 檔案時安全無虞。例如，您可以考慮使用便宜的定價層與 SKU，讓部署範本的使用者用於測試環境，但不會產生大筆不必要的花費。

了解參數類型

宣告參數時，必須告訴 Bicep 參數所要包含的資訊類型。 Bicep 將會確定指派給參數的值與參數類型相容。

Bicep 中的參數可以是下列其中一種類型：

string，可讓您輸入任意文字。
int，可讓您輸入數字。
bool：代表布林值 (true 或 false) 值。
object 與 array，代表結構化資料與清單。

物件

您可以使用物件參數，將結構化資料合併到同一個位置。物件可以有多種不同類型的屬性。您可以在資源定義中、變數中，或在 Bicep 檔案的運算式中使用物件。以下是物件的範例：

param appServicePlanSku object = {
  name: 'F1'
  tier: 'Free'
  capacity: 1
}

此參數是具有兩個字串屬性 (name 與 tier) 與一個整數屬性 (capacity) 的物件。請注意，每個屬性都自成一行。

當您參考範本中的參數時，可以使用緊接在屬性名稱之後的點 (如下列範例所示)，選取物件的個別屬性：

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  sku: {
    name: appServicePlanSku.name
    tier: appServicePlanSku.tier
    capacity: appServicePlanSku.capacity
  }
}

重要

請注意，您不會在物件中指定每個屬性的類型。但當您使用屬性的值時，其類型必須符合預期的值。在上述範例中，App Service 方案 SKU 的名稱與階層，都必須是字串。

另一個使用物件參數的範例，是指定資源標記。您可以將自訂標記中繼資料附加至您部署的資源，藉此識別資源的重要資訊。

標記可以用於追蹤哪些小組擁有資源，或資源屬於生產或非生產環境等狀況。一般而言，您會為每個環境使用不同的標記，但您想要對範本中的所有資源，重複使用相同的標記值。基於這個理由，就很適合對物件參數使用資源標籤，如下列範例所示：

param resourceTags object = {
  EnvironmentName: 'Test'
  CostCenter: '1000100'
  Team: 'Human Resources'
}

當您在 Bicep 檔案中定義資源時，可以在定義 tags 屬性時，隨時重複使用該資源：

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  tags: resourceTags
  sku: {
    name: 'S1'
  }
}

resource appServiceApp 'Microsoft.Web/sites@' = {
  name: appServiceAppName
  location: location
  tags: resourceTags
  kind: 'app'
  properties: {
    serverFarmId: appServicePlan.id
  }
}

陣列

陣列是項目的清單。例如，您可以使用字串值陣列，宣告 Azure 監視器動作群組的電子郵件地址清單。也可以使用物件陣列，表示虛擬網路的子網路清單。

注意

您無法指定陣列必須包含的個別項目類型。例如，您無法指定陣列必須包含字串。

我們來看一個範例。 Azure Cosmos DB 可讓您建立跨多個區域的資料庫帳戶，並自動為您處理資料複寫。當您部署新的資料庫帳戶時，需要指定帳戶部署所在的 Azure 區域清單。對於不同的環境，您通常需要使用不同的位置清單。例如，為了節省測試環境的經費，您可能只會使用一或兩個位置。但是在生產環境中，您可能會使用幾個位置。

您可以建立陣列參數來指定位置清單：

param cosmosDBAccountLocations array = [
  {
    locationName: 'australiaeast'
  }
  {
    locationName: 'southcentralus'
  }
  {
    locationName: 'westeurope'
  }
]

提示

上述範例包含一個物件陣列。每個物件都有一個 locationName 屬性，也是 Azure Cosmos DB 需要的內容。當您使用 Visual Studio Code 中的資源定義時，可以從輸入資源屬性開始，從 Bicep 工具取得 IntelliSense。您可以使用此方法建立一些範例值。當您設定完成之後，請將該 Bicep 程式碼區段移至參數。此法可以將硬式編碼屬性，取代成可以在每次部署時變更的參數，同時還能確保資源的設定正確。

現在，當您宣告 Azure Cosmos DB 資源時，已可參考陣列參數：

resource account 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  name: accountName
  location: location
  properties: {
    locations: cosmosDBAccountLocations
  }
}

只要變更參數的值，就能為開發環境使用不同的參數值。不久之後，您將學習如何不修改原始範本，就能提供不同的參數值。

指定允許值的清單

有時您會需要確保參數使用特定的值。例如，您的小組可能會決定使用進階 v3 SKU 來部署生產 App Service 方案。若要強制執行此規則，可以使用 @allowed 參數裝飾項目。 參數裝飾項目是提供參數值所需相關 Bicep 資訊的一種方法。以下示範如何限制名為 appServicePlanSkuName 的字串參數，達到只能指派幾個特定值的目的：

@allowed([
  'P1v3'
  'P2v3'
  'P3v3'
])
param appServicePlanSkuName string

提示

盡量不使用 @allowed 裝飾項目。過度使用此裝飾項目，又未及時更新此清單，可能會造成有效的部署無法運作。上述範例僅限於在生產環境中執行進階 v3 SKU。若您需要使用相同的範本，部署一些較便宜的非生產環境，允許值的清單可能會造成您無法使用其他您必須使用的 SKU。

限制參數長度與值

當您使用字串參數時，經常需要限制字串的長度。讓我們看看 Azure 資源命名的範例。所有 Azure 資源類型的名稱長度都有限制。建議指定用以控制命名之參數的字元長度上下限，可避免之後部署時發生錯誤。您可以對參數的字元長度上下限，使用 @minLength 與 @maxLength 裝飾項目。

下列範例會宣告名為 storageAccountName 的字串參數，其長度只能介於 5 到 24 個字元之間：

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

此參數包括兩個裝飾項目。您可以為參數套用多個裝飾項目，方法是將裝飾項目置於參數各自所在的行上即可。

注意

您也可以將 @minLength 與 @maxLength 裝飾項目套用至陣列參數，以控制陣列中允許的項目數。

當您使用數值參數時，可能會需要特定範圍內的值。例如，您的玩具公司可能會決定，每當有人部署 App Service 方案時，也必須部署至少一個執行個體，但一個方案不得超過 10 個執行個體。為了滿足這些要求，您可以使用 @minValue 與 @maxValue 裝飾項目，指定允許值的上限及下限。下列範例宣告整數參數 appServicePlanInstanceCount，其值只能介於 1 到 10 (含)：

@minValue(1)
@maxValue(10)
param appServicePlanInstanceCount int

為參數新增描述

參數是讓範本可以供人重複使用的絕佳方式。當他們使用您的範本時，必須了解每個參數的用途，才能提供正確的值。 Bicep 提供 @description 裝飾項目，讓您能夠以人類可讀的格式，記錄您的參數用途。

@description('The locations into which this Cosmos DB account should be configured. This parameter needs to be a list of objects, each of which has a locationName property.')
param cosmosDBAccountLocations array

建議您為參數提供描述。請提供有所助益的描述，並提供範本所需參數值的相關重要資訊。

注意

有時可以在 Azure 入口網站中提供 Bicep 範本，供使用者部署時使用，例如當您使用範本規格時。入口網站會使用參數的描述與其他裝飾項目，協助使用者了解參數值的需求。