Delen via

Syntaxis en expressies in ARM-sjablonen

  • Artikel

De basissyntaxis van de Azure Resource Manager-sjabloon (ARM-sjabloon) is JavaScript Object Notation (JSON). U kunt echter expressies gebruiken om de JSON-waarden uit te breiden die beschikbaar zijn in de sjabloon. Expressies staan respectievelijk tussen de vierkante haken [ en ]. De waarde van de expressie wordt geëvalueerd als de sjabloon wordt geïmplementeerd. Een expressie kan een tekenreeks, een geheel getal, een booleaanse waarde of een object retourneren.

Een sjabloonexpressie mag niet langer zijn dan 24.576 tekens.

Functies gebruiken

Azure Resource Manager biedt functies die u in een sjabloon kunt gebruiken. In het volgende voorbeeld ziet u een expressie die gebruikmaakt van een functie in de standaardwaarde van een parameter:

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

Binnen de expressie roept de syntaxis resourceGroup() een van de functies aan die Resource Manager biedt voor gebruik binnen een sjabloon. In dit geval is dit de resourceGroup-functie . Net als in JavaScript worden functie-aanroepen opgemaakt als functionName(arg1,arg2,arg3). Met de syntaxis .location wordt één eigenschap opgehaald uit het object dat door die functie wordt geretourneerd.

Sjabloonfuncties en hun parameters zijn niet hoofdlettergevoelig. Resource Manager wordt bijvoorbeeld omgezet variables('var1') en VARIABLES('VAR1') hetzelfde. Wanneer deze wordt geëvalueerd, tenzij de functie uitdrukkelijk case wijzigt (zoals toUpper of toLower), behoudt de functie de case. Bepaalde resourcetypen kunnen casevereisten hebben die gescheiden zijn van de wijze waarop functies worden geëvalueerd.

Als u een tekenreekswaarde als parameter wilt doorgeven aan een functie, gebruikt u enkele aanhalingstekens.

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

De meeste functies werken hetzelfde, ongeacht of ze zijn geïmplementeerd in een resourcegroep, abonnement, beheergroep of tenant. De volgende functies hebben beperkingen op basis van het bereik:

  • resourceGroup : kan alleen worden gebruikt in implementaties voor een resourcegroep.
  • resourceId : kan worden gebruikt voor elk bereik, maar de geldige parameters veranderen, afhankelijk van het bereik.
  • abonnement : kan alleen worden gebruikt in implementaties voor een resourcegroep of abonnement.

Escapetekens

Als u een letterlijke tekenreeks wilt laten beginnen met een vierkante haak links en eindigt met een rechterhaak [ ], maar deze niet als een expressie hebt geïnterpreteerd, voegt u een extra haak toe om de tekenreeks met [[te starten. Bijvoorbeeld de variabele:

"demoVar1": "[[test value]"

Wordt omgezet in [test value].

Als de letterlijke tekenreeks echter niet eindigt op een haak, ontsnap dan niet aan de eerste haak. Bijvoorbeeld de variabele:

"demoVar2": "[test] value"

Wordt omgezet in [test] value.

Als u dubbele aanhalingstekens in een expressie wilt ontsnappen, zoals het toevoegen van een JSON-object in de sjabloon, gebruikt u de backslash.

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

Als u enkele aanhalingstekens in een UITVOER van een ARM-expressie wilt ontsnappen, dubbelt u de enkele aanhalingstekens. De uitvoer van de volgende sjabloon resulteert in JSON-waarde {"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''')]"
    }
  }
}

In de resourcedefinitie dubbel escape-waarden binnen een expressie. De scriptOutput van de volgende sjabloon is 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]"
    }
  }
}

Met languageVersion 2.0 is double-escape langer nodig. Het voorgaande voorbeeld kan worden geschreven als de volgende JSON om hetzelfde resultaat te krijgen. 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]"
    }
  }
}

Wanneer u parameterwaarden doorgeeft, is het gebruik van escape-tekens afhankelijk van waar de parameterwaarde is opgegeven. Als u een standaardwaarde in de sjabloon instelt, hebt u de extra vierkante haak links nodig.

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

Als u de standaardwaarde gebruikt, retourneert [test value]de sjabloon.

Als u echter een parameterwaarde doorgeeft via de opdrachtregel, worden de tekens letterlijk geïnterpreteerd. De vorige sjabloon implementeren met:

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

Retourneert [[test value]. Gebruik in plaats daarvan:

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

Dezelfde opmaak is van toepassing bij het doorgeven van waarden uit een parameterbestand. De tekens worden letterlijk geïnterpreteerd. Wanneer het met de voorgaande sjabloon wordt gebruikt, retourneert [test value]het volgende parameterbestand:

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

Null-waarden

U kunt null of [json('null')] gebruiken om een eigenschap in te stellen op nul. De json-functie retourneert een leeg object wanneer u opgeeft null als de parameter. In beide gevallen behandelen Resource Manager-sjablonen deze alsof de eigenschap niet aanwezig is.

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

Als u een element volledig wilt verwijderen, kunt u de functie filter() gebruiken. Voorbeeld:

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

Volgende stappen