Verstehen der Struktur und Syntax von ARM-Vorlagen

In diesem Artikel wird die Struktur einer Azure Resource Manager-Vorlage (ARM-Vorlage) beschrieben. Er zeigt die verschiedenen Abschnitte einer Vorlage und die Eigenschaften, die in diesen Abschnitten verfügbar sind.

Dieser Artikel richtet sich an Benutzer, die bereits Vorkenntnisse zu ARM-Vorlagen haben. Er bietet detaillierte Informationen zur Struktur der Vorlage. Ein Schritt-für-Schritt-Tutorial mit Anleitungen zum Erstellen einer Vorlage finden Sie unter Tutorial: Erstellen und Bereitstellen Ihrer ersten ARM-Vorlage. Informationen zu ARM-Vorlagen durch eine geführte Reihe von Lernmodulen finden Sie unter Bereitstellen und Verwalten von Ressourcen in Azure mithilfe von ARM-Vorlagen.

Vorlagenformat

In der einfachsten Struktur weist eine Vorlage die folgenden Elemente auf:

{
  "$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": { }
}

Jedes Element weist Eigenschaften auf, die Sie festlegen können. In diesem Artikel werden die Abschnitte der Vorlage ausführlicher beschrieben.

Definitionen

Geben Sie im Abschnitt definitions der Vorlage die Schemas an, die zum Überprüfen von Array- und Objektwerten verwendet werden. Definitions kann nur mit languageVersion 2.0 verwendet werden.

"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>"
    }
  }
}

Beispiele für die Verwendung von Typdefinitionen finden Sie unter Typdefinitionen in ARM-Vorlagen.

Weitere Informationen finden Sie unter Benutzerdefinierte Datentypen in Bicep.

Parameter

Im Abschnitt parameters der Vorlage geben Sie an, welche Werte Sie beim Bereitstellen der Ressourcen eingeben können. Die Anzahl der Parameter in einer Vorlage ist auf 256 beschränkt. Sie können die Anzahl der Parameter verringern, indem Sie Objekte verwenden, die mehrere Eigenschaften enthalten.

Folgende Eigenschaften sind für einen Parameter verfügbar:

"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>"
    }
  }
}

Beispiele für die Verwendung von Parametern finden Sie unter Parameter in ARM-Vorlagen.

Weitere Informationen finden Sie unter Parameter in Bicep.

Variables

Im Abschnitt variables erstellen Sie Werte, die in der gesamten Vorlage verwendet werden können. Sie müssen nicht unbedingt Variablen definieren, aber häufig bewirken sie eine Vereinfachung Ihrer Vorlage, indem komplexe Ausdrücke reduziert werden. Das Format der einzelnen Variablen entspricht einem der Datentypen. Die Anzahl der Variablen in einer Vorlage ist auf 256 beschränkt.

Im folgenden Beispiel werden die verfügbaren Optionen zum Definieren einer Variable angezeigt:

"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>
    }
  ]
}

Informationen zur Verwendung von copy zum Erstellen mehrerer Werte für eine Variable finden Sie unter copy.

Beispiele für die Verwendung von Variablen finden Sie unter Variablen in einer ARM-Vorlage.

Weitere Informationen finden Sie unter Variablen in Bicep.

Functions

In Ihrer Vorlage können Sie Ihre eigenen Funktionen erstellen. Diese Funktionen stehen dann zur Verwendung in der Vorlage zur Verfügung. Normalerweise definieren Sie komplexe Ausdrücke, die in der Vorlage nicht wiederholt werden sollen. Sie erstellen die benutzerdefinierten Funktionen aus Ausdrücken und Funktionen, die in Vorlagen unterstützt werden.

Beim Definieren einer benutzerdefinierten Funktion gelten einige Einschränkungen:

• Die Funktion kann nicht auf Variablen zugreifen.
• Die Funktion kann nur Parameter verwenden, die in der Funktion definiert sind. Bei Verwendung der parameters-Funktion innerhalb einer benutzerdefinierten Funktion sind Sie auf die Parameter für diese Funktion beschränkt.
• Die Funktion kann keine anderen benutzerdefinierten Funktionen aufrufen.
• Die Funktion kann nicht die Referenzfunktion verwenden.
• Für die Parameter der Funktion können keine Standardwerte verwendet werden.

"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>"
        }
      }
    }
  }
],

Beispiele für die Verwendung von benutzerdefinierten Funktionen finden Sie unter Benutzerdefinierte Funktionen in einer ARM-Vorlage.

In Bicep werden benutzerdefinierte Funktionen nicht unterstützt. Bicep unterstützt verschiedene Funktionen und Operatoren.

Ressourcen

Im Abschnitt resources definieren Sie die Ressourcen, die bereitgestellt oder aktualisiert werden. Die Anzahl der Ressourcen in einer Vorlage ist auf 800 beschränkt.

Sie definieren Ressourcen mit der folgenden Struktur:

"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>"
    ]
  }
]

Um symbolische Bicep-Namen in ARM-JSON-Vorlagen zu unterstützen, fügen Sie languageVersion mit der Version 2.0 oder höher hinzu, und ändern Sie die Ressourcendefinition von einem Array in ein 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>": {
      ...
    }
  }
}

Weitere Informationen finden Sie unter Ressourcen.

Weitere Informationen finden Sie unter Ressourcen in Bicep.

Ausgaben

Im Abschnitt outputs legen Sie Werte fest, die von der Bereitstellung zurückgegeben werden. In der Regel geben Sie Werte aus bereitgestellten Ressourcen zurück. Die Anzahl der Ausgaben in einer Vorlage ist auf 64 beschränkt.

Das folgende Beispiel zeigt die Struktur einer Ausgabedefinition:

"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>
    }
  }
}

Beispiele für die Verwendung von Ausgaben finden Sie unter Ausgaben in ARM-Vorlagen.

Weitere Informationen finden Sie in Bicep unter Ausgaben.

Kommentare und Metadaten

Es gibt mehrere Möglichkeiten, um Kommentare und Metadaten in Ihrer Vorlage hinzuzufügen.

Kommentare

Für Inlinekommentare können Sie entweder // oder /* ... */ verwenden. Speichern Sie die Parameterdateien in Visual Studio Code mit Kommentaren als Dateityp JSON with comments (JSONC). Andernfalls wird eine Fehlermeldung angezeigt, die besagt, dass Kommentare in JSON nicht zulässig sind.

{
  "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'))]"
  ],

In Visual Studio Code kann die Azure Resource Manager-Tools-Erweiterung automatisch eine ARM-Vorlage erkennen und den Sprachmodus ändern. Wenn in der rechten unteren Ecke von Visual Studio Code Azure Resource Manager-Vorlage angezeigt wird, können Sie die Inlinekommentare verwenden. Die Inlinekommentare werden nicht mehr als ungültig markiert.

Weitere Informationen finden Sie in Bicep unter Kommentare.

Metadaten

Sie können ein metadata-Objekt fast überall in Ihrer Vorlage hinzufügen. Resource Manager ignoriert das Objekt, aber Sie werden von Ihrem JSON-Editor möglicherweise gewarnt, dass die Eigenschaft nicht gültig ist. Definieren Sie im Objekt die erforderlichen Eigenschaften.

{
  "$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"
  },

Fügen Sie für parameters ein metadata-Objekt mit einer description-Eigenschaft hinzu.

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

Wenn Sie die Vorlage über das Portal bereitstellen, wird der Text, den Sie in der Beschreibung angeben, automatisch als Tipp für diesen Parameter verwendet.

Fügen Sie für resources ein comments-Element oder ein metadata-Objekt hinzu. Das folgende Beispiel zeigt sowohl ein comments-Element als auch ein 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": {}
  }
]

Fügen Sie für outputs dem Ausgabewert ein metadata-Objekt hinzu.

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

Sie können benutzerdefinierten Funktionen kein metadata-Objekt hinzufügen.

Mehrzeilige Zeichenfolgen

Sie können eine Zeichenfolge in mehrere Zeilen unterteilen. Sehen Sie sich beispielsweise die location-Eigenschaft und einen der Kommentare im folgenden JSON-Beispiel an.

{
  "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'))]"
  ],

Weitere Informationen finden Sie in Bicep unter Multi-Linienzeichenfolgen.

languageVersion 2.0

Um languageVersion 2.0 zu verwenden, fügen Sie Ihrer Vorlage "languageVersion": "2.0" hinzu:

{
  "$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>": {
      ...
    }
  }
}

Die Verbesserungen und Änderungen in languageVersion 2.0:

• Verwenden eines symbolischen Namens in einer ARM-JSON-Vorlage. Weitere Informationen finden Sie unter Verwenden eines symbolischen Namens.
• Verwenden eines symbolischen Namens in Ressourcenkopierschleifen. Weitere Informationen finden Sie unter Verwenden des symbolischen Namens.
• Verwenden eines symbolischen Namens in dependsOn-Arrays. Weitere Informationen finden Sie unter DependsOn und Abhängigkeit von Ressourcen in einer Schleife.
• Verwenden eines symbolischen Namens anstelle des Ressourcennamens in der reference-Funktion. Weitere Informationen finden Sie unter Verweis.
• Eine references()-Funktion, die ein Array von Objekten zurückgibt, das die Runtimezustände einer Ressourcensammlung darstellt. Weitere Informationen finden Sie unter Referenzen.
• Verwenden Sie die Ressourceneigenschaft "existing", um vorhandene Ressourcen für ARM zu deklarieren, damit eine Ressource gelesen und nicht bereitgestellt wird. Weitere Informationen finden Sie unter Deklarieren vorhandener Ressourcen.
• Erstellen benutzerdefinierter Typen. Weitere Informationen finden Sie unter Typendefinition.
• Zusätzliche Aggregattypvalidierungseinschränkungen, die in Parametern und Ausgaben verwendet werden sollen.
• Der Standardwert für die expressionEvaluationOptions-Eigenschaft ist inner. Der Wert outer wird blockiert. Weitere Informationen finden Sie unter Auswertungsbereich von Ausdrücken in geschachtelten Vorlagen.
• Die deployment-Funktion gibt eine begrenzte Teilmenge von Eigenschaften zurück. Weitere Informationen finden Sie unter Bereitstellung.
• Wenn die Bereitstellungsressource in einer Bereitstellung mit symbolischem Namen verwendet wird, verwenden Sie apiVersion 2020-09-01 oder höher.
• In der Ressourcendefinition sind doppelte Escapewerte innerhalb eines Ausdrucks nicht mehr erforderlich. Weitere Informationen finden Sie unter Escapezeichen.

Die Verwendung eines der folgenden Bicep-Features aktiviert automatisch die Codegenerierung mit der Sprachversion 2.0:

• Benutzerdefinierte Typen
• Benutzerdefinierte Funktionen
• Importe zur Kompilierungszeit
• Experimentelle Features

Nächste Schritte

• Komplette Vorlagen für viele verschiedene Lösungstypen finden Sie unter Azure-Schnellstartvorlagen.
• Ausführliche Informationen zu den Funktionen, die Sie innerhalb einer Vorlage nutzen können, finden Sie unter Funktionen von ARM-Vorlagen.
• Informationen zum Zusammenführen mehrerer Vorlagen während der Bereitstellung finden Sie unter Verwenden von verknüpften und geschachtelten Vorlagen bei der Bereitstellung von Azure-Ressourcen.
• Empfehlungen zum Erstellen von Vorlagen finden Sie unter Bewährte Methoden für ARM-Vorlagen.
• Antworten auf gängige Fragen finden Sie unter Häufig gestellte Fragen zu ARM-Vorlagen.