Azure Resource Manager 範本規格 \(部分機器翻譯\)

發行項
03/25/2024

範本規格是一種資源類型，用來在 Azure 中儲存 Azure Resource Manager 範本 (ARM 範本) 以供後續部署之用。此資源類型可讓您與組織中的其他使用者共用 ARM 範本。就像任何其他 Azure 資源，您也可以使用 Azure 角色型存取控制 (Azure RBAC) 來共用範本規格。

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

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

注意

若要使用範本規格搭配 Azure PowerShell，您必須安裝 5.0.0 版或更新版本。若要與 Azure CLI 搭配使用，請使用 2.14.2 版或更新版本。

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

訓練資源

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

提示

我們建議使用 Bicep，因為其提供的功能與 ARM 範本相同，而且語法更易於使用。若要深入了解，請參閱 Bicep 中的 Azure Resource Manager 範本規格。

為什麼要使用範本規格？

範本規格提供下列優點：

您可以針對範本規格使用標準 ARM 範本。
您可以透過 Azure RBAC 來管理存取權，而非 SAS 權杖。
使用者可以在不需要範本寫入權限的情況下，部署範本規格。
您可以將範本規格整合至現有的部署流程，例如 PowerShell 指令碼或 DevOps 管線。

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

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

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

所需的權限

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

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

建立範本規格

下列範例顯示用來在 Azure 中建立儲存體帳戶的簡易範本。

{
  "$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": "2019-06-01",
      "name": "[concat('store', uniquestring(resourceGroup().id))]",
      "location": "[resourceGroup().location]",
      "kind": "StorageV2",
      "sku": {
        "name": "[parameters('storageAccountType')]"
      }
    }
  ]
}

當您建立範本規格時，PowerShell 或 CLI 命令會傳遞至主要範本檔案。如果主要範本參考連結的範本，則命令會尋找並封裝這些範本，以建立範本規格。若要深入了解，請參閱使用連結的範本建立範本規格。

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

PowerShell
CLI

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

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

您也可以使用 ARM 範本來建立範本規格。下列範本會建立範本規格來部署儲存體帳戶：

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "templateSpecName": {
      "type": "string",
      "defaultValue": "CreateStorageAccount"
    },
    "templateSpecVersionName": {
      "type": "string",
      "defaultValue": "0.1"
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/templateSpecs",
      "apiVersion": "2021-05-01",
      "name": "[parameters('templateSpecName')]",
      "location": "[parameters('location')]",
      "properties": {
        "description": "A basic templateSpec - creates a storage account.",
        "displayName": "Storage account (Standard_LRS)"
      }
    },
    {
      "type": "Microsoft.Resources/templateSpecs/versions",
      "apiVersion": "2021-05-01",
      "name": "[format('{0}/{1}', parameters('templateSpecName'), parameters('templateSpecVersionName'))]",
      "location": "[parameters('location')]",
      "dependsOn": [
        "[resourceId('Microsoft.Resources/templateSpecs', parameters('templateSpecName'))]"
      ],
      "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": "2019-06-01",
              "name": "[concat('store', uniquestring(resourceGroup().id))]",
              "location": "[resourceGroup().location]",
              "kind": "StorageV2",
              "sku": {
                "name": "[parameters('storageAccountType')]"
              }
            }
          ]
        }
      }
    }
  ]
}

範本規格的大小限制大約為 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 或作為較大型範本部署中連結的範本來部署範本規格。組織中的使用者可以將範本規格部署至 Azure 中的任何範圍 (資源群組、訂用帳戶、管理群組或租用戶)。

您可以透過提供資源識別碼 (而非傳入範本的路徑或 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}

參數

將參數傳入範本規格，與將參數傳遞至 ARM 範本的方法完全相同。以內嵌方式新增參數值，或在參數檔案中新增參數值。

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

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'

若要建立本機參數檔案，請使用：

{
  "$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.json `
  -Tag @{Dept="Finance";Environment="Production"}

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

PowerShell
CLI

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

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

在建立或修改範本規格時已指定 version 參數，但未指定 tag/tags 參數：

如果範本規格存在且具有標記，但版本不存在，則新版本會繼承與現有範本規格相同的標記。

在建立或修改範本規格時，同時指定了 tag/tags 參數和 version 參數：

如果範本規格和版本都不存在，就會將標記新增至新的範本規格和新版本中。
如果範本規格存在，但版本不存在，只會將標記新增至新版本中。
如果範本規格和版本都存在，則標記只會套用至版本。

在以指定的 tag/tags 參數修改範本，但未指定 version 參數時，只會將標記新增至範本規格中。

使用連結的範本建立範本規格 \(部分機器翻譯\)

如果範本規格的主要範本會參考連結的範本，PowerShell 和 CLI 命令就可以自動從您的本機磁碟機尋找並封裝連結的範本。您不需要手動設定儲存體帳戶或存放庫來裝載範本規格，所有項目都會在範本規格資源中獨立進行。

下列範例包含具有兩個連結範本的主要範本。此範例只是範本的摘要。請注意，其使用名為 relativePath 的屬性來連結到其他範本。您必須針對部署資源使用 2020-06-01 或更新版本的 apiVersion。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  ...
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-06-01",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "relativePath": "artifacts/webapp.json"
        }
      }
    },
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-06-01",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "relativePath": "artifacts/database.json"
        }
      }
    }
  ],
  "outputs": {}
}

針對上述範例執行建立範本規格的 PowerShell 或 CLI 命令時，此命令會尋找三個檔案：主要範本、Web 應用程式範本 (webapp.json)，以及資料庫範本 (database.json)，並將其封裝到範本規格中。

如需詳細資訊，請參閱教學課程：使用連結的範本建立範本規格。

將範本規格部署為連結的範本

建立範本規格之後，可以輕鬆地從 ARM 範本或其他範本規格重複使用。您可以將範本識別碼新增至範本，以連結至範本規格。當您部署主要範本時，即會自動部署連結的範本規格。此行為可讓您開發模組化範本規格，並視需要重複使用它們。

例如，您可以建立一個範本規格來部署網路資源，並建立另一個範本規格來部署儲存體資源。在 ARM 範本中，您可以在每次需要設定網路功能或儲存體資源時，連結至這兩個範本規格。

下列範例與先前範例類似，但您可以使用 id 屬性連結至範本規格，而不是使用 relativePath 屬性連結至本機範本。使用 2020-06-01 作為部署資源的 API 版本。在此範例中，範本規格位於名為 templateSpecsRG 的資源群組中。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  ...
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-06-01",
      "name": "networkingDeployment",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "id": "[resourceId('templateSpecsRG', 'Microsoft.Resources/templateSpecs/versions', 'networkingSpec', '1.0a')]"
        }
      }
    },
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-06-01",
      "name": "storageDeployment",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "id": "[resourceId('templateSpecsRG', 'Microsoft.Resources/templateSpecs/versions', 'storageSpec', '1.0a')]"
        }
      }
    }
  ],
  "outputs": {}
}

如需連結範本規格的詳細資訊，請參閱教學課程：將範本規格部署為連結的範本。

下一步

若要建立及部署範本規格，請參閱快速入門：建立和部署範本規格。
如需在範本規格中連結範本的詳細資訊，請參閱教學課程：使用連結的範本建立範本規格。
若要了解如何將範本規格部署為連結的範本，請參閱教學課程：將範本規格部署為連結的範本。