Syntaxe a výrazy v šablonách ARM

  • Článek

Základní syntaxí šablony Azure Resource Manager (šablona ARM) je JavaScript Object Notation (JSON). K rozšíření hodnot JSON dostupných v šabloně ale můžete použít výrazy. Výrazy začínají a končí závorkami [ a ] v uvedeném pořadí. Hodnota výrazu se vyhodnocuje po nasazení šablony. Výraz může vrátit řetězec, celé číslo, logickou hodnotu, pole nebo objekt.

Výraz šablony nesmí být delší než 24 576 znaků.

Použití funkcí

Azure Resource Manager poskytuje funkce, které můžete použít v šabloně. Následující příklad ukazuje výraz, který používá funkci ve výchozí hodnotě parametru:

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

Syntaxe resourceGroup() v rámci výrazu volá jednu z funkcí, které Resource Manager umožňuje použití v šabloně. V tomto případě je to funkce resourceGroup . Stejně jako v JavaScriptu jsou volání funkcí formátovaná jako functionName(arg1,arg2,arg3). Syntaxe .location načte jednu vlastnost z objektu vráceného danou funkcí.

Funkce šablon a jejich parametry nerozlišují malá a velká písmena. Například Resource Manager se přeloží variables('var1') a VARIABLES('VAR1') stejně. Pokud funkce výslovně nemodifikuje malá a velká písmena (například toUpper nebo toLower), zachová při vyhodnocování malá a velká písmena. Některé typy prostředků můžou mít požadavky na případ, které jsou oddělené od způsobu vyhodnocování funkcí.

Pokud chcete funkci předat řetězcovou hodnotu jako parametr, použijte jednoduché uvozovky.

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

Většina funkcí funguje stejně bez ohledu na to, jestli jsou nasazené do skupiny prostředků, předplatného, skupiny pro správu nebo tenanta. Následující funkce mají omezení v závislosti na rozsahu:

  • resourceGroup – dá se použít jenom v nasazeních do skupiny prostředků.
  • resourceId – lze použít v libovolném oboru, ale platné parametry se mění v závislosti na oboru.
  • předplatné – dá se použít jenom v nasazeních do skupiny prostředků nebo předplatného.

Řídicí znaky

Pokud chcete, aby literálový řetězec začínal levou závorkou a končil pravou závorkou [], ale neinterpretoval se jako výraz, přidejte další závorku, která začne řetězcem [[. Například proměnná:

"demoVar1": "[[test value]"

Přeloží se na [test value].

Pokud ale řetězec literálu nekončí hranatou závorkou, neuchovávejte první hranatou závorku. Například proměnná:

"demoVar2": "[test] value"

Přeloží se na [test] value.

Pokud chcete ve výrazu uvozovat dvojité uvozovky, jako je například přidání objektu JSON do šablony, použijte zpětné lomítko.

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

Pokud chcete ve výstupu výrazu ARM uvozovat jednoduché uvozovky, zdvojte jednoduché uvozovky nahoru. Výstup následující šablony má za následek hodnotu {"abc":"'quoted'"}JSON .

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

V definici prostředku použijte dvojité řídicí hodnoty ve výrazu. Následující scriptOutput šablona je 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]"
    }
  }
}

S languageVersion 2.0, double-escape je na déle potřebné. Předchozí příklad je možné zapsat jako následující json a získat tak stejný výsledek: 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]"
    }
  }
}

Při předávání hodnot parametrů závisí použití řídicích znaků na tom, kde je hodnota parametru zadaná. Pokud v šabloně nastavíte výchozí hodnotu, potřebujete další levou závorku.

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

Pokud použijete výchozí hodnotu, vrátí [test value]šablona .

Pokud ale hodnotu parametru předáte prostřednictvím příkazového řádku, znaky se interpretují doslovně. Nasazení předchozí šablony pomocí:

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

Vrací objekt [[test value]. Postupujte takto:

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

Stejné formátování platí při předávání hodnot ze souboru parametrů. Znaky jsou interpretovány doslovně. Při použití s předchozí šablonou vrátí [test value]následující soubor parametrů :

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

Hodnoty Null

Pokud chcete nastavit vlastnost na hodnotu null, můžete použít null nebo [json('null')]. Funkce json vrátí prázdný objekt, když zadáte null jako parametr . V obou případech s ní šablony Resource Manager nakládají, jako by vlastnost nebyla k dispozici.

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

Pokud chcete prvek úplně odebrat, můžete použít funkci filter(). Příklad:

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

Další kroky