Erstellen einer Resource Manager-Parameterdatei

  • Artikel

Anstatt Parameter als Inlinewerte in Ihrem Skript zu übergeben, können Sie eine JSON-Datei verwenden, die die Parameterwerte enthält. In diesem Artikel erfahren Sie, wie Sie eine Parameterdatei erstellen, die Sie mit einer JSON-Vorlage verwenden.

Tipp

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

Parameterdatei

Eine Parameterdatei verwendet das folgende Format:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "<first-parameter-name>": {
      "value": "<first-value>"
    },
    "<second-parameter-name>": {
      "value": "<second-value>"
    }
  }
}

Es ist beachtenswert, dass die Parameterdatei Parameterwerte als Nur-Text speichert. Aus Sicherheitsgründen wird dieser Ansatz für vertrauliche Werte wie Kennwörter nicht empfohlen. Wenn Sie einen Parameter mit einem vertraulichen Wert übergeben müssen, bewahren Sie den Wert in einem Schlüsseltresor auf. Nehmen Sie dann einen Verweis auf den Schlüsseltresor in Ihre Parameterdatei auf. Während der Bereitstellung wird der vertrauliche Wert dann auf sichere Weise abgerufen. Weitere Informationen finden Sie unter Verwenden von Azure Key Vault zum Übergeben eines sicheren Parameterwerts während der Bereitstellung.

Die folgende Parameterdatei enthält einen Klartextwert und einen vertraulichen Wert, der in einem Schlüsseltresor gespeichert ist.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "<first-parameter-name>": {
      "value": "<first-value>"
    },
    "<second-parameter-name>": {
      "reference": {
        "keyVault": {
          "id": "<resource-id-key-vault>"
        },
        "secretName": "<secret-name>"
      }
    }
  }
}

Weitere Informationen zur Verwendung von Werten aus einem Schlüsseltresor finden Sie unter Verwenden von Azure Key Vault zum Übergeben eines sicheren Parameterwerts während der Bereitstellung.

Definieren von Parameterwerten

Öffnen Sie Ihre JSON-Vorlage und prüfen Sie den Abschnitt parameters, um zu bestimmen, wie die Parameternamen und -werte definiert werden. Im folgenden Beispiel sind die Parameter aus einer JSON-Vorlage dargestellt.

"parameters": {
  "storagePrefix": {
    "type": "string",
    "maxLength": 11
  },
  "storageAccountType": {
    "type": "string",
    "defaultValue": "Standard_LRS",
    "allowedValues": [
    "Standard_LRS",
    "Standard_GRS",
    "Standard_ZRS",
    "Premium_LRS"
    ]
  }
}

In der Parameterdatei ist das erste Detail der Name der einzelnen Parameter. Der Parameternamen in der Parameterdatei müssen mit den Parameternamen in der Vorlage identisch sein.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
    },
    "storageAccountType": {
    }
  }
}

Beachten Sie die Parametertypskala. Die Parametertypen in ihrer Parameterdatei müssen die gleichen Typen wie Ihre Vorlage verwenden. In diesem Beispiel sind beide Parametertypen Zeichenfolgen.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": ""
    },
    "storageAccountType": {
      "value": ""
    }
  }
}

Überprüfen Sie die Vorlage auf Parameter mit einem Standardwert. Wenn ein Parameter über einen Standardwert verfügt, können Sie einen Wert in der Parameterdatei angeben, aber er ist nicht erforderlich. Der Wert der Parameterdatei überschreibt den Standardwert der Vorlage.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": "" // This value must be provided.
    },
    "storageAccountType": {
      "value": "" // This value is optional. Template will use default value if not provided.
    }
  }
}

Überprüfen Sie die zulässigen Werte der Vorlage und alle Einschränkungen, z. B. die maximale Länge. Diese Werte geben den Wertebereich an, den Sie für einen Parameter angeben können. In diesem Beispiel kannstoragePrefix maximal 11 Zeichen enthalten und storageAccountType muss einen zulässigen Wert angeben.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "storagePrefix": {
      "value": "storage"
    },
    "storageAccountType": {
      "value": "Standard_ZRS"
    }
  }
}

Hinweis

Ihre Parameterdatei kann nur Werte für Parameter enthalten, die in der Vorlage definiert sind. Wenn die Parameterdatei zusätzliche Parameter enthält, die nicht mit den Parametern in der Vorlage identisch sind, erhalten Sie eine Fehlermeldung.

Parametertypformate

Das folgende Beispiel zeigt die Formate verschiedener Parametertypen: Zeichenfolge, ganze Zahl, Boolean, Array und Objekt.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "exampleString": {
      "value": "test string"
    },
    "exampleInt": {
      "value": 4
    },
    "exampleBool": {
      "value": true
    },
    "exampleArray": {
      "value": [
        "value 1",
        "value 2"
      ]
    },
    "exampleObject": {
      "value": {
        "property1": "value1",
        "property2": "value2"
      }
    }
  }
}

Bereitstellen der Vorlage mit einer Parameterdatei

In Azure CLI übergeben Sie eine lokale Parameterdatei mit @ und dem Namen der Parameterdatei. Beispiel: @storage.parameters.json.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters @storage.parameters.json

Weitere Informationen finden Sie unter Bereitstellen von Ressourcen mit ARM-Vorlagen und der Azure CLI.

In Azure PowerShell übergeben Sie eine lokale Parameterdatei mithilfe des TemplateParameterFile-Parameters.

New-AzResourceGroupDeployment -Name ExampleDeployment -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.json `
  -TemplateParameterFile C:\MyTemplates\storage.parameters.json

Weitere Informationen finden Sie unter Bereitstellen von Ressourcen mit ARM-Vorlagen und Azure PowerShell

Hinweis

Es ist nicht möglich, eine Parameterdatei mit dem benutzerdefinierten Vorlagenblatt im Portal zu verwenden.

Tipp

Stellen Sie bei Verwendung des Projekts „Azure-Ressourcengruppe“ in Visual Studio sicher, dass die Eigenschaft Buildvorgang der Parameterdatei auf Inhalt festgelegt ist.

Dateiname

Die allgemeine Konvention für das Benennen der Parameterdatei ist das Hinzufügen von Parametern zum Vorlagennamen. Wenn Ihre Vorlage beispielsweise den Namen azuredeploy.json hat, ergibt sich für Ihre Parameterdatei der Name azuredeploy.parameters.json. Anhand dieser Namenskonvention können Sie die Verbindung zwischen der Vorlage und den Parametern erkennen.

Erstellen Sie mehr als eine Parameterdatei, wenn Sie die Bereitstellung in unterschiedlichen Umgebungen durchführen möchten. Wenn Sie die Parameterdateien benennen, identifizieren Sie deren Verwendung, z. B. Entwicklung und Produktion. Verwenden Sie beispielsweise azuredeploy.parameters-dev.json und azuredeploy.parameters-prod.json, um Ressourcen bereitzustellen.

Parameterrangfolge

Sie können Inlineparameter und eine lokale Parameterdatei im selben Bereitstellungsvorgang verwenden. Sie können beispielsweise einige Werte in der lokalen Parameterdatei angeben und weitere Werte während der Bereitstellung inline hinzufügen. Wenn Sie Werte für einen Parameter sowohl in der lokalen Parameterdatei als auch inline bereitstellen, haben die Inlinewerte Vorrang.

Sie können eine externe Parameterdatei verwenden, indem Sie den URI der Datei bereitstellen. Bei Verwendung einer externen Parameterdatei können Sie keine anderen Werte (weder inline noch aus einer lokalen Datei) übergeben. Alle Inlineparameter werden ignoriert. Stellen Sie alle Parameterwerte in der externen Datei bereit.

Parameternamenskonflikte

Wenn Ihre Vorlage einen Parameter enthält, der den gleichen Namen besitzt wie einer der Parameter des PowerShell-Befehls, zeigt PowerShell den Parameter der Vorlage mit dem Postfix FromTemplate an. Beispiel: Ein Parameter namens ResourceGroupName in Ihrer Vorlage verursacht einen Konflikt mit dem Parameter ResourceGroupName im Cmdlet ResourceGroupName. Sie werden zur Eingabe eines Werts für ResourceGroupNameFromTemplate aufgefordert. Verwenden Sie Parameternamen, die nicht für Bereitstellungsbefehle verwendet werden, um diese Verwechslung zu vermeiden.

Nächste Schritte