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ří znají šablony 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 s asistencí 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 podívat se na Bicep.

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

Formát šablon

Šablona má ve své nejjednodušší struktuře 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 Azure Resource Manager tools, použijte pro nasazení skupin prostředků nejnovější verzi:
https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#

Jiné editory (včetně sady Visual Studio) nemusí být schopny 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). Pro tento prvek můžete zadat libovolnou hodnotu. Tato hodnota slouží k dokumentaci významných změn v šabloně. Při nasazování prostředků pomocí šablony je možné tuto hodnotu použít k zajištění, že se používá správná šablona.
apiProfile Ne 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 daný typ prostředku, který je definovaný 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 š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 Ne Hodnoty, které se zadají při spuštění nasazení pro přizpůsobení nasazení prostředků.
Proměnné Ne Hodnoty, které se v šabloně používají jako fragmenty JSON, aby se zjednodušily výrazy jazyka šablony.
Funkce Ne Uživatelem definované funkce, které jsou k dispozici v rámci šablony.
Zdroje Yes Typy prostředků nasazené nebo aktualizované ve skupině prostředků nebo předplatném.
Výstupy Ne Hodnoty, které se vrátí po nasazení.

Každý prvek má vlastnosti, které můžete nastavit. Tento článek podrobněji 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í to být platný identifikátor JavaScriptu.
typ Yes Typ hodnoty parametru. Povolené typy a hodnoty jsou string, securestring, int, bool, object, secureObject a array. Viz Datové typy v šablonách ARM.
Defaultvalue Ne Výchozí hodnota parametru, pokud pro parametr není zadaná žádná hodnota.
Allowedvalues Ne Pole povolených hodnot pro parametr, aby se zajistilo, že je zadaná správná hodnota.
Minvalue Ne Minimální hodnota parametrů typu int je včetně.
Maxvalue Ne Maximální hodnota parametrů typu int je včetně.
Minlength Ne Minimální délka parametrů řetězce, zabezpečeného řetězce a typu pole je tato hodnota včetně.
Maxlength Ne Maximální délka parametrů řetězce, zabezpečeného řetězce a typu pole je tato hodnota včetně.
description Ne Popis parametru, který se uživatelům zobrazí 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 nástroji Bicep si projděte parametry.

Proměnné

V části variables vytvoříte hodnoty, které se dají použít v celé šabloně. Proměnné nemusíte definovat, ale často zjednodušují šablonu tím, že zmenšují složité výrazy. 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 najdete v tématu Iterace proměnné.

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

V nástroji Bicep se podívejte na proměnné.

Functions

V rámci šablony můžete vytvářet 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 můžete vytvořit z výrazů a funkcí podporovaných v šablonách.

Při definování uživatelské funkce platí určitá omezení:

  • Funkce nemá přístup k proměnným.
  • Funkce může používat pouze parametry, které jsou definovány ve funkci. Když použijete funkci parametrů v rámci uživatelem definované funkce, budete omezeni 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. Slouží k zabránění konfliktům názvů s funkcemi šablony.
název funkce Yes Název vlastní funkce Při volání funkce zkombinujte název funkce s oborem názvů. Pokud například chcete volat funkci s názvem uniqueName v oboru názvů contoso, použijte "[contoso.uniqueName()]".
název parametru Ne Název parametru, který se má použít v rámci vlastní funkce.
parameter-value Ne Typ hodnoty parametru. Povolené typy a hodnoty jsou string, securestring, int, bool, object, secureObject a array.
output-type Yes Typ výstupní hodnoty. Výstupní hodnoty podporují stejné typy jako vstupní parametry funkce.
output-value Yes Výraz jazyka šablony, který je vyhodnocen a vrácen z funkce.

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

V Bicepu se uživatelem definované funkce nepodporují. Bicep podporuje celou řadu funkcí a operátorů.

Zdroje informací

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

Prostředky definujete s následující strukturou:

"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 Ne Logická hodnota označující, jestli se prostředek zřídí během tohoto nasazení. Když truese prostředek vytvoří během nasazení. Když 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). Informace o určení dostupných hodnot najdete v referenčních informacích k šabloně. U podřízeného prostředku závisí formát typu na tom, jestli je vnořený v nadřazený prostředek nebo definovaný mimo nadřazený prostředek. Viz Nastavení názvu a typu pro podřízené prostředky.
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. Dokud šablona funguje podle potřeby, použijte stejnou verzi rozhraní API. Pokud budete dál používat stejnou verzi rozhraní API, minimalizujete riziko, že nová verze rozhraní API změní způsob fungování šablony. Aktualizaci verze rozhraní API zvažte pouze v případech, kdy chcete použít novou funkci, která je zavedena v novější verzi. Informace o určení dostupných hodnot najdete v referenčních informacích k šabloně.
name Yes Název prostředku. Název musí dodržovat omezení komponent identifikátoru URI definovaná v 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ý v nadřazený prostředek nebo definovaný mimo nadřazený prostředek. Viz Nastavení názvu a typu pro podřízené prostředky.
komentáře Ne Poznámky k dokumentaci 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 libovolné z dostupných umístění, ale obvykle má smysl vybrat umístění, které je blízko vašim uživatelům. Obvykle má také smysl umístit prostředky, které spolu vzájemně spolupracují, do 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 Ne Prostředky, které je potřeba nasadit 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 na sobě závislé, nasazují se paralelně. Hodnota může být čárkami oddělený seznam názvů prostředků nebo jedinečných identifikátorů prostředků. Vypište pouze prostředky nasazené v této šabloně. Prostředky, které nejsou definované v této šabloně, už musí existovat. Vyhněte se přidávání zbytečných závislostí, protože můžou zpomalit vaše nasazení a vytvořit cyklické závislosti. Pokyny k nastavení závislostí najdete v tématu Definování pořadí nasazení prostředků v šablonách ARM.
tags Ne 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 Ne 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 tyto 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 Ne 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 Ne Některé prostředky umožňují hodnotu, která definuje typ prostředku, který nasazujete. Můžete například zadat typ instance Azure Cosmos DB, která se má vytvořit.
scope Ne Vlastnost scope 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 rozšiřující prostředky v šablonách ARM.
kopírování Ne Pokud je potřeba více než jedna instance, 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 Ne 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 Ne 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 Ne Podřízené prostředky, které závisí na definovaném prostředku. Zadejte pouze typy prostředků, které jsou povolené schématem nadřazeného prostředku. Závislost na nadřazených prostředcích není implicitní. Tuto závislost musíte explicitně definovat. Viz Nastavení názvu a typu pro podřízené prostředky.

V bicepu si projděte prostředky.

Výstupy

outputs V části zadáte hodnoty, které se vrátí z nasazení. Obvykle vracíte hodnoty z prostředků, které byly nasazeny. V šabloně jste omezeni 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 Ne Logická hodnota označující, zda je tato výstupní hodnota vrácena. Pokud trueje hodnota zahrnutá ve výstupu pro nasazení. Při falsepřeskočení výstupní hodnoty pro toto nasazení. Pokud není zadán, výchozí hodnota je true.
typ Yes Typ výstupní hodnoty. Výstupní hodnoty podporují stejné typy jako vstupní parametry šablony. Pokud pro typ výstupu zadáte securestring , hodnota se nezobrazí v historii nasazení a nedá se načíst z jiné šablony. Pokud chcete použít hodnotu tajného klíče ve více než jedné šabloně, uložte tajný klíč do Key Vault a odkazujte na tajný klíč 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 nasazení.
hodnota Ne Výraz jazyka šablony, který je vyhodnocen a vrácen jako výstupní hodnota. Zadejte hodnotu nebo kopii.
kopírování Ne Slouží k vrácení více než jedné hodnoty výstupu. 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 bicepu si projděte výstupy.

Komentáře a metadata

Máte několik možností, jak do šablony přidat komentáře a metadata.

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 typ souboru JSON s komentáři (JSONC), jinak se zobrazí chybová zpráva Komentáře nejsou povolené ve formátu JSON.

Poznámka

Pokud k nasazení šablon s komentáři používáte 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'))]"
  ],

V editoru Visual Studio Code může rozšíření Azure Resource Manager Tools 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é.

Režim šablony Azure Resource Manager editoru Visual Studio Code

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

Metadata

Objekt můžete přidat metadata téměř kamkoli do šablony. Resource Manager objekt ignoruje, ale editor JSON vás může upozornit, že vlastnost není platná. V objektu definujte vlastnosti, které potřebujete.

{
  "$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 parameterspřidejte 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, který zadáte v popisu, automaticky použije jako tip pro tento parametr.

Zobrazit tip k parametru

Pro resourcespřidejte comments prvek nebo metadata objekt. Následující příklad ukazuje element i commentsmetadata 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 outputspřidejte 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 do uživatelem metadata definovaných funkcí.

Víceřádkové řetězce

Řetězec můžete rozdělit na několik řá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 se nepodporují, když šablonu nasazujete 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 nástroji Bicep se podívejte na víceřádkové řetězce.

Další kroky