Syntaxe a výrazy v šablonách ARM

  • Článek

Základní syntaxe šablony Azure Resource Manageru (šablona ARM) je JavaScript Object Notation (JSON). Výrazy ale můžete použít k rozšíření hodnot JSON dostupných v rámci šablony. 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í překročit 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() ve výrazu volá jednu z funkcí, které Resource Manager poskytuje pro použití v rámci šablony. V tomto případě se jedná o funkci resourceGroup . Stejně jako v JavaScriptu se volání funkcí formátují jako functionName(arg1,arg2,arg3). Syntaxe .location načte jednu vlastnost z objektu vráceného danou funkcí.

Funkce šablony a jejich parametry nerozlišují malá a velká písmena. Resource Manager se například vyřeší variables('var1') a VARIABLES('VAR1') bude stejný. Při vyhodnocování, pokud funkce výslovně modifikuje malá a velká písmena (například toUpper nebo toLower), funkce zachová velikost písmen. 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 hodnotu řetězce 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í na základě rozsahu:

  • resourceGroup – lze použít pouze 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

Chcete-li mít literální řetězec začínající levou závorkou [ a končit pravou závorkou , ale nemá ji interpretovat jako výraz, přidejte další hranatou závorku ]pro zahájení řetězce s [[. Například proměnná:

"demoVar1": "[[test value]"

Přeloží na [test value].

Pokud ale řetězec literálu nekončí hranatými závorkami, neucházejte z první hranaté závorky. Například proměnná:

"demoVar2": "[test] value"

Přeloží na [test] value.

Chcete-li uvozovat dvojité uvozovky ve výrazu, například přidání objektu JSON v šabloně, použijte zpětné lomítko.

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

Pokud chcete uvozovat jednoduché uvozovky ve výstupu výrazu ARM, zdvojte jednoduché uvozovky. 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 jsou v rámci výrazu dvojité řídicí hodnoty. Z scriptOutput následující šablony 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]"
    }
  }
}

U languageVersion 2.0 je dvojitý řídicí znak déle nutný. Předchozí příklad lze zapsat jako následující JSON, aby se získal 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 zadaná hodnota parametru. Pokud v šabloně nastavíte výchozí hodnotu, budete potřebovat 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, šablona vrátí [test value].

Pokud však předáte hodnotu parametru přes příkazový řádek, znaky se interpretují doslova. 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 doslova. 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 nimi šablony Resource Manageru zachází, jako by vlastnost nebyla k dispozici.

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

K úplnému odebrání prvku 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