Bicep 中的 Azure Resource Manager 範本規格

發行項
01/11/2025

範本規格是用來儲存 Azure Resource Manager 範本（ARM 範本）的資源類型，稍後加以部署。此資源類型可讓您與組織中的其他使用者共用 ARM 範本。就像任何其他 Azure 資源，您也可以使用 Azure 角色型存取控制 (Azure RBAC) 來共用範本規格。您可以使用 Azure CLI 或 Azure PowerShell 來建立範本規格，方法是提供 Bicep 檔案。 Bicep 檔案會在儲存之前轉譯成 JSON ARM 範本。您目前無法從 Azure 入口網站匯入 Bicep 檔案，以建立範本規格資源。

Microsoft.Resources/templateSpecs 是適用於範本規格的資源類型。它由一個主要範本和任意數目的連結範本所組成。 Azure 會將範本規格安全地儲存在資源群組中。主要範本和連結範本都必須為 JSON 格式。範本規格支援版本設定。

若要部署範本規格，請使用標準 Azure 工具，例如 PowerShell、Azure CLI、Azure 入口網站、REST 和其他支援的 SDK 和用戶端。您可以使用與範本或 Bicep 檔案相同的命令。

注意

若要與 Azure PowerShell 搭配使用 Bicep 內的範本規格，您必須安裝 6.3.0 版或更新版本。若要與 Azure CLI 搭配使用，請使用 2.27.0 版或更新版本。

設計部署時，請一律考慮資源的生命週期，並將共用類似生命週期的資源分組為單一範本規格。例如，您的部署包含多個 Azure Cosmos DB 執行個體，每個執行個體都包含自己的資料庫和容器。由於資料庫和容器的變化不大，因此，您希望建立單一範本規格來包含 Cosmo DB 執行個體及其基礎資料庫和容器。然後您可以使用 Bicep 中的條件陳述式並複製迴圈來建立這些資源的多個執行個體。

提示

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

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

所需的權限

Azure 內建兩個角色，並針對範本規格定義：

此外，您也需要部署 Bicep 檔案的權限。請參閱使用 Azure CLI 或 Azure PowerShell 部署 Bicep 檔案。

為何使用範本規格

範本規格提供下列優點：

您可以針對範本規格使用標準 ARM 範本或 Bicep 檔案。
您可以透過 Azure RBAC 管理存取，而不是共用存取簽章令牌。
使用者可以在不需要 Bicep 檔案寫入權限的情況下，部署範本規格。
您可以將範本規格整合到現有的部署程式，例如 PowerShell 腳本或 DevOps 管線。

範本規格可讓您建立標準範本，並與組織中的小組共用。範本規格相當安全，因為它們可供 Azure Resource Manager 用來部署，但沒有正確權限的使用者無法存取。使用者只需擁有範本規格的讀取權限即可部署其範本，因此您無須允許其他人修改範本即可共用範本。

如果您的範本目前位於 GitHub 存放庫或儲存體帳戶中，則會在嘗試共用和使用範本時遇到幾項挑戰。若要部署範本，您必須將範本設為可公開存取，或使用 SAS 權杖來管理存取權。為了解決這項限制，使用者可能會建立本機複本，使其最終能夠脫離您的原始範本。範本規格簡化了共用範本的方式。

您在範本規格中包含的範本應由組織中的管理員進行驗證，以遵循組織的需求和指引。

建立範本規格

下列範例簡易示範如何在 Azure 中建立儲存體帳戶的 Bicep 檔案。

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name:  'store${uniqueString(resourceGroup().id)}'
  location: resourceGroup().location
  sku: {
    name: storageAccountType
  }
  kind:'StorageV2'
}

使用下列程式碼來建立範本規格：

Azure PowerShell
Azure CLI

New-AzTemplateSpec -Name storageSpec -Version 1.0a -ResourceGroupName templateSpecsRg -Location westus2 -TemplateFile ./mainTemplate.bicep

az ts create \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.bicep"

您也可以使用 Bicep 檔案來建立範本規格。不過，的內容 mainTemplate 必須是 JSON。下列範本會建立範本規格來部署儲存體帳戶：

param templateSpecName string = 'CreateStorageAccount'
param templateSpecVersionName string = '0.1'
param location string = resourceGroup().location

resource createTemplateSpec 'Microsoft.Resources/templateSpecs@2022-02-01' = {
  name: templateSpecName
  location: location
  properties: {
    description: 'A basic templateSpec - creates a storage account.'
    displayName: 'Storage account (Standard_LRS)'
  }
}

resource createTemplateSpecVersion 'Microsoft.Resources/templateSpecs/versions@2022-02-01' = {
  parent: createTemplateSpec
  name: templateSpecVersionName
  location: location
  properties: {
    mainTemplate: {
      '$schema': 'https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#'
      'contentVersion': '1.0.0.0'
      'parameters': {
        'storageAccountType': {
          'type': 'string'
          'defaultValue': 'Standard_LRS'
          'allowedValues': [
            'Standard_LRS'
            'Standard_GRS'
            'Standard_ZRS'
            'Premium_LRS'
          ]
        }
      }
      'resources': [
        {
          'type': 'Microsoft.Storage/storageAccounts'
          'apiVersion': '2023-04-01'
          'name': 'store$uniquestring(resourceGroup().id)'
          'location': resourceGroup().location
          'kind': 'StorageV2'
          'sku': {
            'name': '[parameters(\'storageAccountType\')]'
          }
        }
      ]
    }
  }
}

內嵌於 Bicep 檔案中的 JSON 範本必須進行這些變更：

移除每行結尾的逗號。
以單引號取代雙引號。
將運算式內的單引號逸出。例如，'name': '[parameters(\'storageAccountType\')]'。
若要存取 Bicep 檔案中定義的參數和變數，您可以直接使用參數名稱和變數名稱。若要存取中 mainTemplate定義的參數和變數，您仍然需要使用 JSON ARM 範本語法。例如，'name': '[parameters(\'storageAccountType\')]'。
使用 Bicep 語法來呼叫 Bicep 函式。例如，'location': resourceGroup().location。

範本規格的大小限制為大約 2 MB。如果範本規格大小超過限制，則會出現 TemplateSpecTooLarge 錯誤碼。錯誤訊息顯示：

The size of the template spec content exceeds the maximum limit. For large template specs with many artifacts, the recommended course of action is to split it into multiple template specs and reference them modularly via TemplateLinks.

您可以使用下列程式碼來檢視訂用帳戶中的所有範本規格：

Azure PowerShell
Azure CLI

Get-AzTemplateSpec

az ts list

您可以使用下列程式碼來檢視範本規格的詳細資料，包括其版本：

Azure PowerShell
Azure CLI

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

az ts show \
    --name storageSpec \
    --resource-group templateSpecRG \
    --version "1.0a"

部署範本規格

建立範本規格之後，具有範本規格讀取器角色的使用者就可以部署它。請記住，您需要適當的許可權才能部署ARM範本。

範本規格可以透過 Azure 入口網站、PowerShell、Azure CLI 或大型範本部署中的 Bicep 模組來部署。組織中的使用者可以將範本規格部署到 Azure 中的任何範圍（例如資源群組、訂用帳戶、管理群組或租使用者）。

您可以藉由提供其資源標識符來部署範本規格，而不是將它傳遞至 Bicep 檔案的路徑或 URI。資源識別碼的格式如下：請注意，它包含範本規格的版本名稱：

/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Resources/templateSpecs/{template-spec-name}/versions/{template-spec-version}

您可以使用下列命令來部署樣本規格：

Azure PowerShell
Azure CLI

$id = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG

id = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

az deployment group create \
  --resource-group demoRG \
  --template-spec $id

在實務上，通常會執行 Get-AzTemplateSpec 或 az ts show 以取得您想要部署之範本規格的識別碼。

Azure PowerShell
Azure CLI

$id = (Get-AzTemplateSpec -Name storageSpec -ResourceGroupName templateSpecsRg -Version 1.0a).Versions.Id

New-AzResourceGroupDeployment `
  -ResourceGroupName demoRG `
  -TemplateSpecId $id

id = $(az ts show --name storageSpec --resource-group templateSpecRG --version "1.0a" --query "id")

az deployment group create \
  --resource-group demoRG \
  --template-spec $id

您也可以使用下列格式開啟 URL 來部署樣本規格：

https://portal.azure.com/#create/Microsoft.Template/templateSpecVersionId/%2fsubscriptions%2f{subscription-id}%2fresourceGroups%2f{resource-group-name}%2fproviders%2fMicrosoft.Resources%2ftemplateSpecs%2f{template-spec-name}%2fversions%2f{template-spec-version}

參數

將參數傳遞至範本規格類似於將參數傳遞至 Bicep 檔案。在參數檔案中加入內嵌或參數值。

內嵌參數

若要以內嵌方式傳遞參數，請使用：

Azure PowerShell
Azure CLI

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG `
  -StorageAccountType Standard_GRS

az deployment group create \
  --resource-group demoRG \
  --template-spec $id \
  --parameters storageAccountType='Standard_GRS'

參數檔案

使用 Bicep 參數檔案。

您必須指定 using 語句來建立 Bicep 參數檔案。例如：
```
using 'using 'ts:<subscription-id>/<resource-group-name>/<template-spec-name>:<tag>'

param StorageAccountType = 'Standard_GRS'
```
如需詳細資訊，請參閱建立 Bicep 部署的參數檔案。

使用下列方法傳遞參數檔案：
- Azure PowerShell
- Azure CLI
您目前無法使用 PowerShell 來部署具有檔案的.bicepparam範本規格。
```
az deployment group create \
  --resource-group demoRG \
  --parameters "./mainTemplate.bicepparam"
```
因為檔案中的 .bicepparam 語句，using因此您不需要指定 --template-spec 參數。

使用 JSON 參數檔案。

下列 JSON 是範例 JSON 參數檔案：

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "StorageAccountType": {
      "value": "Standard_GRS"
    }
  }
}

您也可以使用：

Azure PowerShell
Azure CLI

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG `
  -TemplateParameterFile ./mainTemplate.parameters.json

az deployment group create \
  --resource-group demoRG \
  --template-spec $id \
  --parameters "./mainTemplate.parameters.json"

版本控制

當您建立範本規格時，您會提供版本名稱。當您逐一查看範本程式碼後，就能夠更新現有版本 (用於修正程式)，或發佈新版本。版本是一個文字字串。您可以選擇遵循任何版本設定系統，包括語意化版本控制系統。範本規格使用者可以提供部署時想要使用的版本名稱，而且可以有無限數量的版本。

使用標記

標籤可協助您以邏輯方式組織資源。您可以使用 Azure PowerShell 或 Azure CLI 將標籤新增至範本規格。下列範例會示範如何在建立範本規格時指定標記：

Azure PowerShell
Azure CLI

New-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0a `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateFile ./mainTemplate.bicep `
  -Tag @{Dept="Finance";Environment="Production"}

az ts create \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.bicep" \
  --tags Dept=Finance Environment=Production

下列範例示範如何在更新現有的範本規格時套用標籤：

Azure PowerShell
Azure CLI

Set-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0a `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateFile ./mainTemplate.bicep `
  -Tag @{Dept="Finance";Environment="Production"}

az ts update \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.bicep" \
  --tags Dept=Finance Environment=Production

範本及其版本都可以有標記。標記會根據您指定的參數套用或繼承：

範本規格	版本	版本參數	標記參數	標記值
Exists	N/A	未指定	已指定	已套用至範本規格
Exists	新增	已指定	未指定	從範本規格繼承至版本
新增	新增	已指定	已指定	同時套用至範本規格和版本
Exists	新增	已指定	已指定	已套用至版本
Exists	Exists	已指定	已指定	已套用至版本

連結至範本規格

建立範本規格之後，您可以在 Bicep 模組中連結至該範本規格。當您部署包含該模組的 Bicep 檔案時，會部署範本規格。如需詳細資訊，請參閱模組的路徑。
若要為用於模組連結的範本規格建立別名，請參閱模組的別名。

下一步

如需範本規格的詳細資訊和實際操作指引，請參閱使用範本規格發佈可重複使用基礎結構程式代碼的連結庫 Learn 課程模組。

共用方式為