Syntax och uttryck i ARM-mallar

  • Artikel

Den grundläggande syntaxen för Azure Resource Manager-mallen (ARM-mall) är JavaScript Object Notation (JSON). 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 den funktionen.

Mallfunktioner och deras parametrar är skiftlägeskänsliga. Resource Manager löser variables('var1') till exempel 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 är separata 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 de giltiga parametrarna ändras beroende på omfånget.
  • prenumeration – kan endast användas i distributioner till en resursgrupp eller prenumeration.

Escape-tecken

Om du vill att en literalsträng ska börja med en vänster hakparentes [ och avsluta 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 literalsträngen 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 omvänt snedstreck.

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

Om du vill undvika enkla citattecken i ett 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 dubbelutrymningsvä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 behövs double-escape längre. 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 du skickar in parametervärden 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 den tidigare mallen 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 det som om egenskapen inte finns.

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

Om du vill ta bort ett element helt kan du använda funktionen filter(). Till 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