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 die beschikbaar zijn in de sjabloon uit te breiden. 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 in een sjabloon. In dit geval is dit de functie resourceGroup . Net als in JavaScript worden functie-aanroepen opgemaakt als functionName(arg1,arg2,arg3). De syntaxis .location haalt één eigenschap op uit het object dat door die functie wordt geretourneerd.

Sjabloonfuncties en hun parameters zijn niet hoofdlettergevoelig. Resource Manager wordt bijvoorbeeld en als hetzelfde opgelost variables('var1')VARIABLES('VAR1'). Wanneer de functie wordt geëvalueerd, blijft de case behouden, tenzij de functie hoofdletters en kleine letters (zoals toUpper of toLower) uitdrukkelijk wijzigt. Bepaalde resourcetypen kunnen casevereisten hebben die los staan 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 worden 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 naar 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 naar een resourcegroep of abonnement.

Escapetekens

Als u een letterlijke tekenreeks wilt laten beginnen met een vierkante haak [ links en eindigt op een vierkante haak ]rechts, maar deze niet wilt interpreteren als een expressie, voegt u een extra haak toe om de tekenreeks te beginnen met [[. Bijvoorbeeld de variabele:

"demoVar1": "[[test value]"

Wordt omgezet in [test value].

Als de letterlijke tekenreeks echter niet eindigt op een vierkante haak, moet u niet ontsnappen aan de eerste haak. Bijvoorbeeld de variabele:

"demoVar2": "[test] value"

Wordt omgezet in [test] value.

Als u dubbele aanhalingstekens in een expressie wilt verwijderen, 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 de uitvoer van een ARM-expressie wilt ontsnappen, verdubbelt 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 dubbele escape-waarden in 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 dubbele 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]"
    }
  }
}

Bij het doorgeven van parameterwaarden is het gebruik van escape-tekens afhankelijk van waar de parameterwaarde is opgegeven. Als u een standaardwaarde instelt in de sjabloon, 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. Bij gebruik met de voorgaande sjabloon 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 het alsof de eigenschap niet aanwezig is.

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

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

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