Syntax och uttryck i ARM-mallar

  • Artikel

Den grundläggande syntaxen för Azure Resource Manager-mallen (ARM-mall) är JSON (JavaScript Object Notation). Du kan dock använda uttryck för att utöka de JSON-värden som är tillgängliga i mallen. Uttryck börjar och slutar med hakparenteser: [ respektive ]. Uttryckets värde utvärderas när mallen distribueras. Ett uttryck kan returnera en sträng, ett heltal, ett booleskt värde, en matris eller ett objekt.

Ett malluttryck får inte överstiga 24 576 tecken.

Använda funktioner

Azure Resource Manager innehåller funktioner som du kan använda i en mall. I följande exempel visas ett uttryck som använder en funktion i standardvärdet för en parameter:

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

I uttrycket anropar syntaxen resourceGroup() en av de funktioner som Resource Manager tillhandahåller för användning i en mall. I det här fallet är det funktionen resourceGroup . Precis som i JavaScript formateras funktionsanrop som functionName(arg1,arg2,arg3). Syntaxen .location hämtar en egenskap från objektet som returneras av funktionen.

Mallfunktioner och deras parametrar är skiftlägesokänsliga. Till exempel löser variables('var1') Resource Manager och VARIABLES('VAR1') på samma sätt. När den utvärderas, såvida inte funktionen uttryckligen ändrar skiftläge (till exempel toUpper eller toLower), bevarar funktionen ärendet. Vissa resurstyper kan ha skiftlägeskrav som skiljer sig från hur funktioner utvärderas.

Om du vill skicka ett strängvärde som en parameter till en funktion använder du enkla citattecken.

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

De flesta funktioner fungerar på samma sätt oavsett om de distribueras till en resursgrupp, prenumeration, hanteringsgrupp eller klientorganisation. Följande funktioner har begränsningar baserat på omfånget:

  • resourceGroup – kan bara användas i distributioner till en resursgrupp.
  • resourceId – kan användas i valfritt omfång, men giltiga parametrar ändras beroende på omfånget.
  • prenumeration – kan endast användas i distributioner till en resursgrupp eller prenumeration.

Escape-tecken

Om du vill att en strängliteral ska börja med en vänster hakparentes [ och sluta med en höger hakparentes ], men inte tolka den som ett uttryck, lägger du till en extra hakparentes för att starta strängen med [[. Till exempel variabeln:

"demoVar1": "[[test value]"

Löser till [test value].

Men om strängliteralen inte slutar med en hakparentes ska du inte ta bort den första hakparentesen. Till exempel variabeln:

"demoVar2": "[test] value"

Löser till [test] value.

Om du vill undvika dubbla citattecken i ett uttryck, till exempel lägga till ett JSON-objekt i mallen, använder du det omvända snedstrecket.

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

Om du vill undvika enkla citattecken i arm-uttrycksutdata, dubblar du de enkla citattecknarna. Utdata från följande mall resulterar i JSON-värdet {"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''')]"
    }
  }
}

I resursdefinitionen dubbla escape-värden i ett uttryck. Från scriptOutput följande mall är 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]"
    }
  }
}

Med languageVersion 2.0 är double-escape på längre tid. Föregående exempel kan skrivas som följande JSON för att få samma resultat, 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]"
    }
  }
}

När parametervärden skickas beror användningen av escape-tecken på var parametervärdet anges. Om du anger ett standardvärde i mallen behöver du den extra vänstra hakparentesen.

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

Om du använder standardvärdet returnerar [test value]mallen .

Men om du skickar in ett parametervärde via kommandoraden tolkas tecknen bokstavligen. Distribuera föregående mall med:

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

Returnerar [[test value]. Använd i stället:

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

Samma formatering gäller när du skickar in värden från en parameterfil. Tecknen tolkas bokstavligen. När den används med föregående mall returnerar [test value]följande parameterfil :

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

Null-värden

Om du vill ange en egenskap till null kan du använda null eller [json('null')]. JSON-funktionen returnerar ett tomt objekt när du anger null som parameter. I båda fallen behandlar Resource Manager mallar den som om egenskapen inte finns.

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

Om du vill ta bort ett element helt kan du använda funktionen filter(). Exempel:

{
  "$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ästa steg