Szintaxis és kifejezések ARM-sablonokban

  • Cikk

Az Azure Resource Manager sablon (ARM-sablon) alapszintaxisa a JavaScript Object Notation (JSON). Kifejezések használatával azonban kiterjesztheti a sablonban elérhető JSON-értékeket. A kifejezések szögletes zárójellel kezdődnek és végződnek: [ és ]. A kifejezés értékét a rendszer a sablon üzembe helyezésekor értékeli ki. A kifejezés lehet sztring, egész szám, logikai érték, tömb vagy objektum.

A sablonkifejezések legfeljebb 24 576 karakter hosszúságúak lehetnek.

Függvények használata

Az Azure Resource Manager a sablonban használható függvényeket biztosít. Az alábbi példa egy olyan kifejezést mutat be, amely egy paraméter alapértelmezett értékében egy függvényt használ:

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

A kifejezésben a szintaxis resourceGroup() meghívja az egyik függvényt, amelyet Resource Manager biztosít a sablonban való használatra. Ebben az esetben ez a resourceGroup függvény. A JavaScripthez hasonlóan a függvényhívások is a következő formátumban functionName(arg1,arg2,arg3)vannak formázva: . A szintaxis .location egy tulajdonságot kér le a függvény által visszaadott objektumból.

A sablonfüggvények és paramétereik nem különböztetik meg a kis- és nagybetűket. Például a Resource Manager feloldja variables('var1')VARIABLES('VAR1') és ugyanúgy. A kiértékeléskor, kivéve, ha a függvény kifejezetten módosítja a kis- és nagybetűket (például toUpper vagy toLower), a függvény megőrzi az esetet. Bizonyos erőforrástípusoknak lehetnek olyan esetkövetelményei, amelyek eltérnek a függvények kiértékelésének módjától.

Ha egy sztringértéket paraméterként szeretne átadni egy függvénynek, használjon szimpla idézőjeleket.

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

A legtöbb függvény ugyanúgy működik, függetlenül attól, hogy egy erőforráscsoportban, előfizetésben, felügyeleti csoportban vagy bérlőben vannak üzembe helyezve. Az alábbi függvények hatókörön alapuló korlátozásokkal rendelkeznek:

  • resourceGroup – csak erőforráscsoport üzemelő példányaiban használható.
  • resourceId – bármely hatókörben használható, de az érvényes paraméterek a hatókörtől függően változnak.
  • előfizetés – csak erőforráscsoportban vagy előfizetésben üzemelő példányokban használható.

Escape-karakterek

Ha egy literális sztring bal oldali szögletes zárójelmel kezdődik, és jobb oldali szögletes [ zárójelmel ]végződik, de nem értelmezi kifejezésként, adjon hozzá egy további szögletes zárójelet a sztring elindításához a következővel [[: . Például a változó:

"demoVar1": "[[test value]"

A feloldása: [test value].

Ha azonban a literális sztring nem szögletes zárójelmel végződik, ne meneküljön ki az első szögletes zárójelből. Például a változó:

"demoVar2": "[test] value"

A feloldása: [test] value.

Ha meg szeretne szabadulni egy kifejezésben szereplő dupla idézőjelek elől, például JSON-objektumot ad hozzá a sablonhoz, használja a fordított perjelet.

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

Ha egyetlen idézőjelet szeretne feloldani egy ARM-kifejezés kimenetében, duplázza meg az egyszeres idézőjeleket. A következő sablon kimenete JSON-értéket {"abc":"'quoted'"}eredményez.

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

Az erőforrás-definícióban a kifejezésen belüli dupla feloldási értékek. A scriptOutput következő sablonból a következő: 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]"
    }
  }
}

A languageVersion 2.0 esetén a dupla feloldás hosszabb ideig szükséges. Az előző példa a következő JSON-fájlként írható, hogy ugyanazt az eredményt kapja: 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]"
    }
  }
}

Paraméterértékek megadásakor a feloldókarakterek használata attól függ, hogy hol van megadva a paraméterérték. Ha beállít egy alapértelmezett értéket a sablonban, szüksége lesz a további bal oldali szögletes zárójelre.

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

Ha az alapértelmezett értéket használja, a sablon a következőt adja [test value]vissza: .

Ha azonban paraméterértéket ad meg a parancssoron keresztül, a karaktereket szó szerint értelmezi a rendszer. Az előző sablon üzembe helyezése a következőkkel:

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

A értéket adja [[test value]vissza. Ehelyett alkalmazza a következő módszert:

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

Ugyanez a formázás érvényes, amikor értékeket ad át egy paraméterfájlból. A karaktereket szó szerint értelmezi a rendszer. Az előző sablonnal való használat esetén a következő paraméterfájl ad [test value]vissza:

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

Null-értékek

Ha egy tulajdonságot null értékre szeretne beállítani, használja a következőket: null vagy [json('null')]. A json függvény üres objektumot ad vissza, ha paraméterként adja meg null . Mindkét esetben Resource Manager sablonok úgy kezelik, mintha a tulajdonság nem lenne jelen.

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

Egy elem teljes eltávolításához használhatja a filter() függvényt. Például:

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

Következő lépések