Vysvětlení struktury a syntaxe šablon ARM

Tento článek popisuje strukturu šablony Azure Resource Manager (šablona ARM). Zobrazí různé oddíly šablony a vlastnosti, které jsou v těchto oddílech k dispozici.

Tento článek je určený pro uživatele, kteří mají zkušenosti se šablonami ARM. Poskytuje podrobné informace o struktuře šablony. Podrobný kurz, který vás provede procesem vytvoření šablony, najdete v tématu Kurz: Vytvoření a nasazení první šablony ARM. Další informace o šablonách ARM prostřednictvím sady modulů Learn najdete v tématu Nasazení a správa prostředků v Azure pomocí šablon ARM.

Tip

Bicep je nový jazyk, který nabízí stejné funkce jako šablony ARM, ale se syntaxí, která se snadněji používá. Pokud zvažujete infrastrukturu jako možnosti kódu, doporučujeme se podívat na Bicep.

Informace o prvcích souboru Bicep najdete v tématu Vysvětlení struktury a syntaxe souborů Bicep.

Formát šablon

V nejjednodušší struktuře má šablona následující prvky:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "",
  "apiProfile": "",
  "parameters": {  },
  "variables": {  },
  "functions": [  ],
  "resources": [  ],
  "outputs": {  }
}
Název elementu Povinné Popis
$schema Yes Umístění souboru schématu JSON (JavaScript Object Notation), který popisuje verzi jazyka šablony. Použité číslo verze závisí na rozsahu nasazení a editoru JSON.

Pokud používáte Visual Studio Code s rozšířením nástrojů Azure Resource Manager, použijte nejnovější verzi pro nasazení skupin prostředků:
https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#

Jiné editory (včetně sady Visual Studio) nemusí toto schéma zpracovat. Pro tyto editory použijte:
https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#

Pro nasazení předplatného použijte:
https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#

Pro nasazení skupin pro správu použijte:
https://schema.management.azure.com/schemas/2019-08-01/managementGroupDeploymentTemplate.json#

Pro nasazení tenanta použijte:
https://schema.management.azure.com/schemas/2019-08-01/tenantDeploymentTemplate.json#
contentVersion Yes Verze šablony (například 1.0.0.0.0). Pro tento prvek můžete zadat libovolnou hodnotu. Pomocí této hodnoty můžete zdokumentovat významné změny v šabloně. Při nasazování prostředků pomocí šablony je možné tuto hodnotu použít k zajištění použití správné šablony.
apiProfile No Verze rozhraní API, která slouží jako kolekce verzí rozhraní API pro typy prostředků. Tuto hodnotu použijte, abyste nemuseli zadávat verze rozhraní API pro každý prostředek v šabloně. Když zadáte verzi profilu rozhraní API a nezadáte verzi rozhraní API pro typ prostředku, Resource Manager použije verzi rozhraní API pro tento typ prostředku, který je definován v profilu.

Vlastnost profilu rozhraní API je zvlášť užitečná při nasazování šablony do různých prostředí, jako je Azure Stack a globální Azure. Pomocí verze profilu rozhraní API se ujistěte, že vaše šablona automaticky používá verze podporované v obou prostředích. Seznam aktuálních verzí profilu rozhraní API a verzí rozhraní API prostředků definovaných v profilu najdete v tématu Profil rozhraní API.

Další informace najdete v tématu Sledování verzí pomocí profilů rozhraní API.
parameters No Hodnoty, které jsou poskytovány při spuštění nasazení, aby se přizpůsobilo nasazení prostředků.
Proměnné No Hodnoty používané jako fragmenty JSON v šabloně pro zjednodušení výrazů jazyka šablony
Funkce No Uživatelem definované funkce, které jsou dostupné v rámci šablony.
Zdroje Yes Typy prostředků nasazené nebo aktualizované ve skupině prostředků nebo předplatném
Výstupy No Hodnoty, které se vrátí po nasazení.

Každý prvek má vlastnosti, které můžete nastavit. Tento článek podrobně popisuje oddíly šablony.

Parametry

parameters V části šablony určíte, které hodnoty můžete zadat při nasazování prostředků. V šabloně jste omezeni na 256 parametrů . Počet parametrů můžete snížit pomocí objektů, které obsahují více vlastností.

Následují dostupné vlastnosti pro parametr:

"parameters": {
  "<parameter-name>" : {
    "type" : "<type-of-parameter-value>",
    "defaultValue": "<default-value-of-parameter>",
    "allowedValues": [ "<array-of-allowed-values>" ],
    "minValue": <minimum-value-for-int>,
    "maxValue": <maximum-value-for-int>,
    "minLength": <minimum-length-for-string-or-array>,
    "maxLength": <maximum-length-for-string-or-array-parameters>,
    "metadata": {
      "description": "<description-of-the parameter>"
    }
  }
}
Název elementu Povinné Popis
název parametru Yes Název parametru Musí být platný identifikátor JavaScriptu.
typ Yes Typ hodnoty parametru. Povolené typy a hodnoty jsou řetězce, securestring, int, bool, object, secureObject a array. Viz Datové typy v šablonách ARM.
Defaultvalue No Výchozí hodnota parametru, pokud parametr neobsahuje žádnou hodnotu.
Allowedvalues No Pole povolených hodnot pro parametr, aby se zajistilo, že je zadaná správná hodnota.
Minvalue No Minimální hodnota parametrů typu int je tato hodnota inkluzivní.
Maxvalue No Maximální hodnota parametrů typu int je tato hodnota inkluzivní.
Minlength No Minimální délka parametrů řetězce, zabezpečeného řetězce a typu pole je tato hodnota inkluzivní.
Maxlength No Maximální délka parametrů řetězce, zabezpečeného řetězce a typu pole je tato hodnota inkluzivní.
description No Popis parametru, který se zobrazí uživatelům prostřednictvím portálu. Další informace najdete v tématu Komentáře v šablonách.

Příklady použití parametrů najdete v tématu Parametry v šablonách ARM.

V Bicep viz parametry.

Proměnné

variables V části vytvoříte hodnoty, které lze použít v celé šabloně. Nemusíte definovat proměnné, ale často zjednodušují šablonu snížením složitých výrazů. Formát každé proměnné odpovídá jednomu z datových typů. V šabloně jste omezeni na 256 proměnných .

Následující příklad ukazuje dostupné možnosti pro definování proměnné:

"variables": {
  "<variable-name>": "<variable-value>",
  "<variable-name>": {
    <variable-complex-type-value>
  },
  "<variable-object-name>": {
    "copy": [
      {
        "name": "<name-of-array-property>",
        "count": <number-of-iterations>,
        "input": <object-or-value-to-repeat>
      }
    ]
  },
  "copy": [
    {
      "name": "<variable-array-name>",
      "count": <number-of-iterations>,
      "input": <object-or-value-to-repeat>
    }
  ]
}

Informace o použití copy k vytvoření několika hodnot pro proměnnou naleznete v tématu Iterace proměnných.

Příklady použití proměnných najdete v tématu Proměnné v šabloně ARM.

V bicep si prohlédněte proměnné.

Functions

V šabloně můžete vytvořit vlastní funkce. Tyto funkce jsou k dispozici pro použití v šabloně. Obvykle definujete složité výrazy, které nechcete opakovat v celé šabloně. Uživatelem definované funkce vytvoříte z výrazů a funkcí podporovaných v šablonách.

Při definování funkce uživatele existují určitá omezení:

  • Funkce nemá přístup k proměnným.
  • Funkce může používat pouze parametry definované v této funkci. Když použijete funkci parametrů v uživatelem definované funkci, omezíte se na parametry této funkce.
  • Funkce nemůže volat jiné uživatelem definované funkce.
  • Funkce nemůže použít referenční funkci.
  • Parametry funkce nemohou mít výchozí hodnoty.
"functions": [
  {
    "namespace": "<namespace-for-functions>",
    "members": {
      "<function-name>": {
        "parameters": [
          {
            "name": "<parameter-name>",
            "type": "<type-of-parameter-value>"
          }
        ],
        "output": {
          "type": "<type-of-output-value>",
          "value": "<function-return-value>"
        }
      }
    }
  }
],
Název elementu Povinné Popis
namespace Yes Obor názvů pro vlastní funkce Umožňuje vyhnout se konfliktům názvů s funkcemi šablony.
function-name Yes Název vlastní funkce. Při volání funkce zkombinujte název funkce s oborem názvů. Pokud například chcete volat funkci pojmenovanou uniqueName v oboru názvů contoso, použijte "[contoso.uniqueName()]".
název parametru No Název parametru, který se má použít v rámci vlastní funkce.
parametr-hodnota No Typ hodnoty parametru. Povolené typy a hodnoty jsou řetězce, securestring, int, bool, object, secureObject a array.
output-type Yes Typ výstupní hodnoty. Výstupní hodnoty podporují stejné typy jako vstupní parametry funkce.
výstupní hodnota Yes Výraz jazyka šablony, který se vyhodnotí a vrátí z funkce.

Příklady použití vlastních funkcí najdete v tématu Uživatelem definované funkce v šabloně ARM.

V Bicep nejsou uživatelem definované funkce podporovány. Bicep podporuje různé funkce a operátory.

Zdroje informací

V části resources definujete prostředky, které se nasazují nebo aktualizují. V šabloně jste omezeni na 800 prostředků .

Prostředky definujete pomocí následující struktury:

"resources": [
  {
      "condition": "<true-to-deploy-this-resource>",
      "type": "<resource-provider-namespace/resource-type-name>",
      "apiVersion": "<api-version-of-resource>",
      "name": "<name-of-the-resource>",
      "comments": "<your-reference-notes>",
      "location": "<location-of-resource>",
      "dependsOn": [
          "<array-of-related-resource-names>"
      ],
      "tags": {
          "<tag-name1>": "<tag-value1>",
          "<tag-name2>": "<tag-value2>"
      },
      "identity": {
        "type": "<system-assigned-or-user-assigned-identity>",
        "userAssignedIdentities": {
          "<resource-id-of-identity>": {}
        }
      },
      "sku": {
          "name": "<sku-name>",
          "tier": "<sku-tier>",
          "size": "<sku-size>",
          "family": "<sku-family>",
          "capacity": <sku-capacity>
      },
      "kind": "<type-of-resource>",
      "scope": "<target-scope-for-extension-resources>",
      "copy": {
          "name": "<name-of-copy-loop>",
          "count": <number-of-iterations>,
          "mode": "<serial-or-parallel>",
          "batchSize": <number-to-deploy-serially>
      },
      "plan": {
          "name": "<plan-name>",
          "promotionCode": "<plan-promotion-code>",
          "publisher": "<plan-publisher>",
          "product": "<plan-product>",
          "version": "<plan-version>"
      },
      "properties": {
          "<settings-for-the-resource>",
          "copy": [
              {
                  "name": ,
                  "count": ,
                  "input": {}
              }
          ]
      },
      "resources": [
          "<array-of-child-resources>"
      ]
  }
]
Název elementu Povinné Popis
Podmínka No Logická hodnota, která označuje, jestli se prostředek během tohoto nasazení zřídí. Když truese prostředek vytvoří během nasazení. Pokud falsese prostředek pro toto nasazení přeskočí. Viz podmínka.
typ Yes Typ prostředku. Tato hodnota je kombinací oboru názvů poskytovatele prostředků a typu prostředku (například Microsoft.Storage/storageAccounts). Pokud chcete určit dostupné hodnoty, přečtěte si referenční informace k šabloně. U podřízeného prostředku závisí formát typu na tom, jestli je vnořený do nadřazeného prostředku nebo definovaný mimo nadřazený prostředek. Viz Nastavení názvu a typu podřízených prostředků.
apiVersion Yes Verze rozhraní REST API, která se má použít k vytvoření prostředku. Při vytváření nové šablony nastavte tuto hodnotu na nejnovější verzi prostředku, který nasazujete. Pokud šablona funguje podle potřeby, pokračujte ve stejné verzi rozhraní API. Když budete dál používat stejnou verzi rozhraní API, minimalizujete riziko nové verze rozhraní API, která mění způsob fungování šablony. Zvažte aktualizaci verze rozhraní API pouze v případě, že chcete použít novou funkci, která je zavedena v novější verzi. Pokud chcete určit dostupné hodnoty, přečtěte si referenční informace k šabloně.
name Yes Název prostředku. Název musí dodržovat omezení součástí identifikátoru URI definovaná v dokumentu RFC3986. Služby Azure, které zpřístupňují název prostředku externím stranám, ověřují název, aby se ujistily, že se nejedná o pokus o falšování jiné identity. U podřízeného prostředku závisí formát názvu na tom, jestli je vnořený do nadřazeného prostředku nebo definovaný mimo nadřazený prostředek. Viz Nastavení názvu a typu podřízených prostředků.
komentáře No Poznámky pro dokumentování prostředků v šabloně Další informace najdete v tématu Komentáře v šablonách.
location Různé Podporovaná geografická umístění poskytnutého prostředku. Můžete vybrat libovolnou z dostupných umístění, ale obvykle je vhodné vybrat si jednu, která je blízko vašim uživatelům. Obvykle také dává smysl umístit prostředky, které vzájemně spolupracují ve stejné oblasti. Většina typů prostředků vyžaduje umístění, ale některé typy (například přiřazení role) nevyžadují umístění. Viz Nastavení umístění prostředku.
dependsOn No Prostředky, které musí být nasazeny před nasazením tohoto prostředku. Resource Manager vyhodnotí závislosti mezi prostředky a nasadí je ve správném pořadí. Pokud prostředky nejsou závislé na sobě, nasadí se paralelně. Hodnota může být seznam názvů prostředků nebo jedinečných identifikátorů prostředků oddělených čárkami. Uveďte pouze prostředky nasazené v této šabloně. Prostředky, které nejsou definovány v této šabloně, už musí existovat. Vyhněte se přidávání nepotřebných závislostí, protože můžou zpomalit nasazení a vytvářet cyklické závislosti. Pokyny k nastavení závislostí najdete v tématu Definování pořadí nasazení prostředků v šablonách ARM.
tags No Značky přidružené k prostředku Použijte značky k logickému uspořádání prostředků v rámci vašeho předplatného.
identity No Některé prostředky podporují spravované identity pro prostředky Azure. Tyto prostředky mají objekt identity na kořenové úrovni deklarace prostředku. Můžete nastavit, jestli je identita přiřazená uživatelem nebo systémem. Pro identity přiřazené uživatelem zadejte seznam ID prostředků pro identity. Nastavte klíč na ID prostředku a hodnotu na prázdný objekt. Další informace najdete v tématu Konfigurace spravovaných identit pro prostředky Azure na virtuálním počítači Azure pomocí šablon.
Sku No Některé prostředky umožňují hodnoty, které definují skladovou položku k nasazení. Můžete například zadat typ redundance pro účet úložiště.
Druhu No Některé prostředky umožňují hodnotu, která definuje typ nasazeného prostředku. Můžete například zadat typ služby Cosmos DB, který chcete vytvořit.
scope No Vlastnost oboru je k dispozici pouze pro typy prostředků rozšíření. Použijte ho při zadávání oboru, který se liší od oboru nasazení. Viz Nastavení oboru pro prostředky rozšíření v šablonách ARM.
kopírování No Pokud je potřeba více instancí, počet prostředků, které se mají vytvořit. Výchozí režim je paralelní. Pokud nechcete, aby se nasadily všechny prostředky nebo prostředky najednou, zadejte sériový režim. Další informace najdete v tématu Vytvoření několika instancí prostředků v Azure Resource Manager.
Plán No Některé prostředky umožňují hodnoty, které definují plán nasazení. Můžete například zadat image marketplace pro virtuální počítač.
properties No Nastavení konfigurace specifické pro prostředky Hodnoty vlastností jsou stejné jako hodnoty, které zadáte v textu požadavku pro operaci REST API (METODA PUT) k vytvoření prostředku. Můžete také zadat pole kopírování pro vytvoření několika instancí vlastnosti. Informace o určení dostupných hodnot najdete v referenčních informacích k šabloně.
resources No Podřízené prostředky, které závisí na definovaném prostředku. Zadejte pouze typy prostředků, které jsou povoleny schématem nadřazeného prostředku. Závislost na nadřazený prostředek není implicitní. Tuto závislost musíte explicitně definovat. Viz Nastavení názvu a typu pro podřízené prostředky.

V Bicep najdete zdroje informací.

Výstupy

outputs V části zadáte hodnoty, které se vrátí z nasazení. Obvykle vrátíte hodnoty z nasazených prostředků. V šabloně jsou omezené na 64 výstupů .

Následující příklad ukazuje strukturu definice výstupu:

"outputs": {
  "<output-name>": {
    "condition": "<boolean-value-whether-to-output-value>",
    "type": "<type-of-output-value>",
    "value": "<output-value-expression>",
    "copy": {
      "count": <number-of-iterations>,
      "input": <values-for-the-variable>
    }
  }
}
Název elementu Povinné Popis
output-name Yes Název výstupní hodnoty. Musí to být platný identifikátor JavaScriptu.
Podmínka No Logická hodnota označující, zda je tato výstupní hodnota vrácena. Pokud trueje hodnota zahrnuta ve výstupu pro nasazení. Pokud falsese výstupní hodnota pro toto nasazení přeskočí. Pokud není zadána, výchozí hodnota je true.
typ Yes Typ výstupní hodnoty Výstupní hodnoty podporují stejné typy jako vstupní parametry šablony. Pokud zadáte zabezpečený řetězec pro typ výstupu, hodnota se v historii nasazení nezobrazí a nelze ji načíst z jiné šablony. Pokud chcete použít hodnotu tajného kódu ve více než jedné šabloně, uložte tajný kód do Key Vault a odkazujte na tajný kód v souboru parametrů. Další informace najdete v tématu Použití Azure Key Vault k předání hodnoty zabezpečeného parametru během nasazování.
hodnota No Výraz jazyka šablony, který se vyhodnotí a vrátí jako výstupní hodnota. Zadejte hodnotu nebo kopii.
kopírování No Slouží k vrácení více než jedné hodnoty pro výstup. Zadejte hodnotu nebo zkopírujte. Další informace najdete v tématu Iterace výstupu v šablonách ARM.

Příklady použití výstupů najdete v tématu Výstupy v šabloně ARM.

V bicep se podívejte na výstupy.

Komentáře a metadata

Máte několik možností pro přidání komentářů a metadat do šablony.

Komentáře

Pro vložené komentáře můžete použít buď // nebo /* ... */. V editoru Visual Studio Code uložte soubory parametrů s komentáři jako soubor JSON s typem souboru JSONC (Comments not permitted in JSONC), jinak se zobrazí chybová zpráva s informací, že komentáře nejsou ve formátu JSON povolené.

Poznámka

Při nasazování šablon s komentáři pomocí Azure CLI použijte verzi 2.3.0 nebo novější a zadejte --handle-extended-json-format přepínač.

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[parameters('location')]", //defaults to resource group location
  "dependsOn": [ /* storage account and network interface must be deployed first */
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

Rozšíření Azure Resource Manager Tools v editoru Visual Studio Code dokáže automaticky rozpoznat šablonu ARM a změnit režim jazyka. Pokud se v pravém dolním rohu editoru Visual Studio Code zobrazí šablona Azure Resource Manager, můžete použít vložené komentáře. Vložené komentáře už nejsou označené jako neplatné.

Visual Studio Code Azure Resource Manager režim šablony

V Bicep se podívejte na komentáře.

Metadata

Objekt můžete přidat metadata téměř kdekoli v šabloně. Resource Manager objekt ignoruje, ale editor JSON vás může upozornit, že vlastnost není platná. V objektu definujte požadované vlastnosti.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "comments": "This template was developed for demonstration purposes.",
    "author": "Example Name"
  },

Pro parameters, přidat metadata objekt s description vlastností.

"parameters": {
  "adminUsername": {
    "type": "string",
    "metadata": {
      "description": "User name for the Virtual Machine."
    }
  },

Při nasazování šablony prostřednictvím portálu se text zadaný v popisu automaticky použije jako tip pro tento parametr.

Zobrazit tip parametrů

Pro resources, přidat comments prvek nebo metadata objekt. Následující příklad ukazuje comments prvek i metadata objekt.

"resources": [
  {
    "type": "Microsoft.Storage/storageAccounts",
    "apiVersion": "2018-07-01",
    "name": "[concat('storage', uniqueString(resourceGroup().id))]",
    "comments": "Storage account used to store VM disks",
    "location": "[parameters('location')]",
    "metadata": {
      "comments": "These tags are needed for policy compliance."
    },
    "tags": {
      "Dept": "[parameters('deptName')]",
      "Environment": "[parameters('environment')]"
    },
    "sku": {
      "name": "Standard_LRS"
    },
    "kind": "Storage",
    "properties": {}
  }
]

Pro outputs, přidat metadata objekt do výstupní hodnoty.

"outputs": {
  "hostname": {
    "type": "string",
    "value": "[reference(variables('publicIPAddressName')).dnsSettings.fqdn]",
    "metadata": {
      "comments": "Return the fully qualified domain name"
    }
  },

Objekt nelze přidat metadata do uživatelem definovaných funkcí.

Víceřádkové řetězce

Řetězec můžete rozdělit na více řádků. Podívejte se například na location vlastnost a jeden z komentářů v následujícím příkladu JSON.

Poznámka

Pokud chcete nasadit šablony s víceřádkovými řetězci, použijte Azure PowerShell nebo Azure CLI. Pro rozhraní příkazového řádku použijte verzi 2.3.0 nebo novější a zadejte --handle-extended-json-format přepínač.

Víceřádkové řetězce nejsou podporovány při nasazování šablony prostřednictvím Azure Portal, kanálu DevOps nebo rozhraní REST API.

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[
    parameters('location')
    ]", //defaults to resource group location
  /*
    storage account and network interface
    must be deployed first
  */
  "dependsOn": [
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

V bicep si projděte víceřádkové řetězce.

Další kroky