Vysvětlení struktury a syntaxe šablon ARM

Tento článek popisuje strukturu šablony Azure Resource Manageru (šablona ARM). Zobrazí různé části š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.

Formát šablony

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "",
  "contentVersion": "",
  "apiProfile": "",
  "definitions": { },
  "parameters": { },
  "variables": { },
  "functions": [ ],
  "resources": [ ], /* or "resources": { } with languageVersion 2.0 */
  "outputs": { }
}

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

Definice

definitions V části šablony zadejte schémata použitá k ověřování hodnot pole a objektů. Definitions lze použít pouze s languageVersion 2.0.

"definitions": {
  "<definition-name": {
    "type": "<data-type-of-definition>",
    "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>,
    "prefixItems": <schema-for-validating-array>,
    "items": <schema-for-validating-array-or-boolean>,
    "properties": <schema-for-validating-object>,
    "additionalProperties": <schema-for-validating-object-or-boolean>,
    "discriminator": <schema-to-apply>,
    "nullable": <boolean>,
    "metadata": {
      "description": "<description-of-the-type-definition>"
    }
  }
}

Příklady použití definic typů najdete v tématu Definice typů v šablonách ARM.

V bicep najdete informace o datových typech definovaných uživatelem.

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>,
    "prefixItems": <schema-for-validating-array>,
    "items": <schema-for-validating-array-or-boolean>,
    "properties": <schema-for-validating-object>,
    "additionalProperties": <schema-for-validating-object-or-boolean>,
    "discriminator": <schema-to-apply>,
    "nullable": <boolean>,
    "metadata": {
      "description": "<description-of-the parameter>"
    }
  }
}

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

V bicep si prohlédněte 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 omezení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é.

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

V bicep se podívejte na proměnné.

Funkce

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í uživatelské funkce existují určitá omezení:

• Funkce nemá přístup k proměnným.
• Funkce může používat pouze parametry definované ve funkci. Pokud 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 pro funkci nemůžou 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>"
        }
      }
    }
  }
],

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

V Bicep se uživatelem definované funkce nepodporují. Bicep podporuje různé funkce a operátory.

Zdroje informací

resources V části definujete prostředky, které se nasazují 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>"
    ]
  }
]

Pokud chcete podporovat symbolický název Bicep v šablonách JSON ARM, přidejte languageVersion ho s verzí 2.0 nebo novějším a změňte definici prostředku z pole na objekt.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "resources": {
    "<name-of-the-resource>": {
      ...
    }
  }
}

Další informace najdete v tématu Zdroje informací.

V Bicep se podívejte na prostředky.

Výstupy

outputs V části zadáte hodnoty, které se vrátí z nasazení. Obvykle vracíte hodnoty z nasazených prostředků. 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>
    }
  }
}

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

V Bicep najdete výstupy.

Komentáře a metadata

Do šablony můžete 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 soubor JSON s typem souboru JSONC (Comments not permitted in JSONC). V opačném případě se zobrazí chybová zpráva o tom, že komentáře nejsou ve formátu JSON povolené.

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2023-03-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 Manageru, můžete použít vložené komentáře. Vložené komentáře už nejsou označené jako neplatné.

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 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ř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, který zadáte v popisu, automaticky použije jako tip pro tento 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": "2022-09-01",
    "name": "[format('{0}{1}', '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 několik řádků. Podívejte se například na location vlastnost a jeden z komentářů v následujícím příkladu JSON.

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2023-03-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 se podívejte na víceřádkové řetězce.

languageVersion 2.0

Pokud chcete použít languageVersion 2.0, přidejte "languageVersion": "2.0" ji do šablony:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "resources": {
    "<name-of-the-resource>": {
      ...
    }
  }
}

Vylepšení a změny, které jsou součástí languageVersion 2.0:

• Použijte symbolický název v šabloně JSON ARM. Další informace naleznete v tématu Použití symbolického názvu.
• Ve smyčce kopírování prostředků použijte symbolický název. Viz Použití symbolického názvu.
• V polích použijte symbolický název dependsOn . Viz DependsOn a Závisí na prostředcích ve smyčce.
• Místo názvu prostředku ve reference funkci použijte symbolický název. Viz reference.
• Funkce references(), která vrací pole objektů představujících stavy modulu runtime kolekce prostředků. Viz odkazy.
• Pomocí vlastnosti existujícího prostředku deklarujte existující prostředky pro ARM, aby se místo nasazení prostředku načetl. Viz Deklarujte existující prostředky.
• Vytvořte uživatelem definované typy. Viz definice typu.
• Další omezení ověření agregovaného typu, která se mají použít v parametrech a výstupech.
• Výchozí hodnota vlastnosti expressionEvaluationOptions je inner. Hodnota outer je blokovaná. Viz obor vyhodnocení výrazu ve vnořených šablonách.
• Funkce deployment vrátí omezenou podmnožinu vlastností. Viz nasazení.
• Pokud se prostředek Deployments používá v nasazení symbolického názvu, použijte apiVersion 2020-09-01 nebo novější.
• V definici prostředku už nepotřebujete dvojité eskapace hodnot v rámci výrazu. Viz řídicí znaky.

Použití některé z následujících funkcí Bicep automaticky povolí generování kódu verze 2.0:

• uživatelem definované typy
• uživatelem definované funkce
• importy v čase kompilace
• experimentální funkce

Další kroky

• Hotové šablony pro mnoho různých typů řešení najdete na stránce Šablony Azure pro rychlý start.
• Podrobnosti o funkcích, které můžete použít v rámci šablony, najdete v tématu Funkce šablony ARM.
• Pokud chcete během nasazování zkombinovat několik šablon, přečtěte si téma Použití propojených a vnořených šablon při nasazování prostředků Azure.
• Doporučení týkající se vytváření šablon najdete v osvědčených postupech pro šablony ARM.
• Odpovědi na běžné otázky najdete v tématu Nejčastější dotazy týkající se šablon ARM.