Vysvětlení struktury a syntaxe šablon ARM

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

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 pomocí příručky sady modulů na Microsoft Learn najdete v tématu nasazení a Správa prostředků v Azure pomocí šablon ARM.

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 JavaScript Object Notation (JSON), 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 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í být schopné zpracovat toto schéma. Pro tyto editory použijte:
https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#

Pro nasazení předplatných 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í klientů 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. Tuto hodnotu použijte k dokumentování významných změn v šabloně. Při nasazování prostředků pomocí šablony můžete tuto hodnotu použít k tomu, abyste se ujistili, že je používána pravá šablona.
apiProfile No Verze rozhraní API, která slouží jako kolekce verzí rozhraní API pro typy prostředků. Tuto hodnotu použijte, chcete-li se vyhnout nutnosti 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, Správce prostředků používá verzi rozhraní API pro tento typ prostředku, který je definovaný v profilu.

Vlastnost profil rozhraní API je užitečná hlavně při nasazení š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, které jsou v obou prostředích podporované. Seznam aktuálních verzí profilů 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.
ukazatelů No Hodnoty, které jsou k dispozici při spuštění nasazení za účelem přizpůsobení nasazení prostředků.
proměnné No Hodnoty, které se používají jako fragmenty JSON v šabloně pro zjednodušení výrazů jazyka šablony.
POZVYHLEDAT No Uživatelsky definované funkce, které jsou k dispozici v rámci šablony.
prostředky Yes Typy prostředků, které se nasazují nebo aktualizují v rámci skupiny prostředků nebo předplatného.
činnosti No Hodnoty, které se vrátí po nasazení.

Každý prvek má vlastnosti, které lze nastavit. V tomto článku jsou podrobněji popsány části šablony.

Parametry

V parameters části šablony určíte, které hodnoty můžete zadat při nasazování prostředků. V šabloně můžete zadat jen 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 String, SecureString, int, bool, Object, secureObject a Array. Podívejte se na datové typy v šablonách ARM.
Hodnot No Výchozí hodnota parametru, pokud není k dispozici žádná hodnota pro parametr.
allowedValues No Pole povolených hodnot pro parametr, aby bylo zajištěno, že je zadána pravá hodnota.
minValue No Minimální hodnota pro parametry typu int je tato hodnota včetně.
maxValue No Maximální hodnota pro parametry typu int je tato hodnota včetně.
minLength No Minimální délka parametrů pro řetězec, zabezpečený řetězec a typ pole je hodnota včetně.
maxLength No Maximální délka parametrů pro řetězec, zabezpečený řetězec a typ pole je hodnota včetně.
description No 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.

Proměnné

V variables části můžete vytvořit hodnoty, které lze použít v celé šabloně. Nemusíte definovat proměnné, ale často zjednodušují vaši šablonu tím, že snižují složité výrazy. Formát každé proměnné odpovídá jednomu z datových typů.

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 příkazu 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.

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 se vytvářejí z výrazů a funkcí podporovaných v šablonách.

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

  • Funkce nemůže získat přístup k proměnným.
  • Funkce může používat pouze parametry, které jsou definovány ve funkci. Při použití funkce parameters v rámci uživatelem definované funkce jste 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 nemají 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 šablon.
název funkce Yes Název vlastní funkce. Při volání funkce zkombinujte název funkce s oborem názvů . Pokud chcete například volat funkci s názvem 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 string, securestring, int, bool, object, secureObject a array.
output-type (typ výstupu) 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.

Zdroje informací

V resources části definujete prostředky, které se nasadí nebo aktualizují.

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>"
      },
      "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á určuje, jestli se prostředek během tohoto nasazení zřizuje. Když true se vytvoří prostředek během nasazování. V false případě tohoto nasazení se prostředek 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, podívejte se na referenční informace k šablonám. U podřízeného prostředku závisí formát typu na tom, jestli je vnořený v nadřazeném prostředku nebo definovaný mimo nadřazený prostředek. Viz Nastavení názvu a typu pro podřízené prostředky.
apiVersion Yes Verze 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, držte stejnou verzi rozhraní API. Když budete dál používat stejnou verzi rozhraní API, minimalizujete riziko, že nová verze rozhraní API změní způsob, jakým vaše šablona funguje. Aktualizaci verze rozhraní API zvažte pouze v případě, že chcete použít novou funkci, která je zavedená v novější verzi. Pokud chcete určit dostupné hodnoty, podívejte se na referenční informace k šablonám.
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é zveřejňuje název prostředku vnějším stranám, tento název ověří, aby se ujistily, že nejde 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 pro podřízené prostředky.
komentáře No Poznámky ke zdokumentová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 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 také dává smysl umístit prostředky, které spolu vzájemně komunikují, do stejné oblasti. Většina typů prostředků vyžaduje umístění, ale některé typy (například přiřazení role) umístění nevyžadují. 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 vyhodnocuje závislosti mezi prostředky a nasazovat je ve správném pořadí. Pokud na sobě prostředky nejsou závislé, nasadí se paralelně. Hodnotou 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, které jsou 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 mohou zpomalit nasazení a vytvářet cyklické závislosti. Pokyny k nastavení závislostí najdete v tématu Definování pořadí nasazování prostředků v šablonách ARM.
tags No Značky, které jsou 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.
Sku No Některé prostředky umožňují hodnoty, které definují SKU 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 prostředku, který nasadíte. Můžete například zadat typ souboru, Cosmos DB se má vytvořit.
scope No 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 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 vytvoří. Výchozí režim je paralelní. Pokud nechcete, aby se všechny prostředky nebo nasazované prostředky nasadily současně, 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 pro konkrétní prostředky. Hodnoty vlastností jsou stejné jako hodnoty, které poskytnete v textu požadavku pro operaci REST API (metoda PUT) pro vytvoření prostředku. Můžete také zadat pole kopírování a vytvořit několik instancí vlastnosti. Pokud chcete určit dostupné hodnoty, podívejte se na referenční informace k šablonám.
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ém prostředku není implikovaná. Tuto závislost musíte explicitně definovat. Viz Nastavení názvu a typu pro podřízené prostředky.

Výstupy

V outputs části zadáte hodnoty, které se vrátí z nasazení. Obvykle vracíte hodnoty z nasazených prostředků.

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
název výstupu Yes Název výstupní hodnoty. Musí to být platný identifikátor JavaScriptu.
Podmínka No Logická hodnota, která určuje, jestli se tato výstupní hodnota vrátí. Když true se hodnota zahrne do výstupu nasazení. V false případě tohoto nasazení se výstupní hodnota přeskočí. Pokud není zadaný, výchozí hodnota je true .
typ Yes Typ výstupní hodnoty Výstupní hodnoty podporují stejné typy jako vstupní parametry šablony. Pokud jako typ výstupu zadáte securestring, hodnota se nezobrazí v historii nasazení a nelze ji načíst z jiné šablony. Pokud chcete použít hodnotu tajného klíče 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 zkopírujte.
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 Výstupní iterace v šablonách ARM.

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

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 /* ... */ .

Poznámka

Pokud chcete nasadit šablony s komentáři, použijte Azure PowerShell nebo Azure CLI. V případě rozhraní příkazového řádku použijte verzi 2.3.0 nebo novější a zadejte --handle-extended-json-format přepínač .

Komentáře nejsou podporované, pokud nasazujete šablonu prostřednictvím Azure Portal, kanálu DevOps nebo 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
  "dependsOn": [ /* storage account and network interface must be deployed first */
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

V Visual Studio Code rozšíření Azure Resource Manager Tools dokáže automaticky rozpoznat šablonu ARM a změnit režim jazyka. Pokud se Azure Resource Manager v pravém dolním rohu okna zobrazí Visual Studio Code, 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žimu šablony

Metadata

Objekt můžete do metadata šablony přidat téměř kdekoli. Resource Manager objekt ignoruje, ale váš 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 parameters př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ý v popisu zadáte, automaticky použije jako tip pro tento parametr.

Zobrazení tipu parametru

Pro resources přidejte comments prvek nebo objekt metadata . Následující příklad ukazuje element comments 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ř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 metadata 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 řádky řetězců, použijte Azure PowerShell nebo Azure CLI. V případě 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 podporované, pokud nasazujete šablonu prostřednictvím Azure Portal, kanálu DevOps nebo 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'))]"
  ],

Další kroky