Syntax und Ausdrücke in ARM-Vorlagen

  • Artikel

Die grundlegende Syntax der Azure Resource Manager-Vorlage (ARM-Vorlage) ist in JSON-Format (JavaScript Object Notation). Allerdings können Sie Ausdrücke verwenden, um die JSON-Werte zu erweitern, die in der Vorlage zur Verfügung stehen. Ausdrücke beginnen und enden mit Klammern, entsprechend [ und ]. Der Wert des Ausdrucks wird bei der Bereitstellung der Vorlage ausgewertet. Ein Ausdruck kann eine Zeichenfolge, eine ganze Zahl, einen booleschen Wert, ein Array oder ein Objekt zurückgeben.

Ein Vorlagenausdruck darf aus maximal 24.576 Zeichen bestehen.

Verwenden von Funktionen

Azure Resource Manager bietet Funktionen, die Sie in einer Vorlage verwenden können. Das folgende Beispiel zeigt einen Ausdruck, der eine Funktion im Standardwert eines Parameters verwendet:

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

Innerhalb des Ausdrucks ruft die Syntax resourceGroup() eine der Funktionen auf, die Resource Manager für die Verwendung innerhalb einer Vorlage bereitstellt. Hier ist dies die Funktion resourceGroup. Genau wie in JavaScript haben Funktionsaufrufe das Format functionName(arg1,arg2,arg3). Die Syntax .location ruft eine Eigenschaft des Objekts ab, das von dieser Funktion zurückgegeben wird.

Bei Vorlagenfunktionen und ihren Parametern wird Groß-und Kleinschreibung nicht unterschieden. Beispielsweise löst Resource Manager variables('var1') und VARIABLES('VAR1') identisch auf. Bei der Auswertung bleibt die Groß-/Kleinschreibung erhalten, sofern diese nicht ausdrücklich durch die Funktion geändert wird (z. B. mit toUpper oder toLower). Für spezielle Ressourcentypen gelten möglicherweise Vorgaben zur Groß-/Kleinschreibung, die sich davon unterscheiden, wie Funktionen ausgewertet werden.

Verwenden Sie einfache Anführungszeichen, um einen Zeichenfolgenwert als Parameter an eine Funktion zu übergeben.

"name": "[concat('storage', uniqueString(resourceGroup().id))]"

Die meisten Funktionen funktionieren identisch, unabhängig davon, ob sie in einer Ressourcengruppe, einem Abonnement, einer Verwaltungsgruppe oder einem Mandanten bereitgestellt werden. Die folgenden Funktionen haben Einschränkungen auf der Grundlage des Bereichs:

  • resourceGroup: Kann nur in Bereitstellungen in einer Ressourcengruppe verwendet werden.
  • resourceId: Kann in jedem Bereich verwendet werden, aber die gültigen Parameter ändern sich je nach Bereich.
  • subscription: Kann nur in Bereitstellungen in einer Ressourcengruppe oder einem Abonnement verwendet werden.

Escape-Zeichen

Wenn eine Literalzeichenfolge mit einer öffnenden eckigen Klammer [ beginnen und einer schließenden eckigen Klammer ] enden, aber nicht als Ausdruck interpretiert werden soll, fügen Sie am Anfang der Zeichenfolge eine zusätzliche eckige Klammer ein: [[. Beispielsweise wird folgende Variable:

"demoVar1": "[[test value]"

in [test value] aufgelöst.

Wenn die Literalzeichenfolge jedoch nicht mit einer eckigen Klammer endet, dürfen Sie die erste eckige Klammer nicht mit einem Escapezeichen versehen. Beispielsweise wird folgende Variable:

"demoVar2": "[test] value"

in [test] value aufgelöst.

Verwenden Sie den umgekehrten Schrägstrich, um doppelte Anführungszeichen in einem Ausdruck mit einem Escapezeichen zu versehen, wie beim Hinzufügen eines JSON-Objekts.

"tags": {
    "CostCenter": "{\"Dept\":\"Finance\",\"Environment\":\"Production\"}"
},

Um einfache Anführungszeichen in einer ARM-Ausdrucksausgabe mit Escapezeichen zu versehen, verdoppeln Sie die einfachen Anführungszeichen. Die Ausgabe der folgenden Vorlage ergibt den JSON-Wert {"abc":"'quoted'"}.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {},
  "resources": [],
  "outputs": {
    "foo": {
      "type": "object",
      "value": "[createObject('abc', '''quoted''')]"
    }
  }
}

Verwenden Sie in der Ressourcendefinition doppelte Escapezeichen innerhalb eines Ausdrucks. scriptOutput aus der folgenden Vorlage ist de'f.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "forceUpdateTag": {
      "type": "string",
      "defaultValue": "[newGuid()]"
    }
  },
  "variables": {
    "deploymentScriptSharedProperties": {
      "forceUpdateTag": "[parameters('forceUpdateTag')]",
      "azPowerShellVersion": "10.1",
      "retentionInterval": "P1D"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "escapingTest",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "properties": "[union(variables('deploymentScriptSharedProperties'), createObject('scriptContent', '$DeploymentScriptOutputs = @{}; $DeploymentScriptOutputs.escaped = \"de''''f\";'))]"
    }
  ],
  "outputs": {
    "scriptOutput": {
      "type": "string",
      "value": "[reference('escapingTest').outputs.escaped]"
    }
  }
}

Mit languageVersion 2.0 sind doppelte Escapezeichen nicht mehr erforderlich. Das obige Beispiel kann als der folgende JSON-Code geschrieben werden, um dasselbe Ergebnis zu erhalten: de'f.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "languageVersion": "2.0",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "forceUpdateTag": {
      "type": "string",
      "defaultValue": "[newGuid()]"
    }
  },
  "variables": {
    "deploymentScriptSharedProperties": {
      "forceUpdateTag": "[parameters('forceUpdateTag')]",
      "azPowerShellVersion": "10.1",
      "retentionInterval": "P1D"
    }
  },
  "resources": {
    "escapingTest": {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "escapingTest",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "properties": "[union(variables('deploymentScriptSharedProperties'), createObject('scriptContent', '$DeploymentScriptOutputs = @{}; $DeploymentScriptOutputs.escaped = \"de''f\";'))]"
    }
  },
  "outputs": {
    "scriptOutput": {
      "type": "string",
      "value": "[reference('escapingTest').outputs.escaped]"
    }
  }
}

Beim Übergeben von Parameterwerten hängt die Verwendung von Escapezeichen davon ab, wo der Parameterwert angegeben wird. Wenn Sie in der Vorlage einen Standardwert festlegen, benötigen Sie die zusätzliche linke eckige Klammer.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "demoParam1": {
      "type": "string",
      "defaultValue": "[[test value]"
    }
  },
  "resources": [],
  "outputs": {
    "exampleOutput": {
      "type": "string",
      "value": "[parameters('demoParam1')]"
    }
  }
}

Wenn Sie den Standardwert verwenden, gibt die Vorlage [test value] zurück.

Wenn Sie jedoch einen Parameterwert über die Befehlszeile übergeben, werden die Zeichen buchstäblich interpretiert. Das Bereitstellen der vorherigen Vorlage mit:

New-AzResourceGroupDeployment -ResourceGroupName demoGroup -TemplateFile azuredeploy.json -demoParam1 "[[test value]"

Gibt [[test value] zurück. Verwenden Sie stattdessen:

New-AzResourceGroupDeployment -ResourceGroupName demoGroup -TemplateFile azuredeploy.json -demoParam1 "[test value]"

Die gleiche Formatierung gilt auch, wenn Werte aus einer Parameterdatei übergeben werden. Die Zeichen werden buchstäblich interpretiert. Bei Verwendung mit der vorherigen Vorlage gibt die folgende Parameterdatei [test value] zurück:

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

NULL-Werte

Zur Festlegung einer Eigenschaft auf NULL, können Sie null oder [json('null')] verwenden. Die json-Funktion gibt ein leeres Objekt zurück, wenn Sie null als Parameter angeben. In beiden Fällen wird dies von Resource Manager-Vorlagen so behandelt, als ob die Eigenschaft nicht vorhanden ist.

"stringValue": null,
"objectValue": "[json('null')]"

Um ein Element vollständig zu entfernen, können Sie die Filter ()-Funktion verwenden. Beispiel:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "deployCaboodle": {
      "type": "bool",
      "defaultValue": false
    }
  },
  "variables": {
    "op": [
      {
        "name": "ODB"
      },
      {
        "name": "ODBRPT"
      },
      {
        "name": "Caboodle"
      }
    ]
  },
  "resources": [],
  "outputs": {
    "backendAddressPools": {
      "type": "array",
      "value": "[if(parameters('deployCaboodle'), variables('op'), filter(variables('op'), lambda('on', not(equals(lambdaVariables('on').name, 'Caboodle')))))]"
    }
  }
}

Nächste Schritte