改善參數與名稱

8 分鐘

參數將會是同事與您的範本互動的最常見方式。當同事部署您的範本時，其需要指定參數的值。建立之後，資源的名稱會為任何查看您 Azure 環境的人員提供與其用途相關的重要資訊。

在本單元中，您將了解在規劃 Bicep 檔案的參數以及為資源命名時的一些重要考量事項。

參數的可理解程度為何？

參數有助於讓 Bicep 檔案可重複使用且具有彈性。對於任何使用參數的人來說，每個參數的用途都必須清楚明瞭。當同事使用您的範本時，他們會使用參數自訂其部署的行為。

例如，假設您需要使用 Bicep 檔案部署儲存體帳戶。儲存體帳戶的其中一個必要屬性是定義資料備援層級的庫存單位 (SKU)。該 SKU 有數個屬性，最重要的是 name。當建立參數以設定儲存體帳戶 SKU 的值時，請使用明確定義的名稱，例如 storageAccountSkuName。使用這個值而非泛型名稱 (如 sku 或 skuName)，可協助其他人了解參數的用途及設定其值的效果。

預設值是讓您的範本可供其他人使用的重要方式。請務必使用合理的預設值。這些預設值會以兩種方式協助您的範本使用者：

預設值簡化了部署範本的程序。若參數具有適用於大部分範本使用者的良好預設值，則可以省略參數值，而不是在每次部署範本時都加以指定。
預設值提供您預期參數值外觀的範例。若範本使用者需要選擇不同的值，則預設值可提供與其值外觀相關的實用提示。

Bicep 也可協助驗證使用者透過「參數裝飾項目」所提供的輸入。您可以使用這些裝飾項目來提供參數描述，或陳述允許值的種類。 Bicep 會提供數種類型的參數裝飾項目：

描述提供有關參數用途及設定其值之效果的人類可讀資訊。
值條件約束會為使用者可針對參數值輸入的內容實施限制。您可以透過使用 @allowed() 裝飾項目來指定特定允許值的清單。您可以使用 @minValue() 和 @maxValue() 裝飾項目來強制規定數值參數的最小值和最大值，也可以使用 @minLength() 和 @maxLength() 裝飾項目來強制規定字串和陣列參數的長度。

提示

使用 @allowed() 參數裝飾項目指定 SKU 時請小心。 Azure 服務通常會新增 SKU，而您不想讓範本不必要地禁止使用。請考慮使用 Azure 原則實施特定 SKU，並且只有當範本的使用者不應選取特定 SKU 時，才搭配 SKU 一起使用 @allowed() 裝飾項目。例如，當範本所需的功能可能無法在該 SKU 中使用時。請使用 @description() 裝飾項目或註解來說明這一點，讓後續所有人都清楚了解這些原因。
中繼資料可以用來提供關於參數的額外自訂中繼資料，雖然並不常用。

Bicep 檔案彈性程度應該為何？

定義基礎結構即程式碼的其中一個目標，就是讓您的範本可重複使用且具有彈性。您不會想要建立包含硬式編碼設定的單一用途範本。另一方面，將所有資源屬性都公開為參數並不合理。請建立適用於特定商務問題或解決方案的範本，而不是需要應付各種情況的泛用型範本。您也不希望有太多參數，以至於在部署範本之前需要花很長時間來輸入這些值。當您在設定資源的 SKU 與執行個體計數時，這一點特別重要。

當您在規劃範本時，請考慮如何在簡潔性與彈性之間取得平衡。有兩種常見方式可提供範本中的參數：

提供自由格式的設定選項
使用預先定義的設定集

讓我們使用部署儲存體帳戶與 Azure App Service 方案的範例 Bicep 檔案來考量這兩種方法。

提供自由格式的設定選項

App Service 方案與儲存體帳戶都需要您指定其 SKU。您可以考慮建立一組參數，以控制資源的每個 SKU 與執行個體計數：

控制 App Service 方案和儲存體帳戶的參數圖表。

在 Bicep 中會這樣顯示：

param appServicePlanSkuName string
param appServicePlanSkuCapacity int
param storageAccountSkuName string

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

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-05-01' = {
  name: storageAccountSkuName
  location: location
  sku: {
    name: storageAccountSkuName
  }
}

因為使用此範本的任何人都可以指定任何參數值組合，所以此格式可提供最大的彈性。然而，新增愈多資源，就需要愈多參數，導致您的範本變得更複雜。此外，您可能需要限制特定的參數組合，或確保在使用某一個 SKU 部署特定資源時，另一個資源需要使用不同的 SKU 進行部署。如果您提供太多不同的參數，則很難實施這些規則。

提示

請考慮將使用您範本的人員。看到數十個參數可能會造成人員的負擔，並促使人員放棄使用您的範本。

您可以透過參數物件的形式將相關參數分組，以減少參數數目，如下所示：

param appServicePlanSku object = {
  name: 'S1'
  capacity: 2
}

然而，這種方法會降低驗證參數值的能力，而且您的範本使用者不一定能很容易理解如何定義物件。

使用預先定義的設定集

或者，您可以提供「設定集」：單一參數，其值為受限制的允許值清單，例如環境類型清單。當使用者部署您的範本時，使用者只需要針對這一個參數選取一個值。為參數選取值之後，部署會自動繼承一組設定：

控制 App Service 方案和儲存體帳戶的組態集圖表。

該參數定義看起來像這樣：

@allowed([
  'Production'
  'Test'
])
param environmentType string = 'Test'

組態集提供較低的彈性，因為部署範本的人無法為個別的資源指定大小，但您可以驗證每組組態，並確保它們符合您的需求。使用設定集可降低範本使用者了解每個資源所有不同可用選項的需求，讓您更輕鬆地支援、測試範本及對範本進行疑難排解。

當使用設定集時，會建立一個「對應」變數，根據參數值來定義要在不同資源上設定的特定屬性：

var environmentConfigurationMap = {
  Production: {
    appServicePlan: {
      sku: {
        name: 'P2V3'
        capacity: 3
      }
    }
    storageAccount: {
      sku: {
        name: 'ZRS'
      }
    }
  }
  Test: {
    appServicePlan: {
      sku: {
        name: 'S2'
        capacity: 1
      }
    }
    storageAccount: {
      sku: {
        name: 'LRS'
      }
    }
  }
}

然後，您的資源定義會使用該設定對應來定義資源屬性：

resource appServicePlan 'Microsoft.Web/serverfarms@2023-12-01' = {
  name: appServicePlanName
  location: location
  sku: environmentConfigurationMap[environmentType].appServicePlan.sku
}

設定集可協助您使複雜的範本更容易存取。其也可以協助您實施自己的規則，並鼓勵使用預先驗證的設定值。

注意

此方法有時稱為「T 恤尺寸」。當購買 T 恤時，不會有長度、寬度、有袖等許多選項。您只需選擇 S、M 及 L 尺寸，而 T 恤設計師已根據該大小預先定義這些量值。

如何命名資源？

在 Bicep 中，請務必為資源提供有意義的名稱。 Bicep 中的資源有兩種名稱：

符號名稱只會在 Bicep 檔案中使用，且不會出現在您的 Azure 資源上。符號名稱可協助使用者讀取或修改您的範本，以了解參數、變數或資源定義的用途，並協助使用者針對是否要變更範本做出明智的決策。
資源名稱是在 Azure 中所建立資源的名稱。許多資源都有其名稱的限制，而許多資源的名稱都不得重複。

符號名稱

請務必思考您套用至資源的符號名稱。想像您有需要修改範本的同事。他們會了解每個資源的用途嗎？

例如，假設您定義了儲存體帳戶，其中將包含可供使用者從網站下載的產品手冊。您可以為資源提供一個符號名稱 (例如) storageAccount，但如果它位於包含許多其他資源 (甚至可能還包含其他儲存體帳戶) 的 Bicep 檔案中，則該名稱的描述性不夠。相反地，您可以為其提供一個符號名稱，其中包含一些有關其用途的資訊，例如 productManualStorageAccount。

在 Bicep 中，您通常會針對參數、變數名稱與資源符號名稱使用 camelCase。這表示您會對第一個單字的第一個字母使用小寫，然後對其他單字的第一個字母使用大寫 (如上述範例中的 productManualStorageAccount)。您不一定要使用 camelCase。若您選擇使用不同的樣式，請務必在您小組內針對一個標準取得共識，並保持一致的用法。

資源名稱

每個 Azure 資源都有名稱。名稱是組成資源識別碼的一部分。在許多情況下，它們也表示為您用於存取資源的主機名稱。例如，當您建立名為 myapp 的 App Service 應用程式時，您用來存取應用程式的主機名稱就是 myapp.azurewebsites.net。部署資源後您無法對其進行重新命名。

請務必考慮您命名 Azure 資源的方式。許多組織會定義自己的資源命名慣例。 Azure 雲端採用架構具有特定指南，可協助您定義自己的資源命名慣例。資源命名慣例的目的是協助您組織中的每個人都了解每個資源的用途。

此外，每個 Azure 資源都有特定的命名規則與限制。例如，對於名稱長度、可包含的字元，以及名稱是在全域都不得重複還是只在資源群組中不得重複，都有一些限制。

要同時遵循您組織的所有命名慣例及 Azure 的命名需求，可能會很複雜。妥善撰寫的 Bicep 範本應該讓使用者無法察覺此複雜性，並自動判斷資源的名稱。以下是要遵循的其中一個方法範例：

新增用來建立「唯一性尾碼」的參數。這有助於確保您的資源具有唯一名稱。建議您使用 uniqueString() 函式產生預設值。若部署範本的使用者想要擁有有意義的名稱，則可使用特定值覆寫此值。請務必使用 @maxLength() 裝飾項目限制此尾碼的長度，讓資源名稱不會超過其長度上限。

提示

建議您使用唯一性尾碼，而不是首碼。此方法可讓您更輕鬆地排序及快速掃描資源名稱。此外，某些 Azure 資源對於名稱的第一個字元有所限制，而隨機產生的名稱有時可能會違反這些限制。
請使用變數動態地建構資源名稱。您的 Bicep 程式碼可確保其產生的名稱同時遵循組織命名慣例，以及 Azure 的需求。請在資源名稱中包含唯一性尾碼。

注意

並非每個資源都需要全域唯一的名稱。考慮是否在每個資源的名稱中包含唯一性尾碼，還是僅在需要它的資源的名稱中包含唯一性尾碼。