Bicep 中的 Azure Resource Manager 範本規格

發行項
09/26/2024

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

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

若要部署範本規格，您可以使用 PowerShell、Azure CLI、Azure 入口網站、REST 等標準 Azure 工具，和其他支援的 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 (部分機器翻譯) 來自訂入口網站部署體驗。
Bicep 針對用下述函式內嵌其他專案成品 (包括非 Bicep 和非 ARM 範本檔案。例如，PowerShell 指令碼、CLI 指令碼和其他二進位檔) 的功能上有所限制：loadTextContent (部分機器翻譯) 和 loadFileAsBase64 (部分機器翻譯) 函式。範本規格無法封裝這些成品。

訓練資源

若要深入了解範本規格並取得實作指引，請參閱使用範本規格來發佈可重複使用基礎結構程式碼的程式庫。

所需的權限

範本規格已定義兩個 Azure 內建角色：

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

為什麼要使用範本規格？

範本規格提供下列優點：

您可以針對範本規格使用標準 ARM 範本或 Bicep 檔案。
您可以透過 Azure RBAC 來管理存取權，而非 SAS 權杖。
使用者可以在不需要 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'
}

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

PowerShell
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 中已定義的參數和變數，您仍然需要使用 ARM JSON 範本語法。例如，'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.

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

PowerShell
CLI

Get-AzTemplateSpec

az ts list

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

PowerShell
CLI

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

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

部署範本規格

建立範本規格之後，具有範本規格讀取者角色的使用者即可加以部署。此外，您也需要部署 ARM 範本的權限。請參閱部署 - CLI 或部署 - PowerShell。

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

您可以藉由提供資源識別碼來部署範本規格，而非藉由傳入 Bicep 檔案的路徑或 URI。資源識別碼具有下列格式：

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

請注意，資源識別碼包含範本規格的版本名稱。

例如，您可以使用下列命令來部署範本規格。

PowerShell
CLI

$id = "/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

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

id = "/subscriptions/11111111-1111-1111-1111-111111111111/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 以取得您想要部署之範本規格的識別碼。

PowerShell
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 檔案的方法類似。以內嵌方式新增參數值，或在參數檔案中新增參數值。

內嵌參數

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

PowerShell
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 參數檔案

若要建立 Bicep 參數檔案，您必須指定 using 陳述式。以下是範例：
```
using 'using 'ts:<subscription-id>/<resource-group-name>/<template-spec-name>:<tag>'

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

然後，使用下列程式碼來傳遞參數檔案：
- PowerShell
- CLI
目前，您無法使用 Azure 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"
    }
  }
}

然後，使用下列程式碼來傳遞該參數檔案：

PowerShell
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，將標記新增至範本規格。下列範例會示範如何在建立範本規格時指定標記：

PowerShell
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

下一個範例會示範如何在更新現有的範本規格時套用標記：

PowerShell
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 檔案時，會部署範本規格。如需詳細資訊，請參閱範本規格中的檔案。

若要為用於模組連結的範本規格建立別名，請參閱模組的別名。

下一步