在模組中新增參數和輸出

7 分鐘

您建立的每個模組應該都有明確的用途。將模組視為具有「合約」。它接受一組參數、建立一組資源，而且可能會將一些輸出提供回父範本。無論誰使用模組，都不需擔心其運作方式，只要模組按照使用者的期望運作即可。

當您規劃模組時，請考慮：

您需要知道才能滿足模組用途的事項。
任何取用您模組的人都將預期提供的內容。
任何取用您模組的人都將預期要存取來作為輸出的內容。

模組參數

考慮模組接受的參數，以及每個參數應該是選擇性還是必要參數。

當您建立範本的參數時，最好的做法是盡可能新增預設參數。在模組中，新增預設參數不一定那麼重要，因為您的模組將由可能使用其自己預設參數的父範本使用。如果您在這兩個檔案中都有類似的參數 (這兩者均具有預設值)，您範本的使用者就很難找出將套用哪個預設值並強制執行一致性。通常，最好在父範本上保留預設值，並將它從模組中移除。

您也應該考慮如何管理參數，以控制適用於資源的 SKU 及其他重要組態設定。當您建立一個獨立 Bicep 範本時，通常會將商務規則內嵌至範本中。例如：「當我部署實際執行環境時，儲存體帳戶應該會使用 GRS 層。」。但模組有時候會呈現不同的疑慮。

若您要建置需要重複使用和具備彈性的模組，請記住，每個父範本的商務規則可能會有所差異，因此可能與將商務規則內嵌至一般模組時的道理不同。請考慮在父範本中定義商務規則，然後透過參數明確傳遞模組設定。

不過，如果您建立的模組旨在讓您自己的組織輕鬆地部署符合您特定需求的資源，則包含商務規則來簡化父範本就是個合理的做法。

無論您在模組中包含哪些參數，請務必使用 @description 屬性來新增有意義的描述：

@description('The name of the storage account to deploy.')
param storageAccountName string

使用條件

使用 Bicep 之類的程式碼來部署基礎結構的目標之一就是避免重複工作，或甚至基於相同或類似的用途建立數個範本。 Bicep 的功能可為您提供功能強大的工具箱，讓您能夠建立適用於各種情況且可重複使用的模組。您可以合併模組、運算式、預設參數值及條件等功能，來建置可重複使用的程式碼，以提供您所需的彈性。

假設您正在建立部署 Azure Cosmos DB 帳戶的模組。將其部署到您的實際執行環境時，您必須設定帳戶以將它的記錄傳送到 Log Analytics 工作區。如需設定要傳送到 Log Analytics 的記錄，您可以定義 diagnosticSettings 資源。

您可以透過將條件新增至資源定義來達成需求，並透過新增預設值來選用工作區識別碼參數：

param logAnalyticsWorkspaceId string = ''

resource cosmosDBAccount 'Microsoft.DocumentDB/databaseAccounts@2022-08-15' = {
  // ...
}

resource cosmosDBAccountDiagnostics 'Microsoft.Insights/diagnosticSettings@2021-05-01-preview' =  if (logAnalyticsWorkspaceId != '') {
  scope: cosmosDBAccount
  name: 'route-logs-to-log-analytics'
  properties: {
    workspaceId: logAnalyticsWorkspaceId
    logs: [
      {
        category: 'DataPlaneRequests'
        enabled: true
      }
    ]
  }
}

當您在 Bicep 範本中包含此模組時，您可以透過設定工作區識別碼，輕鬆地設定它以將 Azure Cosmos DB 帳戶記錄傳送到 Log Analytics。或者，如果您不需要所部署環境的記錄，請省略此參數。其具有預設值。此模組會封裝針對您的需求執行正確動作所需的邏輯。

提示

請記得測試您的範本是否適用於這兩種案例 (當 if 陳述式評估為 true 或 false 時)。

模組輸出

模組可以定義輸出。最好針對父範本可能需要使用的資訊建立輸出。例如，如果您的模組會定義儲存體帳戶，請考慮建立儲存體帳戶名稱的輸出，讓父範本可以存取它。

警告

請勿將輸出用於祕密值。輸出會記錄為部署歷程記錄的一部分，因此它們不適用於安全值。您可以改為考慮下列其中一個選項：

使用輸出來提供資源的名稱。然後，父範本可以建立具有該名稱的 existing 資源，而且可以動態查閱安全值。
將值寫入到 Azure Key Vault 祕密。讓父範本可在需要時從保存庫讀取祕密。

父範本可以在變數中使用模組輸出、可針對其他資源定義使用屬性，或者可將變數和屬性公開為輸出本身。透過公開並使用整個 Bicep 檔案中的輸出，您可以建立可重複使用的 Bicep 模組集合，以便與您的小組共用，並在多個部署之間重複使用。使用 @description 屬性來將有意義的描述新增到輸出也是個很好的做法：

@description('The fully qualified Azure resource ID of the blob container within the storage account.')
output blobContainerResourceId string = storageAccount::blobService::container.id

提示

您也可以使用專用服務來儲存、管理及存取 Bicep 範本所建立的設定。 Key Vault 的設計目的是儲存安全值。 Azure 應用程式組態的設計目的是儲存其他 (不安全) 值。

將模組鏈結在一起

通常會建立一個父 Bicep 檔案，以將多個模組組合在一起。例如，假設您要建置新的 Bicep 範本，以部署使用專用虛擬網路的虛擬機器。您可以建立模組來定義虛擬網路。然後，您可以將虛擬網路的子網路資源識別碼作為該模組的輸出，並將其用來作為虛擬機器模組的輸入：

@description('Username for the virtual machine.')
param adminUsername string

@description('Password for the virtual machine.')
@minLength(12)
@secure()
param adminPassword string

module virtualNetwork 'modules/vnet.bicep' = {
  name: 'virtual-network'
}

module virtualMachine 'modules/vm.bicep' = {
  name: 'virtual-machine'
  params: {
    adminUsername: adminUsername
    adminPassword: adminPassword
    subnetResourceId: virtualNetwork.outputs.subnetResourceId
  }
}

在此範例中，符號名稱會用於模組之間的參考。此參考可協助 Bicep 自動了解模組之間的關聯性。

由於 Bicep 了解有相依性存在，因此，其會依序部署模組：

Bicep 會在 virtualNetwork 模組中部署所有項目。
如果該部署成功，Bicep 會存取 subnetResourceId 輸出值，並將它當作參數傳遞給 virtualMachine 模組。
Bicep 會在 virtualMachine 模組中部署所有項目。

注意

當您相依於模組時，Bicep 會等候整個模組部署完成。當您規劃模組時，請務必記住這一點。如果您建立的模組會定義需要長時間部署的資源，則相依於該模組的任何其他資源都會等待整個模組的部署完成。

在模組中新增參數和輸出

模組參數

使用條件

模組輸出

將模組鏈結在一起

意見反應