Bicep 模組

發行項
03/25/2024

Bicep 可讓您將部署組織成模組。模組是從另一個 Bicep 檔案 (或 ARM JSON 範本) 部署的 Bicep 檔案。使用模組時，您可以透過封裝部署的複雜詳細資料，來改善 Bicep 檔案的可讀性。您也可以輕鬆地對不同的部署重複使用模組。

若要與組織中的其他人共用模組，請建立範本規格、公用登錄或私人登錄。範本規格和登錄中的模組僅可供具備正確權限的使用者使用。

提示

您通常可依喜好來選擇要採用模組登錄或範本規格。當您在這兩者之間選擇時，需要考慮下列幾點：

模組登錄僅受 Bicep 支援。如果您尚未使用 Bicep，請使用範本規格。
Bicep 模組登錄中的內容只能從另一個 Bicep 檔案進行部署。範本規格可以直接從 API、Azure PowerShell、Azure CLI 和 Azure 入口網站部署。您甚至可以使用 UiFormDefinition (部分機器翻譯) 來自訂入口網站部署體驗。
Bicep 針對用下述函式內嵌其他專案成品 (包括非 Bicep 和非 ARM 範本檔案。例如，PowerShell 指令碼、CLI 指令碼和其他二進位檔) 的功能上有所限制：loadTextContent (部分機器翻譯) 和 loadFileAsBase64 (部分機器翻譯) 函式。範本規格無法封裝這些成品。

Bicep 模組會使用巢狀範本轉換成單一 Azure Resource Manager 範本。如需 Bicep 如何解析組態檔和 Bicep 如何將使用者定義組態檔與預設組態檔合併的詳細資訊，請參閱組態檔解析流程和組態檔合併流程。

訓練資源

如果您比較想要透過逐步指導來了解模組，請參閱使用模組建立可組合的 Bicep 檔案。

定義語法

定義模組的基本語法為：

module <symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

因此，簡單的真實世界範例看起來像這樣：

module stgModule '../storageAccount.bicep' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

您也可以使用 ARM JSON 範本作為模組：

module stgModule '../storageAccount.json' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

使用符號名稱，在 Bicep 檔案的另一個部分中參考該模組。例如，您可以使用符號名稱來取得模組的輸出。符號名稱可能包含 a-z、A-Z、0-9 和底線 (_)。名稱的開頭不能是數字。模組的名稱不能與參數、變數或資源相同。

路徑可以是本機檔案或登錄中的檔案。本機檔案可以是 Bicep 檔案或 ARM JSON 範本。如需詳細資訊，請參閱模組路徑 (部分機器翻譯)。

name 是必要屬性。其會成為所產生範本中巢狀部署資源的名稱。

如果將具有靜態名稱的模組同時部署到相同的範圍，那麼其中一個部署可能會干擾另一個部署的輸出。例如，如果兩個 Bicep 檔案使用相同的模組與相同的靜態名稱 (examplemodule)，且目標為相同的資源群組，那麼其中一個部署可能會顯示錯誤的輸出。如果您擔心相同範圍裡會有並行部署，那麼請以唯一名稱來命名您的模組。

下列範例會將部署名稱串連至模組名稱。如果您提供給部署的是唯一名稱，那麼模組名稱也會是唯一的。

module stgModule 'storageAccount.bicep' = {
  name: '${deployment().name}-storageDeploy'
  scope: resourceGroup('demoRG')
}

如果您需要指定與主要檔案範圍不同的範圍，請新增 scope 屬性。如需詳細資訊，請參閱設定模組範圍 (部分機器翻譯)。

// deploy to different scope
module <symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  scope: <scope-object>
  params: {
    <parameter-names-and-values>
  }
}

若要有條件地部署模組，請新增 if 運算式。使用方式類似於有條件地部署資源 (部分機器翻譯)。

// conditional deployment
module <symbolic-name> '<path-to-file>' = if (<condition-to-deploy>) {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

若要部署模組一個以上的執行個體，請新增 for 運算式。您可以使用 batchSize 裝飾項目來指定以序列方式或平行方式部署執行個體。如需詳細資訊，請參閱 Bicep 中的反覆式迴圈 (部分機器翻譯)。

// iterative deployment
@batchSize(int) // optional decorator for serial deployment
module <symbolic-name> '<path-to-file>' = [for <item> in <collection>: {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}]

如同資源，模組會以平行方式部署，除非其相依於其他模組或資源。一般來說，您不需要設定相依性，因為其為隱含決定。如果您需要設定明確相依性，您可以將 dependsOn 新增至模組定義。若要深入了解相依性，請參閱資源相依性 (部分機器翻譯)。

module <symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
  dependsOn: [
    <symbolic-names-to-deploy-before-this-item>
  ]
}

模組路徑

模組的檔案可以是本機檔案或外部檔案。外部檔案可以位於範本規格或 Bicep 模組登錄中。下面會說明這些選項。

本機檔案

如果模組是本機檔案，請提供該檔案的相對路徑。 Bicep 中的所有路徑都必須使用斜線 (/) 目錄分隔符號來指定，以確保跨平台的一致匯編。不支援 Windows 反斜線 (\) 字元。路徑可以包含空格。

例如，若要在主要檔案目錄的上一層中部署檔案，請使用：

module stgModule '../storageAccount.bicep' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

登錄中的檔案

公用模組模組登錄

公用模組登錄裝載於 Microsoft 容器登錄 (MCR)。原始程式碼和模組會儲存在 GitHub 中。若要檢視可用模組及其版本，請參閱 Bicep 登錄模組索引。

The screenshot of public module registry.

選取版本以查看可用的版本。您也可以選取原始程式碼，查看模組原始程式碼，然後開啟讀我檔案。

目前只有一些已發佈的模組。日後將持續推出更多模組。若要參與登錄，請參閱《貢獻指南》。

若要連結至公用登錄模組，請使用下列語法指定模組路徑：

module <symbolic-name> 'br/public:<file-path>:<tag>' = {}

br/public 是公用模組登錄的別名。此別名會在您的設定中預先定義。
file path 可以包含以 / 字元分隔的區段。
tag 可用於指定模組的版本。

例如：

module hw 'br/public:samples/hello-world:1.0.2' = {
  name: 'helloWorld'
  params: {
    name: 'John Dole'
  }
}

注意

br/public 是公用登錄的別名。它也可以寫成

module <symbolic-name> 'br:mcr.microsoft.com/bicep/<file-path>:<tag>' = {}

私人模組登錄

如果您已將模組發佈到登錄 (部分機器翻譯)，您可以連結至該模組。提供 Azure 容器登錄的名稱和模組的路徑。使用下列語法指定模組路徑：

module <symbolic-name> 'br:<registry-name>.azurecr.io/<file-path>:<tag>' = {

br 是 Bicep 登錄的結構描述名稱。
file path 在 Azure Container Registry 中稱為 repository。 file path 可以包含以 / 字元分隔的區段。
tag 可用於指定模組的版本。

例如：

module stgModule 'br:exampleregistry.azurecr.io/bicep/modules/storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

參考登錄中的模組時，Visual Studio Code 中的 Bicep 延伸模組會自動呼叫 bicep restore (部分機器翻譯)，以將外部模組複製到本機快取。需要幾分鐘的時間來還原外部模組。如果模組的 IntelliSense 無法立即運作，請等候還原完成。

登錄中模組的完整路徑可能很長。您可以在 bicepconfig.json 檔案中設定別名 (部分機器翻譯)，而不是在每次您想要使用模組時提供完整路徑。別名可讓您更輕鬆地參考模組。例如，您可以使用別名來將路徑縮短為：

module stgModule 'br/ContosoModules:storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

已預先定義公用模組登錄的別名：

module hw 'br/public:samples/hello-world:1.0.2' = {
  name: 'helloWorld'
  params: {
    name: 'John Dole'
  }
}

您可以在 bicepconfig.json 檔案中覆寫公用別名。

範本規格中的檔案

建立範本規格 (部分機器翻譯) 之後，您可以在模組中連結至該範本規格。以下列格式指定範本規格：

module <symbolic-name> 'ts:<sub-id>/<rg-name>/<template-spec-name>:<version>' = {

不過，您可以為包含範本規格的資源群組建立別名 (部分機器翻譯)，以簡化您的 Bicep 檔案。當您使用別名時，語法會變成：

module <symbolic-name> 'ts/<alias>:<template-spec-name>:<version>' = {

下列模組會部署範本規格來建立儲存體帳戶。範本規格的訂用帳戶和資源群組已在名為 ContosoSpecs 的別名中定義。

module stgModule 'ts/ContosoSpecs:storageSpec:2.0' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

參數

您在模組定義中提供的參數會符合 Bicep 檔案中的參數。

下列 Bicep 範例有三個參數：storagePrefix、storageSKU 和 location。 storageSKU 參數有預設值，因此在部署期間，您不需要為該參數提供值。

@minLength(3)
@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_RAGRS'
  'Standard_ZRS'
  'Premium_LRS'
  'Premium_ZRS'
  'Standard_GZRS'
  'Standard_RAGZRS'
])
param storageSKU string = 'Standard_LRS'

param location string

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2021-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

若要使用上述範例作為模組，請提供那些參數的值。

targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

resource demoRG 'Microsoft.Resources/resourceGroups@2021-04-01' existing = {
  name: 'demogroup1'
}

module stgModule '../create-storage-account/main.bicep' = {
  name: 'storageDeploy'
  scope: demoRG
  params: {
    storagePrefix: namePrefix
    location: demoRG.location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

設定模組範圍

宣告模組時，您可以設定與包含 Bicep 檔案的範圍不同的模組範圍。使用 scope 屬性來設定模組的範圍。如果未提供 scope 屬性，則會在父代的目標範圍中部署模組。

下列 Bicep 檔案會在該資源群組中建立資源群組和儲存體帳戶。該檔案會部署至訂用帳戶，但模組的範圍會設為新資源群組。

// set the target scope for this file
targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

param location string = deployment().location

var resourceGroupName = '${namePrefix}rg'

resource newRG 'Microsoft.Resources/resourceGroups@2021-04-01' = {
  name: resourceGroupName
  location: location
}

module stgModule '../create-storage-account/main.bicep' = {
  name: 'storageDeploy'
  scope: newRG
  params: {
    storagePrefix: namePrefix
    location: location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

下一個範例會將儲存體帳戶部署至兩個不同的資源群組。這兩個資源群組都必須已存在。

targetScope = 'subscription'

resource firstRG 'Microsoft.Resources/resourceGroups@2021-04-01' existing = {
  name: 'demogroup1'
}

resource secondRG 'Microsoft.Resources/resourceGroups@2021-04-01' existing = {
  name: 'demogroup2'
}

module storage1 '../create-storage-account/main.bicep' = {
  name: 'westusdeploy'
  scope: firstRG
  params: {
    storagePrefix: 'stg1'
    location: 'westus'
  }
}

module storage2 '../create-storage-account/main.bicep' = {
  name: 'eastusdeploy'
  scope: secondRG
  params: {
    storagePrefix: 'stg2'
    location: 'eastus'
  }
}

將 scope 屬性設定為有效的範圍物件。如果您的 Bicep 檔案會部署資源群組、訂用帳戶或管理群組，您可以將模組的範圍設為該資源的符號名稱。或者，您可以使用範圍函式來取得有效的範圍。

這些函式是：

下列範例會使用 managementGroup 函式來設定範圍。

param managementGroupName string

module mgDeploy 'main.bicep' = {
  name: 'deployToMG'
  scope: managementGroup(managementGroupName)
}

輸出

您可以從模組取得值，並在主要 Bicep 檔案中加以使用。若要從模組取得輸出值，請使用模組物件上的 outputs 屬性。

第一個範例會建立儲存體帳戶，並傳回主要端點。

@minLength(3)
@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_RAGRS'
  'Standard_ZRS'
  'Premium_LRS'
  'Premium_ZRS'
  'Standard_GZRS'
  'Standard_RAGZRS'
])
param storageSKU string = 'Standard_LRS'

param location string

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2021-04-01' = {
  name: uniqueStorageName
  location: location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

當成模組使用時，您可以取得該輸出值。

targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

resource demoRG 'Microsoft.Resources/resourceGroups@2021-04-01' existing = {
  name: 'demogroup1'
}

module stgModule '../create-storage-account/main.bicep' = {
  name: 'storageDeploy'
  scope: demoRG
  params: {
    storagePrefix: namePrefix
    location: demoRG.location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

下一步

如需教學課程，請參閱使用 Bicep 範本部署 Azure 資源 (部分機器翻譯)。
若要將敏感性值傳遞至模組，請使用 getSecret (部分機器翻譯) 函式。