Parameter in ARM-Vorlagen

  • Artikel

Dieser Artikel beschreibt, wie Sie Parameter in Ihrer Azure Resource Manager-Vorlage (ARM-Vorlage) definieren und verwenden. Durch Bereitstellen verschiedener Werte für Parameter können Sie eine Vorlage für verschiedene Umgebungen wiederverwenden.

Resource Manager löst Parameterwerte vor Beginn der Bereitstellungsvorgänge auf. Jedes Vorkommen des Parameters in der Vorlage wird von Resource Manager durch den aufgelösten Wert ersetzt.

Jeder Parameter muss auf einen der Datentypen festgelegt werden.

Zusätzlich zu minValue, maxValue, minLength, maxLength und allowedValues führt languageVersion 2.0 einige Einschränkungen für Aggregattypvalidierung ein, die in Definitionen, Parametern und Ausgabedefinitionen verwendet werden können. Zu diesen Einschränkungen gehören:

Hinweis

In der aktuellen Version der Azure Resource Manager Tools-Erweiterung für Visual Studio Code werden die in languageVersion 2.0 vorgenommenen Verbesserungen nicht erkannt.

Tipp

Wir empfehlen Bicep, weil es dieselben Funktionen wie ARM-Vorlagen bietet und die Syntax einfacher zu verwenden ist. Weitere Informationen finden Sie unter Parameter.

Die Anzahl der Parameter in einer Vorlage ist auf 256 beschränkt. Weitere Informationen finden Sie unter Vorlagengrenzwerte.

Informationen zu bewährten Methoden für Parameter finden Sie unter Parameter.

Minimale Deklaration

Jeder Parameter benötigt mindestens einen Namen und einen Typ.

Wenn Sie eine Vorlage über das Azure-Portal bereitstellen, werden Parameternamen mit Camel-Case-Schreibweise in durch Leerzeichen getrennte Namen umgewandelt. Beispielsweise wird demoString im folgenden Beispiel als Demo String angezeigt. Weitere Informationen finden Sie unter Verwenden einer Bereitstellungsschaltfläche zum Bereitstellen von Vorlagen aus dem GitHub-Repository und Bereitstellen von Ressourcen mit ARM-Vorlagen und dem Azure-Portal.

"parameters": {
  "demoString": {
    "type": "string"
  },
  "demoInt": {
    "type": "int"
  },
  "demoBool": {
    "type": "bool"
  },
  "demoObject": {
    "type": "object"
  },
  "demoArray": {
    "type": "array"
  }
}

Sichere Parameter

Sie können Zeichenfolgen- oder Objektparameter als sicher kennzeichnen. Der Wert eines sicheren Parameters wird weder im Bereitstellungsverlauf gespeichert noch protokolliert.

"parameters": {
  "demoPassword": {
    "type": "secureString"
  },
  "demoSecretObject": {
    "type": "secureObject"
  }
}

Zulässige Werte

Sie können für einen Parameter zulässige Werte definieren. Diese werden in einem Array bereitgestellt. Wenn für den Parameter ein Wert übergeben wird, der nicht zu den zulässigen Werten gehört, schlägt die Bereitstellung während der Überprüfung fehl.

"parameters": {
  "demoEnum": {
    "type": "string",
    "allowedValues": [
      "one",
      "two"
    ]
  }
}

Standardwert

Sie können für einen Parameter keinen Standardwert angeben. Der Standardwert wird verwendet, wenn während der Bereitstellung kein Wert angegeben wird.

"parameters": {
  "demoParam": {
    "type": "string",
    "defaultValue": "Contoso"
  }
}

Wenn Sie für den Parameter einen Standardwert zusammen mit anderen Eigenschaften angeben möchten, verwenden Sie folgende Syntax.

"parameters": {
  "demoParam": {
    "type": "string",
    "defaultValue": "Contoso",
    "allowedValues": [
      "Contoso",
      "Fabrikam"
    ]
  }
}

Ausdrücke können mit dem Standardwert verwendet werden. Im Parameterabschnitt kann weder die reference-Funktion noch eine der list-Funktionen verwendet werden. Diese Funktionen rufen den Laufzeitstatus einer Ressource ab und können nicht vor der Bereitstellung ausgeführt werden, wenn Parameter aufgelöst werden.

In Ausdrücken dürfen keine anderen Parametereigenschaften verwendet werden.

"parameters": {
  "location": {
    "type": "string",
    "defaultValue": "[resourceGroup().location]"
  }
}

Sie können einen anderen Parameterwert verwenden, um einen Standardwert zu erstellen. Mit der folgenden Vorlage wird aus dem Websitenamen ein Name für den Hostplan erstellt.

"parameters": {
  "siteName": {
    "type": "string",
    "defaultValue": "[concat('site', uniqueString(resourceGroup().id))]"
  },
  "hostingPlanName": {
    "type": "string",
    "defaultValue": "[concat(parameters('siteName'),'-plan')]"
  }
}

Sie können jedoch nicht auf eine Variable als Standardwert verweisen.

Längenbeschränkungen

Sie können die minimale und maximale Länge von Zeichenfolgen- und Arrayparametern angeben. Sie können eine oder beide Einschränkungen festlegen. Bei Zeichenfolgen gibt die Länge die Anzahl der Zeichen an. Bei Arrays gibt die Länge die Anzahl der Elemente im Array an.

Im folgenden Beispiel werden zwei Parameter deklariert. Ein Parameter ist für den Namen eines Speicherkontos, der 3–24 Zeichen enthalten muss. Der andere Parameter ist ein Array, das 1–5 Elemente aufweisen muss.

"parameters": {
  "storageAccountName": {
    "type": "string",
    "minLength": 3,
    "maxLength": 24
  },
  "appNames": {
    "type": "array",
    "minLength": 1,
    "maxLength": 5
  }
}

Ganzzahlige Einschränkungen

Sie können die minimalen und maximalen Werte für ganzzahlige Parameter festlegen. Sie können eine oder beide Einschränkungen festlegen.

"parameters": {
  "month": {
    "type": "int",
    "minValue": 1,
    "maxValue": 12
  }
}

Objekteinschränkungen

Die Objekteinschränkungen sind nur für Objekte zulässig und können nur mit languageVersion 2.0 verwendet werden.

Eigenschaften

Der Wert von properties ist eine Zuordnung von Eigenschaftsname = >Typdefinition.

Das folgende Beispiel würde {"foo": "string", "bar": 1} akzeptieren, aber {"foo": "string", "bar": -1}, {"foo": "", "bar": 1} oder ein beliebiges Objekt ohne eine foo- oder bar-Eigenschaft ablehnen.

"parameters": {
  "objectParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    }
  }
}

Alle Eigenschaften sind erforderlich, es sei denn, die Typdefinition der Eigenschaft hat die Einschränkung "nullable": true. Wenn Sie beide Eigenschaften im vorangegangenen Beispiel optional machen, würde es so aussehen:

"parameters": {
  "objectParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3,
        "nullable": true
      },
      "bar": {
        "type": "int",
        "minValue": 0,
        "nullable": true
      }
    }
  }
}

additionalProperties

Der Wert von additionalProperties ist eine Typdefinition oder ein boolescher Wert. Wenn keine additionalProperties-Einschränkung definiert ist, ist true der Standardwert.

Wenn der Wert eine Typdefinition ist, beschreibt der Wert das Schema, das auf alle Eigenschaften angewendet wird, die nicht in der properties-Einschränkung erwähnt werden. Das folgende Beispiel würde {"fizz": "buzz", "foo": "bar"} akzeptieren, {"property": 1} jedoch ablehnen.

"parameters": {
  "dictionaryParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3,
        "nullable": true
      },
      "bar": {
        "type": "int",
        "minValue": 0,
        "nullable": true
      }
    },
    "additionalProperties": {
      "type": "string"
    }
  }
}

Wenn der Wert false ist, können keine Eigenschaften angegeben werden, die über die in der properties-Einschränkung definierten hinausgehen. Das folgende Beispiel würde {"foo": "string", "bar": 1} akzeptieren, {"foo": "string", "bar": 1, "fizz": "buzz"} jedoch ablehnen.

"parameters": {
  "dictionaryParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    },
    "additionalProperties": false
  }
}

Wenn der Wert true ist, akzeptiert jede Eigenschaft, die nicht in der properties-Einschränkung definiert ist, jeden Wert. Das folgende Beispiel würde {"foo": "string", "bar": 1, "fizz": "buzz"} akzeptieren.

"parameters": {
  "dictionaryParameter": {
    "type": "object",
    "properties": {
      "foo": {
        "type": "string",
        "minLength": 3
      },
      "bar": {
        "type": "int",
        "minValue": 0
      }
    },
    "additionalProperties": true
  }
}

discriminator

Der Wert discriminator definiert, welches Schema basierend auf einer Diskriminatoreigenschaft angewendet werden soll. Das folgende Beispiel würde entweder {"type": "ints", "foo": 1, "bar": 2} oder {"type": "strings", "fizz": "buzz", "pop": "goes", "the": "weasel"} akzeptieren, {"type": "ints", "fizz": "buzz"} jedoch ablehnen.

"parameters": {
  "taggedUnionParameter": {
    "type": "object",
    "discriminator": {
      "propertyName": "type",
      "mapping": {
        "ints": {
          "type": "object",
          "additionalProperties": {"type": "int"}
        },
        "strings": {
          "type": "object",
          "additionalProperties": {"type": "string"}
          }
      }
    }
  }
}

Einschränkungen für Arrays

Die Arrayeinschränkungen sind nur für Arrays zulässig und können nur mit languageVersion 2.0 verwendet werden.

prefixItems

Der Wert von prefixItems ist ein Array von Typdefinitionen. Jede Typdefinition im Wert ist das Schema, das zum Überprüfen des Elements eines Arrays am selben Index verwendet werden soll. Das folgende Beispiel würde [1, true] akzeptieren, [1, "string"] oder [1] jedoch ablehnen:

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  }
}

Elemente

Der Wert von items ist eine Typdefinition oder ein boolescher Wert. Wenn keine items-Einschränkung definiert ist, ist true der Standardwert.

Wenn der Wert eine Typdefinition ist, beschreibt der Wert das Schema, das auf alle Elemente des Arrays angewendet wird, deren Index größer als der größte Index der prefixItems-Einschränkung ist. Das folgende Beispiel würde [1, true, 1] oder [1, true, 1, 1] akzeptieren, [1, true, "foo"] jedoch ablehnen:

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      { "type": "int" },
      { "type": "bool" }
    ],
    "items": { "type": "int" },
    "defaultValue": [1, true, "foo"]
  }
}

Sie können items verwenden, ohne prefixItems zu verwenden. Das folgende Beispiel würde [1, 2] oder [1] akzeptieren, ["foo"] jedoch ablehnen:

"parameters": {
  "intArrayParameter": {
    "type": "array",
    "items": {"type": "int"}
  }
}

Wenn der Wert false ist, muss das überprüfte Array genau die gleiche Länge wie die prefixItems-Einschränkung aufweisen. Das folgende Beispiel würde [1, true] akzeptieren, [1, true, 1] und [1, true, false, "foo", "bar"] jedoch ablehnen.

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ],
    "items": false
  }
}

Wenn der Wert true ist, akzeptieren Elemente des Arrays, dessen Index größer als der größte Index der prefixItems-Einschränkung ist, jeden Wert. Die folgenden Beispiele würden [1, true], [1, true, 1] und [1, true, false, "foo", "bar"] akzeptieren.

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  }
}

"parameters": {
  "tupleParameter": {
    "type": "array",
    "prefixItems": [
      {"type": "int"},
      {"type": "bool"}
    ]
  },
  "items": true
}

Nullable-Einschränkung

Die Nullable-Einschränkung kann nur mit languageVersion 2.0 verwendet werden. Sie gibt an, dass der Wert möglicherweise null ist oder ausgelassen wurde. Ein Beispiel finden Sie unter Eigenschaften.

Beschreibung

Sie können einem Parameter eine Beschreibung hinzufügen, damit Benutzer Ihrer Vorlage leichter nachvollziehen können, welcher Wert bereitgestellt werden soll. 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. Beschreibungen sollten nur hinzugefügt werden, wenn der Text mehr Informationen bietet, als aus dem Parameternamen abgeleitet werden können.

"parameters": {
  "virtualMachineSize": {
    "type": "string",
    "metadata": {
      "description": "Must be at least Standard_A3 to support 2 NICs."
    },
    "defaultValue": "Standard_DS1_v2"
  }
}

Verwenden eines Parameters

Um auf den Wert eines Parameters zu verweisen, verwenden Sie die Funktionparameters. Im folgenden Beispiel wird ein Parameterwert für den Namen eines Schlüsseltresors verwendet.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "vaultName": {
      "type": "string",
      "defaultValue": "[format('keyVault{0}', uniqueString(resourceGroup().id))]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.KeyVault/vaults",
      "apiVersion": "2021-06-01-preview",
      "name": "[parameters('vaultName')]",
      ...
    }
  ]
}

Objekte als Parameter

Sie können in Beziehung stehende Werte organisieren, indem sie sie als Objekt übergeben. Diese Vorgehensweise verringert auch die Anzahl der Parameter in der Vorlage.

Das folgende Beispiel zeigt einen Parameter, bei dem es sich um ein Objekt handelt. Der Standardwert gibt die erwarteten Eigenschaften für das Objekt an. Diese Eigenschaften werden in der Definition der bereitzustellenden Ressource verwendet.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "vNetSettings": {
      "type": "object",
      "defaultValue": {
        "name": "VNet1",
        "location": "eastus",
        "addressPrefixes": [
          {
            "name": "firstPrefix",
            "addressPrefix": "10.0.0.0/22"
          }
        ],
        "subnets": [
          {
            "name": "firstSubnet",
            "addressPrefix": "10.0.0.0/24"
          },
          {
            "name": "secondSubnet",
            "addressPrefix": "10.0.1.0/24"
          }
        ]
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.Network/virtualNetworks",
      "apiVersion": "2021-02-01",
      "name": "[parameters('vNetSettings').name]",
      "location": "[parameters('vNetSettings').location]",
      "properties": {
        "addressSpace": {
          "addressPrefixes": [
            "[parameters('vNetSettings').addressPrefixes[0].addressPrefix]"
          ]
        },
        "subnets": [
          {
            "name": "[parameters('vNetSettings').subnets[0].name]",
            "properties": {
              "addressPrefix": "[parameters('vNetSettings').subnets[0].addressPrefix]"
            }
          },
          {
            "name": "[parameters('vNetSettings').subnets[1].name]",
            "properties": {
              "addressPrefix": "[parameters('vNetSettings').subnets[1].addressPrefix]"
            }
          }
        ]
      }
    }
  ]
}

Beispielvorlagen

In den folgenden Beispielen werden Szenarien für die Verwendung von Parametern veranschaulicht.

Vorlage Beschreibung
Parameter mit Funktionen für Standardwerte Zeigt, wie Vorlagenfunktionen verwendet werden, wenn Sie Standardwerte für Parameter definieren. Die Vorlage stellt keine Ressourcen bereit. Sie erstellt Parameterwerte und gibt diese Werte zurück.
Parameterobjekt Veranschaulicht die Verwendung eines Objekts für einen Parameter. Die Vorlage stellt keine Ressourcen bereit. Sie erstellt Parameterwerte und gibt diese Werte zurück.

Nächste Schritte