Specifikace šablon Azure Resource Manageru v Bicep

Článek
01/11/2025

Specifikace šablony je typ prostředku pro uložení šablony Azure Resource Manageru (šablony ARM) pro pozdější nasazení. Tento typ prostředku umožňuje sdílet šablony ARM s ostatními uživateli ve vaší organizaci. Stejně jako jakýkoli jiný prostředek Azure můžete ke sdílení specifikace šablony použít řízení přístupu na základě role v Azure (Azure RBAC). Pomocí Azure CLI nebo Azure PowerShellu můžete vytvořit specifikace šablon tím, že poskytnete soubory Bicep. Soubory Bicep se před uložením překládají do šablon JSON ARM. Z webu Azure Portal nemůžete importovat soubor Bicep a vytvořit v tuto chvíli prostředek specifikace šablony.

Microsoft.Resources/templateSpecs je typ prostředku pro specifikace šablon. Skládá se z hlavní šablony a libovolného počtu propojených šablon. Azure bezpečně ukládá specifikace šablon ve skupinách prostředků. Hlavní i propojené šablony musí být ve formátu JSON. Specifikace šablon podporují správu verzí.

Pokud chcete nasadit specifikaci šablony, použijte standardní nástroje Azure, jako jsou PowerShell, Azure CLI, Azure Portal, REST a další podporované sady SDK a klienti. Použijete stejné příkazy jako pro šablonu nebo soubor Bicep.

Poznámka:

Pokud chcete použít specifikace šablon v Bicep s Azure PowerShellem, musíte nainstalovat verzi 6.3.0 nebo novější. Pokud ho chcete použít s Azure CLI, použijte verzi 2.27.0 nebo novější.

Při navrhování nasazení vždy zvažte životní cyklus prostředků a seskupte prostředky, které sdílejí podobný životní cyklus, do specifikace jedné šablony. Vaše nasazení například zahrnují několik instancí služby Azure Cosmos DB s každou instancí, která obsahuje vlastní databáze a kontejnery. Vzhledem k tomu, že databáze a kontejnery se moc nemění, chcete vytvořit jednu specifikaci šablony, která zahrnuje instanci databáze Cosmo a její podkladové databáze a kontejnery. Podmíněné příkazy pak můžete použít v Bicep spolu se smyčkami kopírování k vytvoření více instancí těchto prostředků.

Tip

Volba mezi registrem modulů a specifikacemi šablon je většinou otázkou preference. Při výběru mezi těmito dvěma možnostmi je potřeba vzít v úvahu několik věcí:

Registr modulů podporuje pouze Bicep. Pokud ještě nepoužíváte Bicep, použijte specifikace šablon.
Obsah v registru modulu Bicep lze nasadit pouze z jiného souboru Bicep. Specifikace šablon je možné nasadit přímo z rozhraní API, Azure PowerShellu, Azure CLI a webu Azure Portal. Můžete dokonce použít UiFormDefinition k přizpůsobení prostředí nasazení na webu Azure Portal.
Bicep má několik omezených možností pro vkládání jiných artefaktů projektu (včetně souborů mimo Bicep a souborů bez šablony ARM). Například skripty PowerShellu, skripty rozhraní příkazového řádku a další binární soubory) pomocí funkcí loadTextContent a loadFileAsBase64 funkcí. Specifikace šablon nemohou tyto artefakty zabalit.

Požadována oprávnění

Do Azure se zabudují dvě role a definují se pro specifikace šablon:

Kromě toho potřebujete také oprávnění k nasazení souboru Bicep. Viz Nasazení souborů Bicep pomocí Azure CLI nebo Azure PowerShellu.

Proč používat specifikace šablon

Specifikace šablon poskytují následující výhody:

Pro specifikaci šablony použijete standardní šablony ARM nebo soubory Bicep.
Přístup spravujete prostřednictvím Azure RBAC místo tokenů sdíleného přístupového podpisu.
Uživatelé mohou nasadit specifikaci šablony bez přístupu k zápisu do souboru Bicep.
Specifikaci šablony můžete integrovat do existujícího procesu nasazení, jako je skript PowerShellu nebo kanál DevOps.

Specifikace šablon umožňují vytvářet kanonické šablony a sdílet je s týmy ve vaší organizaci. Specifikace šablon jsou zabezpečené, protože jsou dostupné pro Azure Resource Manager pro nasazení, ale nejsou přístupné uživatelům bez správného oprávnění. Uživatelé potřebují ke specifikaci šablony přístup jen pro čtení, abyste mohli šablonu nasadit, abyste ji mohli sdílet bez toho, aby ji ostatní mohli upravovat.

Pokud aktuálně máte šablony v úložišti GitHubu nebo účtu úložiště, při pokusu o sdílení a používání šablon narazíte na několik problémů. Pokud chcete šablonu nasadit, musíte šablonu nastavit jako veřejně přístupnou nebo spravovat přístup pomocí tokenů SAS. Pokud chcete toto omezení obejít, můžou uživatelé vytvářet místní kopie, které se nakonec liší od původní šablony. Specifikace šablon zjednodušují sdílení šablon.

Šablony, které zahrnete do specifikace šablony, by měli ověřit správci ve vaší organizaci, aby postupovali podle požadavků a pokynů organizace.

Vytvoření specifikace šablony

Následující příklad ukazuje jednoduchý soubor Bicep pro vytvoření účtu úložiště v Azure.

@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'
}

Vytvořte specifikaci šablony pomocí:

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"

Soubory Bicep můžete také použít k vytvoření specifikací šablony. Obsah mainTemplate ale musí být ve formátu JSON. Následující šablona vytvoří specifikaci šablony pro nasazení účtu úložiště:

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\')]'
          }
        }
      ]
    }
  }
}

Šablona JSON vložená do souboru Bicep musí provést tyto změny:

Odeberte čárky na konci řádků.
Dvojité uvozovky nahraďte jednoduchými uvozovkami.
Uvozovky v rámci výrazů uvozovek uvozovek. Například 'name': '[parameters(\'storageAccountType\')]'.
Pokud chcete získat přístup k parametrům a proměnným definovaným v souboru Bicep, můžete přímo použít názvy parametrů a názvy proměnných. Pokud chcete získat přístup k parametrům a proměnným definovaným v mainTemplate, musíte stále použít syntaxi šablony JSON ARM. Například 'name': '[parameters(\'storageAccountType\')]'.
K volání funkcí Bicep použijte syntaxi Bicep. Například location: resourceGroup().location.

Velikost specifikace šablony je omezená na přibližné 2 megabajty. Pokud velikost specifikace šablony překročí limit, získáte kód chyby TemplateSpecTooLarge . Chybová zpráva říká:

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.

Všechny specifikace šablon ve vašem předplatném můžete zobrazit pomocí:

Azure PowerShell
Azure CLI

Get-AzTemplateSpec

az ts list

Můžete zobrazit podrobnosti o specifikaci šablony, včetně jeho verzí:

Azure PowerShell
Azure CLI

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

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

Nasazení specifikace šablony

Po vytvoření specifikace šablony ji můžou uživatelé s rolí Čtenář specifikací šablony nasadit. Nezapomeňte, že k nasazení šablony ARM potřebujete příslušná oprávnění .

Specifikace šablon je možné nasadit prostřednictvím webu Azure Portal, PowerShellu, Azure CLI nebo modulu Bicep ve větším nasazení šablony. Uživatelé v organizaci můžou nasadit specifikaci šablony do libovolného oboru v Azure (např. skupinu prostředků, předplatné, skupinu pro správu nebo tenanta).

Specifikaci šablony nasadíte tak, že místo předání do cesty nebo identifikátoru URI pro soubor Bicep poskytnete jeho ID prostředku. ID prostředku má následující formát; Všimněte si, že obsahuje název verze pro specifikaci šablony:

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

Specifikaci šablony můžete nasadit pomocí následujících příkazů:

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

V praxi obvykle spustíte Get-AzTemplateSpec nebo az ts show získáte ID specifikace šablony, kterou chcete nasadit.

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

Specifikaci šablony můžete nasadit také tak, že otevřete adresu URL v následujícím formátu:

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}

Parametry

Předávání parametrů specifikaci šablony se podobá předávání parametrů do souboru Bicep. Přidejte hodnoty parametrů buď vložené, nebo do souboru parametrů.

Vložené parametry

Pokud chcete předat vložený parametr, použijte:

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'

Soubory parametrů

Použijte soubory parametrů Bicep.

Musíte zadat using příkaz pro vytvoření souboru parametrů Bicep. Příklad:
```
using 'using 'ts:<subscription-id>/<resource-group-name>/<template-spec-name>:<tag>'

param StorageAccountType = 'Standard_GRS'
```
Další informace najdete v tématu Vytvoření souborů parametrů pro nasazení Bicep.

Předání souborů parametrů s:
- Azure PowerShell
- Azure CLI
V tuto chvíli nemůžete pomocí PowerShellu nasadit specifikaci šablony se souborem.bicepparam.
```
az deployment group create \
  --resource-group demoRG \
  --parameters "./mainTemplate.bicepparam"
```
Parametr nemusíte zadávat --template-spec kvůli using příkazu v .bicepparam souboru.

Použijte soubory parametrů JSON.

Následující JSON je ukázkový soubor parametrů JSON:

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

Soubor parametrů můžete předat také pomocí:

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"

Vytváření verzí

Název verze pro specifikaci šablony zadáte při jeho vytvoření. Při iteraci kódu šablony můžete buď aktualizovat existující verzi (pro opravy hotfix), nebo publikovat novou verzi. Verze je textový řetězec. Můžete postupovat podle libovolného systému správy verzí, včetně sémantické správy verzí. Uživatelé specifikace šablony můžou zadat název verze, kterou chtějí použít při nasazování, a mohou mít neomezený počet verzí.

Použití značek

Značky pomáhají logicky uspořádat prostředky. K přidání značek do specifikací šablon můžete použít Azure PowerShell nebo Azure CLI. Následující příklad ukazuje, jak určit značky při vytváření specifikace šablony:

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

Následující příklad ukazuje, jak použít značky při aktualizaci existující specifikace šablony:

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

Šablona i její verze můžou mít značky. Značky se použijí nebo zdědí v závislosti na zadaných parametrech:

Specifikace šablony	Verze	Parametr verze	Parametr značky	Hodnoty značek
Exists	–	Neurčeno	Určeno	použité na specifikaci šablony
Exists	Nová	Určeno	Neurčeno	zděděno ze specifikace šablony do verze
Nová	Nová	Určeno	Určeno	použito pro specifikaci šablony i verzi
Exists	Nová	Určeno	Určeno	použitou na verzi
Exists	Exists	Určeno	Určeno	použitou na verzi

Odkaz na specifikace šablony

Po vytvoření specifikace šablony můžete tuto specifikaci šablony propojit v modulu Bicep. Specifikace šablony se nasadí při nasazení souboru Bicep obsahujícího tento modul. Další informace najdete v tématu Cesta k modulu.
Pokud chcete vytvořit aliasy pro specifikace šablon určené pro propojení modulů, přečtěte si téma Aliasy pro moduly.

Další kroky

Další informace a praktické pokyny ke specifikacím šablon najdete v knihovnách publikování opakovaně použitelného kódu infrastruktury pomocí modulu Learn se specifikacemi šablon.

Sdílet prostřednictvím